Skip to content

engagement-codex plugin

The Engagement Codex renderer — it turns an engagement's graph state into the three documents an engagement runs on:

Document Skill What it is Whose hands it belongs in
Solution Thesis solution-thesis-render the executive story — evidence, readiness verdict, recommendation — in four audience tones any seller — the SE, and just as deliberately the AE. It puts a confident, evidence-backed architecture story in the hands of sellers who will never build one themselves — the seller does not have to become an architect to carry the architecture
Statement of Work sow-render the procurement-grade contract — outcomes, deliverables, acceptance, terms; a contractual PRD the deal's contracting seller — Salesforce Professional Services or a GSI partner selling the delivery itself
Spec Manifest spec-manifest-render the delivery plan humans and agents execute — epics, sprints, work packets, gates the delivery team — ProfServ or GSI, an increasingly small human core working alongside the agents compressing the work; Salesforce FDEs slot in as the accelerant that gets that team started fast

Read down the table and a baton passes: from the seller who must carry architecture without being an architect, to the organization contracting the delivery, to the team — human and agent — that executes it. Each document is the previous one's promise made more binding, and the same governed graph state stands behind all three.

Everything is rendered, not authored (ADR-PA-009): the plugin projects canonical engagement graph state — Context Artifacts, DecisionTraces, the eleven-dimension readiness verdict — and never writes it. When the graph changes, render again and the documents follow. Hand-edits to graph-derived sections are deliberately discarded on re-render; the designated human-authored sections (the seller's §1 prose, the SOW's commercial terms and signatures) are preserved across supersession.

Quick start (Claude Code):

/engagement-codex:solution-thesis-render <engagement-key> [--tone audit|seller|customer|leadership]
/engagement-codex:sow-render <engagement-key> [--tone procurement|partner]
/engagement-codex:spec-manifest-render <engagement-key>

or via Make: make solution-thesis-render ENGAGEMENT=<key> [TONE=…] · make sow-render ENGAGEMENT=<key> [TONE=…] · make spec-manifest-render ENGAGEMENT=<key>. Full flags and the bundle-zip input form are under Invocation. (The old render-* command spellings remain as deprecated aliases for one release.)

  • Current release: plugin v0.9.0 — skills solution-thesis-render v0.6.0 · sow-render v0.0.1 · spec-manifest-render v0.1.0. Release notes: Version history.
  • Cowork bundle: engagement-codex-<version>.zip (regeneratable via make plugin-bundle-engagement-codex or make bundles). Leadership-tone rendering is Claude-Code-only pending a follow-up DT.

What this plugin is (and is not)

This plugin is the structural-rendering layer for the Engagement Codex. It takes engagement graph state (Phase 3 Context Artifacts, Phase 3 DecisionTraces, the eleven-dimension readiness verdict; Phase 4 PromotionCandidates) and produces the three-layer contracting stack — the Solution Thesis (canonical template at skills/solution-thesis-render/templates/solution-thesis.md), the Statement of Work, and the Spec Manifest — each honoring its skill's canonical template, section flags, and gap-marker inventory.

This plugin is not an authoring or analysis surface. It does not read dossiers, classify patterns, or write Cypher. It reads engagement graph state plus an optional Cowork-emitted thesis, and writes Markdown files at deterministic paths.

Sibling to rosetta-archaeology

The two plugins overlap on output category but not runtime:

  • rosetta-archaeology (Cowork plugin) — runs the Project Archaeology four-phase pipeline. v0.3.1 emits its own runtime-authored Solution Thesis at outputs/plugins/rosetta-archaeology/<engagementKey>/seller/solution-thesis.md. The runtime authors high-quality rhetorical content but rejects structural template specifications (no per-section rendered: flags, no §4 Mermaid diagram, no «TBD-N» inventory; runtime-authored 10-section structure replacing the 11-section template). This is the empirically refined selective procedural adherence finding documented in docs/decision-traces/e3s4wp1-archaeology-v0.3.0-implementation.md.
  • engagement-codex (this plugin) — runs in Claude Code. The SKILL.md procedure walks the canonical 11-section template, extracts per the rules in references/extraction-rules.md, emits «TBD-N» markers per references/tbd-numbering.md, generates the §4 Mermaid diagram per references/mermaid-composition.md, and applies the defensive-parser contract per references/defensive-parser.md.

Both plugin outputs coexist as siblings under different plugin namespaces (per Q-3.B of the design DT). The engagement-codex output is the canonical seller-facing thesis; the rosetta-archaeology output is the runtime's rhetorical contribution, which the engagement-codex skill consumes as input for the rendered: false §1 Future Announcement section.

The four tones (v0.5.0; audience routing v0.9.0)

Audience map (Q-5.A; v0.9.0 — E3-S4-WP15). Per the design DT engagement-codex-narrative-pass.md (RATIFIED 2026-06-11), the four tones route to explicit audiences — audit → internal / reviewer only (the internal diagnostic surface; never hand an audit render to an AE/SE or a customer); seller → AE/SE working document; customer → customer deliverable; leadership → decision room. After every audit render the report reminds: audit tone is the internal diagnostic surface — render --tone seller for an AE/SE handoff. The audit render's bytes are unchanged at v0.9.0; the three human-facing tones get the narrative Pass 2 + conformance lint per references/narrative-style.md.

Tone Audience (Q-5.A routing) Template Gap discipline (Pass 1; Pass 2 converts to named asks in human tones) Front matter Output path
audit (default) Internal / reviewer only (Gate 3 partner-architect; internal diagnostic surface) templates/solution-thesis.md (12 sections) «TBD-N» + closing inventory visible YAML .../seller/solution-thesis.md (v0.1.0 canonical)
seller AE/SE working document (SC / account team prep) templates/solution-thesis.md [from NTO: <description>] inline (no inventory); Pass 2 → named asks + consolidated box HTML-commented .../seller/solution-thesis.seller.md
customer Customer deliverable (executive sponsor) templates/solution-thesis.md HARD FAIL on any gap absent .../seller/solution-thesis.customer.md
leadership (NEW v0.5.0) Decision room (leadership / account-team decision brief) templates/solution-thesis-leadership.md (11-section human-facing spine) «to confirm» + section-11 consolidated table; Pass 2 → named asks + consolidated box HTML-commented .../leadership/solution-thesis.leadership.md

The audit / seller / customer trio coexist as sibling files in .../seller/; audit-tone preserves the v0.1.0 canonical path. The leadership tone lives in its own .../leadership/ subdirectory (isolated from the seller-room trio per Q-1.A v0.5.0). See the design DTs for the full Q-1.A through Q-8.A rationale at v0.2.0, the Q-1.A through Q-6.A rationale at v0.3.0, and the Q-1.A through Q-8.A rationale at v0.5.0 (leadership tone).

Invocation

Slash command (interactive)

Inside Claude Code:

/engagement-codex:solution-thesis-render <engagement-key>
/engagement-codex:solution-thesis-render <engagement-key> --tone seller
/engagement-codex:solution-thesis-render <engagement-key> --tone customer
/engagement-codex:solution-thesis-render <engagement-key> --tone leadership
/engagement-codex:solution-thesis-render <path-to-bundle-zip>
/engagement-codex:solution-thesis-render <path-to-bundle-zip> --tone seller
/engagement-codex:solution-thesis-render <path-to-bundle-zip> --tone leadership

The first form resolves inputs from outputs/plugins/rosetta-archaeology/<engagementKey>/ (Cowork bundle output already extracted) AND db/engagements/<engagementKey>/ (the engagement Cypher trio). The bundle-zip form extracts to a scratch directory and reads from there. The --tone flag is optional; defaults to audit if absent. The leadership tone (v0.5.0) is Claude-Code-only; leadership-tone Cowork enablement is deferred to a v0.5.x follow-up DT.

Make target (CI / scripting / non-interactive)

# Render from a Cowork bundle zip (audit tone by default):
make solution-thesis-render BUNDLE=/path/to/rosetta-archaeology-<eng>-runall-<ts>.zip

# Render audit tone explicitly (equivalent to default):
make solution-thesis-render ENGAGEMENT=nto-01 TONE=audit

# Render seller tone (for SC preparation):
make solution-thesis-render ENGAGEMENT=nto-01 TONE=seller

# Render customer tone (for customer-facing handout; HARD FAILS if any gap exists):
make solution-thesis-render ENGAGEMENT=nto-01 TONE=customer

# Render leadership tone (v0.5.0; human-facing decision-brief spine):
make solution-thesis-render ENGAGEMENT=nto-01 TONE=leadership

# Cypher-trio-only render (force-skip Cowork §1 input):
make solution-thesis-render ENGAGEMENT=nto-01 NO_COWORK_INPUT=1

# Hard-fail if the Cowork-emitted thesis is missing:
make solution-thesis-render ENGAGEMENT=nto-01 REQUIRE_COWORK_INPUT=1

Both invocations dispatch to the same SKILL.md procedure and produce identical output at the same per-tone path.

Typical SC workflow

# 1. Initial audit-tone render (governance baseline):
make solution-thesis-render ENGAGEMENT=nto-01

# 2. Seller-tone render for SC prep:
make solution-thesis-render ENGAGEMENT=nto-01 TONE=seller

# 3. Hand-edit solution-thesis.seller.md to resolve [from NTO: ...]
#    placeholders with customer-side data as it surfaces in
#    discovery / alignment sessions.

# 4. Customer-tone render attempt (succeeds only when all gaps resolved):
make solution-thesis-render ENGAGEMENT=nto-01 TONE=customer

# 5. Leadership-tone render for leadership / account-team decision brief
#    (v0.5.0; absence-tolerant, never HARD FAILS):
make solution-thesis-render ENGAGEMENT=nto-01 TONE=leadership

The customer-tone HARD FAIL surfaces missing data points explicitly — its stderr message names each missing field + its corresponding seller-tone [from NTO: ...] placeholder for remediation. The leadership tone (v0.5.0) takes a different posture: missing inputs render partial-with-WARNING rather than HARD FAIL, surfacing four absence-tolerant MANIFEST WARNING categories (leadership-gloss-missing, decision-brief-partial, leadership-evidence-fallback, verdict-qualifier-partial) so the reviewer can iterate the engagement Cypher + re-render without blocking on first-pass gaps.

Input/output contract

Inputs (hybrid; per Q-2.C of the design DT)

The skill prefers Cowork-bundle input when available, falls back to the engagement Cypher trio when not:

Path Source Required
db/engagements/<engagementKey>/00-domain.cypher engagement leaf KnowledgeDomain yes
db/engagements/<engagementKey>/10-context-artifacts.cypher Phase 3 Context Artifacts yes
db/engagements/<engagementKey>/13-decision-traces.cypher Phase 3 DecisionTraces v1.3 yes
db/engagements/<engagementKey>/14-promotion-candidates.cypher Phase 4 PromotionCandidates optional (Phase 4 only)
outputs/plugins/rosetta-archaeology/<engagementKey>/research/classification-readiness-verdict.md Phase 3 eleven-dimension verdict yes
outputs/plugins/rosetta-archaeology/<engagementKey>/seller/solution-thesis.md Cowork runtime's rhetorical thesis optional (Q-2.C preferred)
outputs/plugins/rosetta-archaeology/<engagementKey>/research/survey-brief.md Phase 1 survey notes optional (fallback for §1 pre-staging)

Output (per resolved TONE; v0.2.0 / v0.5.0)

outputs/plugins/engagement-codex/<engagementKey>/
├── seller/
│   ├── solution-thesis.md             ← audit tone (default; v0.1.0 canonical path)
│   ├── solution-thesis.seller.md      ← seller tone
│   └── solution-thesis.customer.md    ← customer tone
└── leadership/                         ← NEW v0.5.0
    └── solution-thesis.leadership.md  ← leadership tone (11-section human-facing spine)

The audit / seller / customer trio coexist as sibling files in seller/. The leadership tone lives in its own leadership/ subdirectory (Q-1.A v0.5.0). Audit-tone path is unchanged from v0.1.0 (no regression for tooling that targets the canonical path).

The output coexists with the Cowork-emitted thesis at outputs/plugins/rosetta-archaeology/<engagementKey>/seller/solution-thesis.md (under a different plugin namespace). Both are first-class artifacts the seller can inspect; the engagement-codex outputs are the canonical seller-facing theses for SC prep + customer- side circulation.

§1 Future Announcement cross-tone propagation (Q-8.A)

The seller authors §1 Future Announcement prose once per engagement (typically against solution-thesis.seller.md). When re-rendering any other tone, the skill detects the seller's authored §1 prose and copies it forward — the same §1 prose appears across audit / seller / customer renders. Re-rendering audit-tone does NOT lose the seller's §1 authorship work. The rendered: false flag is preserved.

The defensive-parser contract operates per-file: hand-editing solution-thesis.seller.md does NOT affect the supersession behavior of solution-thesis.md (the audit-tone canonical) or solution-thesis.customer.md. Each tone-suffix file has its own supersession history.

Versioning

Derived from the input bundle's phaseStatus (per Q-5.C of the design DT):

  • phase3_classification: completed, phase4_preservation: pending → emit documentVersion: 0.1.0-draft
  • phase4_preservation: completed → emit documentVersion: 0.1.1-draft

Subsequent supersession runs append a row to §9 Document History and preserve the prior file at solution-thesis.md.bak.<timestamp> per the defensive-parser contract.

Constitutional alignment

The plugin operates within the rosetta-platform invariants (CLAUDE.md):

  • C-2 (Cypher canonical). The skill is read-only against db/engagements/<eng>/; it never authors Cypher.
  • C-4 (Make is the user surface). The skill is invokable via make solution-thesis-render in addition to the slash command; invocation does not bypass the Make surface.
  • C-5 (five-field identity). §0 Header extracts the leaf KnowledgeDomain five-field identity from 00-domain.cypher. The skill never authors identity.
  • C-7 (producer-only). The skill never references rosetta-app-server; the output is gitignored under outputs/ (ADR-PA-008).

Per ADR-PA-009, the rendered-not-authored discipline applies recursively to the seller-facing artifact: - rendered: true sections re-emit from graph state on every supersession; hand-edits are discarded. - rendered: false sections (§1 Future Announcement) are seller-authored and preserved across supersessions. - Front-matter schema drift is hard-FAIL.

See skills/solution-thesis-render/references/defensive-parser.md for the full contract.

No constitutional change

This plugin does not propose a new ADR. ADR-PA-009 already binds the seller-render category; engagement-codex is a second implementation under the same rule. The Constitutional and contract impact table at the end of the design DT confirms this.

Future-skills roadmap

The umbrella naming (engagement-codex) is intentional. Future versions add sibling skills under skills/:

  • v0.2.0 candidates (per the design DT §Follow-up):
  • architectural-advisory-render — subset of Solution Thesis for pre-SOW SC briefings.
  • --export-svg option for customer-presentation needs.
  • --hide-tbds flag for customer-facing PDF export.
  • v0.3.0 candidates:
  • pov-scope-render skill.
  • multi-engagement mode (single thesis spanning related engagements).
  • ADR promotion candidates (longer-term):
  • ADR-PA-010 (Solution Thesis as canonical Engagement Codex seller-facing layer) — formalize the 11-section template as constitutional rule after 3-5 engagements have exercised it. Premature at v0.1.0.
  • ADR-PA-011 (Claude Code skill discipline for derived producer-side artifacts) — generalize the SKILL.md-as-spec / Python-fallback pattern beyond seller renders if multiple plugins adopt it.

Python fallback (deferred)

Per Q-1.C of the design DT, if Claude Code adherence regresses across 2+ engagements (analogous to the Cowork selective-adherence finding), a Python implementation under util/python/solution_thesis_render/ becomes the fallback runtime. The SKILL.md remains the canonical specification; the Python implementation is a runtime substitute, not a parallel spec. The PR #66 parsers at util/python/archaeology_report/ are the schema oracle for that path.

v0.1.0 does not implement the Python fallback. The trigger is empirical: 2+ engagements showing adherence regression in Claude Code. The SKILL.md procedure is authored to maximize adherence (v0.9.1-style discipline: MUST / REJECTED / concrete templates) so the trigger should not fire on the first engagement.

Reporting issues

File against this repo. Include:

  • the engagement key,
  • the invocation (slash command or Make target),
  • whether Cowork-bundle input was present,
  • the resulting outputs/plugins/engagement-codex/<engagementKey>/seller/solution-thesis.md (or the MANIFEST.md WARNING / FAIL lines if the render did not complete),
  • the document-version line from the front matter (or its absence).

Governance record

  • Authorizing ADR: ADR-PA-009 (no amendment — engagement-codex is a second implementation under the same constitutional rule the rosetta-archaeology plugin already honors; TONE is a render-mode parameter under that rule; v0.3.0 template-shape changes operate under the same rule; v0.3.1 date-stamped-sibling is a pure write-also addition to Step 8.2; v0.4.0 Cowork deployment is a runtime-surface extension under the same rendered-not-authored discipline; v0.5.0 leadership-tone is the fourth audience layer under the same discipline).
  • Design DTs: engagement-codex-plugin-design.md (v0.1.0 scaffold, RATIFIED 2026-05-13) + engagement-codex-tone-parameter.md (v0.2.0 TONE parameter, RATIFIED 2026-05-13) + engagement-codex-seller-rhetorical-hardening.md (v0.3.0 four template-shape sections + two vocab classes, RATIFIED 2026-05-16) + engagement-codex-date-stamped-outputs.md (v0.3.1 date-stamped sibling, RATIFIED 2026-05-16) + engagement-codex-cowork-deployment.md (v0.4.0 Cowork deployment baseline — audit + seller tones; Q-1 through Q-6 ratified 2026-05-16; customer-tone Cowork enablement deferred to v0.4.1) + engagement-codex-leadership-tone.md (v0.5.0 fourth TONE value leadership — 11-section human-facing spine + synthesized Decision Brief + dt.leadershipGloss translation + consolidated placeholders; Q-1 through Q-8 ratified 2026-05-18) + engagement-codex-section-2-inheritance-scope.md (v0.5.1 DT-3 — leadership §2 inherits the three thesis-frame seller §1 sub-sections in narrative order; Option B) + engagement-codex-off-ramp-hardening-discipline.md (v0.5.1 DT-4 — §10 "to confirm" off-ramp body + §11.8 DRAFT block when upstream §5.5 is an unhardened placeholder; Option C) + engagement-codex-synthesis-first-rhetoric.md (v0.9.0 E3-S4-WP14 — §1/§2.0 drafted under guardrails with draftHash ratification gate; RATIFIED 2026-06-11) + engagement-codex-narrative-pass.md (v0.9.0 E3-S4-WP15 — narrative Pass 2 for human-facing tones, conformance lint, Q-5.A audience routing; RATIFIED 2026-06-11) + engagement-codex-live-graph-source.md (v0.9.0 E3-S4-WP17 — live-graph-first source resolution with loud degradation; RATIFIED 2026-06-11)
  • License: Proprietary — © 2026 Keenan Vision LLC (see the repo LICENSE)

Version history

Newest first; each entry preserves the full release notes.

v0.9.0

The humanization release. Three coordinated WPs against solution-thesis-render (sow-render and spec-manifest-render carry only the WP17 source-resolution language):

  • E3-S4-WP15 — narrative pass for human-facing tones (design DT engagement-codex-narrative-pass.md, RATIFIED 2026-06-11; Q-1.A / Q-2 / Q-3 / Q-4 / Q-5.A). Two-pass render, single invocation: Pass 1 is the deterministic render (audit tone IS Pass-1 output — byte-untouched); Pass 2 restructures the seller / customer / leadership output per the new references/narrative-style.md — executive summary first (what you asked for / what we found / are we ready with the verdict verbatim / what we need from you / next step), §0 plumbing + document history to a back-matter colophon, humanized section titles ("Are we ready? An eleven-point check"), ID exile extended to kgq-* / ap-* / evidence-class labels with a traceability appendix, gap tokens replaced by named asks + ONE consolidated "What we need from you" box (cost rows collapse to "costs are priced in the SOW"), CTA never blank ((proposed) defaults). A post-Pass-2 conformance lint (verdict byte-parity, off-ramp + commitment parity, no new numerals, traceability bidirectionality) gates the write; lint failure = MANIFEST FAIL + Pass-1 output emitted (fail-safe). Audience routing (Q-5.A): audit → internal/reviewer only; seller → AE/SE working document; customer → customer deliverable; leadership → decision room — see "The four tones" above.
  • E3-S4-WP14 — synthesis-first §1/§2.0 (design DT engagement-codex-synthesis-first-rhetoric.md). The renderer DRAFTS §1 Future Announcement and §2.0 Thesis Statement from the same run's §2.1/§3/§5 content under traceability/numeral/ verdict guardrails (template 0.4.0); draftHash ratification gate — editing IS ratifying (scaffold → drafted → authored, monotonic); degradation to scaffold + MANIFEST WARNING, never a silent generic paragraph.
  • E3-S4-WP17 — live-graph-first source resolution (design DT engagement-codex-live-graph-source.md). Source chain live → repo trio → bundle with --source override; loud degradation (live-engagement-bypassed WARNING + §0 colophon stamp); per-source-class freshness stamps; metamodelOverrideMode field map; since= supersession freshness.

Versioning: plugin.json → 0.9.0; solution-thesis-render SKILL.md → 0.6.0; marketplace entry → 0.9.0. The engagement-codex-0.9.0.zip bundle regen rides the release-cut pass.

v0.8.0

v0.8.0 is the ADR-RX-010 Phase D compile re-point — the release the v0.7.1 demotion promised ("spec-manifest-render re-points when DT-RX-010 Phases A-B ship"). Phases A-C shipped: platform ADR-PL-022 (delivery spine as engagement-twin graph data; INV-D28 gates the required purpose; 30-delivery-spine.cypher compiled from the overlay via make delivery-spine-compile), rosetta-app-server PR #156 (CompileManifestRequest gains engagementId — exactly one of projectId / engagementId — and an engagement-twin traversal), and rosetta-mcp-server v0.8.1 (the wrapper schema carries engagementId; OpenAPI 1.3.0). Authorized by the ratified engagement-codex-spec-manifest-compile-scope.md (§Ratification) + rosetta-meta ADR-RX-010; no new DT. Only spec-manifest-render changes (skill v0.1.0); solution-thesis-render and sow-render are byte-unchanged.

  • The re-point. On the live path with an engagementId, spec-manifest-render PREFERS the engagement-scoped rosetta_compile_spec_manifest — the server-side traversal of the spine + ContextArtifacts + forensic DecisionTraces + the 11-dimension readiness, every node's purpose included — and renders its nine-section projection from the compiled manifest content. The codex stays read-only (ADR-RX-002): the compile's server-side SpecManifest persistence is the SERVER writing its canonical projection under the producer's ProvenanceEvent discipline, not the codex writing the twin.
  • Spine-source order. The narrative-spine purpose: sources (1) the graph spine — compiled manifest or twin DeliveryWave/Epic/Sprint/WorkPacket nodes (INV-D28-gated); (2) db/engagements/<key>/30-delivery-spine.cypher on the file path; (3) delivery-overlay.yaml as the fallback. A missing purpose: from whichever source is live stays HARD FAIL exit 1 — never a WARNING (E3-S4-WP13).
  • Overlay deprecation window opens (ADR-PL-022). One cycle: both surfaces exist and must agree; the render prefers the graph spine and falls back to the overlay (the cp.icp coalesce shape); a follow-up WP lifts the fallback. The overlay drops from "MUST exist" to "MUST exist only when no graph spine is available."
  • Graceful degradation. The engagement-scoped compile requires servers at OpenAPI >= 1.3.0 (mcp-server >= v0.8.1). Older deployments lack the engagementId field on the wrapper; the render degrades to the v0.7.1 twin-read path (rosetta_get_engagement_twin + file inputs + kinds=-scoped recall) without erroring out. Eval id 4's "compile is never a render source" assertion is INVERTED accordingly.

v0.7.1

Superseded at v0.8.0: the compile demotion below was the interim posture; v0.8.0 re-points spec-manifest-render at the now-shipped engagement-scoped compile (see above). The twin-read corrections (include= / since= / kinds=) remain in force as the fallback path.

v0.7.1 is a documentation-and-eval patch binding the v0.7.0 live-twin-read text to the shipped wire contract (vendored OpenAPI v1.2.0: getEngagementTwin / recallEngagementMemory / compileSpecManifest). Ratified by two DTs (2026-06-10): engagement-codex-twin-read-contract.md and engagement-codex-spec-manifest-compile-scope.md. Renders are byte-identical — no template, tone, or section change.

  • include= never existed on rosetta_get_engagement_twin: the skills read the full TwinDocument and filter node types client-side.
  • since= is an int32 revision watermark (not a timestamp): each render persists the returned revision in its front-matter and passes it back on re-render for a delta read — delta presence/absence drives the defensive-parser supersession modes (graph-native supersession).
  • Memory recall is kinds=-scoped: a section-shaped q= with kinds=decision grounds rationale sections; kinds=gap grounds the «TBD-N» inventory in this engagement's KnowledgeGaps.
  • Compile demoted: rosetta_compile_spec_manifest is project-scoped (requires projectId; traverses the project twin; cannot carry the narrative-spine purpose: fields) and is NOT a render source for spec-manifest-render — provenance-only when a DT-RX-003-paired project twin exists. The engagement-scoped compile is governed by rosetta-meta DT-RX-010 (RATIFIED 2026-06-10); spec-manifest-render re-points when its Phases A-B ship.
  • New MCP-path evals in all three skills' evals/evals.json; the upstream include= enhancement stays dormant unless live profiling shows full twin reads too heavy (the twin-read DT's Option 3 trigger).

v0.7.0

v0.7.0 upgraded all three renders to the rosetta-mcp-server v0.6.0 engagement-twin read surface (additive; rendered artifacts byte-identical when the new tools aren't used). Each skill's live-twin-read reads the engagement twin via rosetta_get_engagement_twin and grounds rationale and decision sections with rosetta_recall_engagement_memory. The v0.7.0 text's include= read-scoping and spec-manifest-render compile preference described an unshipped surface and were corrected at v0.7.1 (see above; the CHANGES.md v0.7.0 entry is preserved as history). The codex stays read-only (ADR-RX-002): it projects canonical graph state and never writes the twin. See CHANGES.md and cross-repo ADR-RX-008 / SPEC-RX-008.

v0.6.0

v0.6.0 completes the three-layer Engagement Codex contracting stack — Solution Thesis → SOW → Spec Manifest — by landing the two downstream renders as net-new skills under the same plugin. Authorized by two co-ratified design DTs (RATIFIED 2026-06-03): engagement-codex-sow-render.md (E3-S4-WP12) and engagement-codex-spec-manifest-render.md (E3-S4-WP13). No constitutional amendment — both skills are further implementations under ADR-PA-009's rendered-not-authored discipline. solution-thesis-render is byte-unchanged (additive release).

WP numbering. The two DTs name target WPs WP8/WP9; those IDs (and WP11) were already allocated in §7.5, so the new skills land as WP12 (sow-render) and WP13 (spec-manifest-render), and this PR also promotes the previously-workplan-only WP11 (rosetta-archaeology v0.4.0 tree renderer) into manifest §7.5.

sow-render v0.0.1 — procurement-grade Statement of Work

The first Codex artifact that is a hybrid of graph-derived and human-authored sections. Every one of its 17 sections (§0–§16) is tagged in template front-matter with one of three provenance classes (Q-2.A, the keystone decision):

Class Source Supersession
inherited (solution-thesis) cross-read from the upstream ST §1/§2/§6.2/§6.4/§8 re-emits
graph (engagement-graph) ContextArtifacts + readiness verdict re-emits
authored (operator) §12 Commercial / §14 Warranties / §16 Signatures + the §13 IP frame preserved; cleared only with --reset-commercial
  • Two tones (Q-6.A): procurement (default; the customer-side signatory view — scope, terms, acceptance, exit) and partner (the SI/reviewer view — adds §11 Spec Manifest reservations, §13 promotion-candidate detail, and per-section provenance annotations).
  • Outcome-first, acceptance-bearing (Q-3.A): §2 Outcomes precede §4 Deliverables; every §4 row (one per ContextArtifact) traces to a §2 outcome (untraced ⇒ MANIFEST WARNING) and carries an objective acceptance check sourced from the readiness verdict.
  • Real §13 IP (Q-4.A): §13 ships real methodology-retention structural language populated from 14-promotion-candidates.cypher (Keenan Vision retains the canonical patterns/methodology; the client licenses the engagement-specific work product) under a standing counsel guard rendered once above §12. §12/§14/§16 are «TBD-N» scaffolds — the renderer is not counsel.
  • Output: outputs/plugins/engagement-codex/<key>/procurement/sow.md (procurement; §11 omitted) + sow.partner.md (partner; all 17), each with a date-stamped sibling.

spec-manifest-render v0.0.1 — delivery-and-agent Spec Manifest

The boundary of the contracting stack — the last contractually- committed artifact and the first machine-executable input. Almost entirely graph-derived (no authored commercial surface). Nine sections (§0–§8), no tone parameter (Q-4.A — the audiences overlap).

  • The "law manual" cure (Q-3.A): an At-a-Glance status panel above §0, a mandatory narrative spine (a plain-English purpose: before any YAML at every Epic / Sprint / Work Packet — HARD FAIL exit 1 if any is absent), and four-block WP subordination (metadata / file-set / execution discipline / context bundle). Narrative layered on the formal structure, not replacing it.
  • Epic = ContextArtifact (Q-5.A): §3 Building Blocks renders one Epic per CA; the body projects layers_intent → layers_structure → layers_binding; contradictions render as an explicit callout. (The overlay MAY carry an additional CA-less delivery Epic — e.g. the terminal POV Complete value gate — which renders only in §5.)
  • Gates in §5 (Q-6.A): the four Sprint exit gates (Foundation / Capability / Activation Ready, POV Complete) live inside §5 with a §5.0 Codex-phase citation — not a top-level Phase section. POV = Proof of Value.
  • §1 reservation reconciliation (Q-7.A — the cross-layer bridge): §1 reconciles the reservation IDs from the ST §6.3 and the SOW §11 against the one-Epic-per-CA set; a clean diff (no reservation-drift WARNING) proves the three-layer handoff closes end-to-end.
  • Inline Decision Traces (Q-8.A) at the governing Epic/Sprint; §6 indexes the set.
  • Output: outputs/plugins/engagement-codex/<key>/delivery/spec-manifest.md with a date-stamped sibling. Reads a per-engagement db/engagements/<key>/delivery-overlay.yaml as the purpose: + Wave/Epic/Sprint/WP source.

NTO-01 dog-food (the join that proves the stack closes)

Both skills were dog-fooded against NTO-01 (our 100%-conformance baseline). The reservation-ID diff is clean across all three layers — ST §6.3 = SOW §11 = SM §1 = {SM-NTO-01, SM-NTO-02, SM-NTO-03, SM-NTO-04} (1:1 with the four ContextArtifacts) — so the Thesis → SOW → Spec Manifest handoff is mechanically verified, not asserted. The SOW §4 outcome-trace + acceptance-check discipline held (zero untraced rows); the SM narrative-spine hard-fail passed (renders with purpose:, refuses without). Evidence: docs/decision-traces/e3s4wp12-engagement-codex-sow-render-v0.0.1-implementation.md and …e3s4wp13-engagement-codex-spec-manifest-render-v0.0.1-implementation.md.

Shared contracts reused unchanged

Both new skills reuse solution-thesis-render's defensive-parser.md (supersession four-mode taxonomy) and tbd-numbering.md (bidirectional «TBD-N» invariant) via relative symlinks — the generic contracts are shared; each skill documents its own anchor set (the SOW's authored §12/§13-frame/§14/§16; the SM's nine graph-derived sections) in its own SKILL.md.

v0.5.1

v0.5.1 is a patch release refining two leadership-tone behaviors surfaced by the E3-S4-WP7 NTO-01 dogfood. The four-tone catalog, the 11-section spine, and audit / seller / customer behavior are unchanged — only the leadership §2 inheritance rule and the §10 / §11 off-ramp discipline change. Authorized by two ratified DecisionTraces (DT-3, DT-4).

Leadership §2 thesis-frame inheritance (DT-3 / Option B)

The leadership §2 Future Announcement Draft previously inherited the seller-tone §1 prose with no rule about which sub-sections carry. v0.5.1 names the inheritance scope explicitly: the leadership §2 inherits only the three thesis-frame sub-sections of the seller §1 —

  1. "What NTO is asking for" (stakeholder framing)
  2. "What the dossier already proves" (evidence framing)
  3. "Our thesis in one sentence" (the singular position)

matched case-insensitively and fuzzily (on asking for / dossier / thesis in one sentence), and emitted in leadership-narrative order — asking-for → dossier-proves → singular-thesis. The seller §1's operational asks, partner-network material, and post-bundle steps re-frame in §9 / §11 / §7 and are not inherited. Unmatched keys fall through with no inheritance; a new MANIFEST WARNING §2-partial-inheritance: <N> of <M> seller sub-sections matched reports the coverage.

Leadership §10 / §11 off-ramp hardening discipline (DT-4 / Option C)

When the upstream classification-readiness-verdict.md §5.5 off-ramp section is an unhardened [from NTO: …] placeholder, the leadership §10 (Production Blockers and Off-Ramps) sub-block B previously synthesized off-ramp triggers inline with no marker — a render-time divergence risk if the operator later hardens §5.5. v0.5.1 signals the synthesized state visibly: §10 sub-block B emits a "to confirm" body pointing the reader to a new appendix subsection 11.8 "Synthesized candidate off-ramp triggers (DRAFT)", which carries the synthesized triggers explicitly marked "DRAFT pending operator review." A new MANIFEST WARNING §10-synthesized-from-placeholder flags the synthesized state. After the operator hardens §5.5, the next render drops 11.8 and lifts §10 sub-block B to the real prose.

The DT-4 follow-up sub-question — extending the discipline to other §5 sub-sections — is deferred.

v0.5.0

v0.5.0 adds a fourth TONE value leadership for human-facing decision-brief Solution Thesis renders targeting leadership and account-team readers. The new tone ships a net-new 11-section template opening with a synthesized Decision Brief composed from §5.1 verdict + §7.0 CTA + §6.2 POV scope. Audit / seller / customer tones at v0.4.x are byte-identical at v0.5.0 — the new tone is additive only.

Origin

A 2026-05-18 external evaluation of the NTO-01 v0.3.0/v0.4.0 seller-tone render found the artifact passed structural conformance but reads as a rendered governance artifact rather than a leadership-room decision brief. Seven distinct findings (opens with renderer metadata; internal labels dominate; evidence not prioritized; verdict arrives too late; placeholders interrupt; no business spine; no "ready for what") motivated the design DT.

Leadership-tone 11-section spine (Q-6.A)

  1. Decision Brief — synthesized from §5.1 + §7.0 + §6.2
  2. Future Announcement Draft — inherits seller §1 Cowork-adapted prose
  3. Why This Matters Now — §6.5 Cost of Inaction + §2.1 stakeholder pressure
  4. What We Found — Q-5.B evidence-by-reference ordering of §3.3 forensic findings
  5. Recommended Solution — §4.1 + §4.3 with dt.leadershipGloss label translation
  6. Guardrails — §3.4 anti-patterns translated to forward- facing prose
  7. Readiness Verdict — §5.1 + Q-8.B "ready for what" scope qualifier
  8. POV Scope and Success Measures — §6.2 SOW scope sketch
  9. Leadership Decisions Needed — §7.1 filtered to leadership tier
  10. Production Blockers and Off-Ramps — §5.4 gap list + §5.5 off-ramp conditions
  11. Appendices — §0 Header demoted + consolidated placeholder table + §6.3 reservations + §6.4 out-of-scope + §8 parked questions + §9 history

Synthesized Decision Brief (Q-3.A)

Section 1 composes 3-5 sentences from three graph-state inputs. Missing input → «TBD-N» marker + MANIFEST WARNING decision-brief-partial. The §0 Header content is demoted to section 11 Appendices subsection 1 for audit-trail preservation; the document's first rendered element is the decision itself, not renderer metadata.

dt.leadershipGloss label translation (Q-4.A; leadership only)

Section 5 (Recommended Solution) reads dt.leadershipGloss (a new DT property authored at engagement-time in db/engagements/<key>/13-decision-traces.cypher) instead of dt.commitmentName. Missing gloss → verbatim fallback + MANIFEST WARNING leadership-gloss-missing: <DT-traceId>. Seller / customer tones UNCHANGED — they continue to emit verbatim commitment names (Q-4.B promotion to those tones is a candidate v0.6.0 follow-up).

Evidence-by-reference ranking (Q-5.B; leadership only)

Section 4 orders forensic findings by §4.3 commitment cross- references (causal grounding — "evidence that changed the solution"). Fallback to Q-5.A heuristic when no §4.3 carries forensic-finding cross-references; MANIFEST WARNING leadership-evidence-fallback.

"Ready for what" verdict qualifier (Q-8.B; leadership only)

Section 7 appends a composed scope qualifier to the verdict ("Conditionally Ready for a bounded POV; not for full production activation until section 10 gaps close"). Symmetric with the Q-3.A Decision Brief composition. Missing pov.inScopeFirstLine → partial-render + MANIFEST WARNING verdict-qualifier-partial.

Consolidated placeholder discipline (Q-7.A; leadership only)

Inline [from NTO: ...] placeholders are replaced with italicized «to confirm» in narrative; a consolidated table in section 11 subsection 2 ("Information needed before customer presentation") lists one row per unique field. Seller / customer tones UNCHANGED — they retain v0.4.x inline discipline (Q-7.B promotion is a candidate v0.6.0 companion to Q-4.B).

Leadership output path (Q-1.A)

outputs/plugins/engagement-codex/<key>/leadership/
├── solution-thesis.leadership.md             ← spec-canonical
└── solution-thesis.leadership.2026-05-18.md  ← date-stamped sibling

The leadership tone lives in its own per-tone subdirectory (isolated from the audit/seller/customer trio under seller/).

Four absence-tolerant MANIFEST WARNINGs (leadership only)

  • leadership-gloss-missing: <DT-traceId> at §5
  • decision-brief-partial: <missing-input-name>
  • leadership-evidence-fallback: no §4.3 cross-references
  • verdict-qualifier-partial: pov scope absent

None of these block the leadership-tone render or trigger HARD FAIL — partial-renders with explicit WARNINGs are the v0.5.0 contract.

New acceptance criteria

  • AT1 / AT2 / AT3 — audit / seller / customer byte-identity regression baselines preserved at v0.5.0.
  • AT4 — leadership-tone 11-section shape conformance (Q-6.A).
  • AT5 — Decision Brief synthesis from §5.1 + §7.0 + §6.2.
  • AT6 — dt.leadershipGloss translation in section 5 with WARNING fallback.
  • AT7 — Evidence-by-reference ranking with WARNING fallback.
  • AT8 — Consolidated placeholder table in section 11.
  • AT9 — "Ready for what" verdict qualifier with WARNING fallback.

Out of scope (deferred)

Leadership-tone Cowork deployment, Q-4.B promotion, Q-7.B promotion, Q-8.A upstream verdictScope field, customer-tone restructure to the 11-section spine. See CHANGES.md §"Out of scope" and the design DT §"Out-of-scope, deferred to follow-up DTs".

v0.4.0

v0.4.0 ships engagement-codex to Cowork in addition to Claude Code. The companion plugins rosetta-research and rosetta-archaeology already ship through Cowork (bundle zip + marketplace.json listing); engagement-codex now achieves parity for the audit + seller tones. Customer-tone reaches Cowork at v0.4.1 (WP6) per Q-1 phased rollout in the v0.4.0 design DT.

Cowork deployment surface

  • Bundle zip: engagement-codex-0.4.0.zip at the plugin root; shape mirrors rosetta-research-0.11.1.zip and rosetta-archaeology-0.3.1.zip (.claude-plugin/, commands/, skills/, README.md at the root). Generated by make plugin-bundle-engagement-codex (delegates to scripts/release/bundle-plugin.sh engagement-codex) and included in the make bundles composite target.
  • Description-cap discipline (Q-5 ratified, v0.4.0 invariant). Three description fields fit under Cowork's empirical validator caps: plugin.json description ≤410 chars (was 585 over); command file description: ≤360 chars (was 613 over); SKILL.md frontmatter description ≤729 chars known-working (was 1615 over). Future version bumps re-evaluate the description surface as a whole — they MUST fit under cap or rework the surface (don't grow additively).

Optional PRIOR_BUNDLE supersession (Q-4 ratified)

A new optional input argument PRIOR_BUNDLE=<path-to-zip> carries a prior engagement-codex output bundle forward into the current render run. The prior bundle is the source of authored §1 / §2.0 prose for cross-tone propagation AND the defensive-parser anchor for supersession drift classification when the operator's runtime is stateless (Cowork) and cannot read prior renders from disk.

SKILL.md amendments:

  • Step 1.prior (new). Extracts PRIOR_BUNDLE to a second scratch directory alongside the primary bundle; pins the three potential PRIOR_TONE_FILES for downstream procedural steps. Optional — no-op when PRIOR_BUNDLE is unset.
  • Step 3.1.prior (new). Expands the §1 cross-tone propagation walk to include prior-bundle files as candidate sources for authored §1 prose. Selection by mtime — prior-bundle files MAY supersede on-disk files when newer.
  • Step 3.3.prior (new). Same expansion for §2.0 propagation.
  • Step 7.prior (new). When on-disk anchor is absent AND PRIOR_BUNDLE was extracted, reads the prior bundle's matching tone-suffix file as the defensive-parser anchor; the .bak.<ts>.md preservation chain materializes inside the returned output bundle (not on the operator filesystem).
  • Step 8.4 render report extended to surface the PRIOR_BUNDLE source + the drift mode.

Cowork-runtime customer-tone disablement (Q-1 ratified)

  • Step 0.cowork (new). After Step 0's TONE resolution, if COWORK_RUNTIME=1 is set AND <tone> == customer, the skill HARD FAILS exit 2 with the explicit message customer-tone render disabled on Cowork at v0.4.0; reaches Cowork at v0.4.1. The Claude-Code-side customer-tone path is unaffected (Claude Code retains all three tones at v0.4.0). Cowork's command file frontmatter sets COWORK_RUNTIME=1; the Claude-Code-side wrappers do not.

New acceptance criteria

  • AT10 — Cowork bundle distribution: engagement-codex-0.4.0.zip exists; layout matches the companion-plugin shape; description fields fit under the three caps.
  • AT11 — Cowork input handling: a Cowork session with a rosetta-archaeology bundle uploaded produces an engagement-codex output bundle for audit or seller tones with both canonical and dated-sibling outputs.
  • AT12 — Cowork supersession via PRIOR_BUNDLE: prior bundle is read for §1 + §2.0 propagation AND defensive-parser drift classification; .bak.<ts>.md preservation lands in the returned bundle.
  • AT13 — Cowork customer-tone refusal: --tone customer AND COWORK_RUNTIME=1 HARD FAILS exit 2 with the explicit disablement message; no output bundle is produced.

v0.3.1

Every render now writes a date-stamped sibling alongside the spec-canonical file. After the canonical write at Step 8.2 step 3, the skill writes a byte-identical content-mirror at <canonical-stem>.<YYYY-MM-DD>.md in the same directory. Example (seller-tone render on 2026-05-16):

outputs/plugins/engagement-codex/<key>/seller/
├── solution-thesis.seller.md             ← spec-canonical (defensive-parser anchor; AT1 byte-identity target)
└── solution-thesis.seller.2026-05-16.md  ← date-stamped sibling (operator-handle)

Same-day re-renders idempotently overwrite the dated sibling. New-day renders create a new dated file; the prior day's sibling is preserved on disk as a chronology trail. Defensive-parser supersession (Step 7) and cross-tone propagation (Step 3.1, Step 3.3) read the canonical file only; dated siblings are pure operator-facing handles, never consulted by procedural steps.

The v0.3.1 rule is scoped to engagement-codex solution-thesis outputs; other repo surfaces keep their own filename contracts and are not covered.

v0.3.0

v0.3.0 closes six rhetorical-shape findings from the NTO-01 v0.2.0 seller-tone evaluation. v0.2.x solved the vocabulary-substitution problem (internal IDs substituted via tone-vocabulary.md, per-section visibility flags, [from NTO: ...] placeholders); v0.3.0 solves the template-shape problem.

Four new template sections

  • §2.0 Thesis Statement (rendered: false, all tones). Seller-authored 100–200 word defensible position synthesizing §3 evidence and §5 verdict. Renderer emits a placeholder block on first render; defensive-parser preserves seller-authored prose across supersessions symmetrical with §1; cross-tone propagation per Q-8.A.
  • §4.0 Methodology Keystone (rendered: true, all tones, conditional on Phase 4 PromotionCandidate presence). 75–100 word callout opening §4. Extracted from the highest-confidence PC via scope_assessment ordering. When suppressed (Phase 3-only engagement), §4.3 retains its v0.2.3 content; when emits, the §4.3 methodology-keystone bullet demotes to a one-line cross-reference.
  • §6.5 Cost of Inaction (rendered: true, all tones, conditional on §3.3 forensic finding meeting severity-≥-threshold AND mention-count-≥-3). Two-sentence framing; per-tone visibility branches (audit: finding ID inline; seller: substituted name; customer: percentage-only).
  • §7.0 Singular CTA (rendered: true, tones: [seller, customer] only). Hoists the §7.4 measurable CTA to the top of §7 in seller and customer tones; §7.1-§7.4 follow in seller under ### Appendix — Working asks, suppressed in customer. Audit-tone NEVER renders §7.0 — audit preserves the v0.2.3 §7.1 → §7.2 → §7.3 → §7.4 ordering byte-identically (AT1 baseline).

Two new tone-vocabulary classes

  • Architectural-mechanism phrases (D.1; mandatory substitution). Canonical phrases like "refining override," "override-mode coherence check," "canonical pattern," "pattern composition" are substituted via D.1 in seller and customer tones; audit retains the canonical phrases. ≥15 rows authored at v0.3.0 (NTO-01-seed).
  • Agency constructions (D.2; candidate substitution). Depersonalized "the engagement encodes / asserts / commits / ..." substituted to "we recommend / our position is / we commit" in seller-tone (and customer-equivalents); applied where grammatically clean; fall-through to canonical + MANIFEST WARNING agency-substitution-skipped when awkward. ≥8 rows authored at v0.3.0.

Two visibility changes

  • §5.3 Dependency map — tones: [audit, seller, customer] → tones: [audit]. The audit-tone Gate-3 reviewer still sees the ASCII dependency diagram; sellers and customers don't (the same point is made better in prose two lines later in §5.4).
  • §6.1 Solution Thesis commitments — tones: [audit, seller, customer] → tones: [audit]. The audit-tone Gate-3 reviewer still sees the meta-documentation about supersession discipline; sellers and customers don't.