# 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 [--tone audit|seller|customer|leadership] /engagement-codex:sow-render [--tone procurement|partner] /engagement-codex:spec-manifest-render ``` or via Make: `make solution-thesis-render ENGAGEMENT= [TONE=…]` · `make sow-render ENGAGEMENT= [TONE=…]` · `make spec-manifest-render ENGAGEMENT=`. Full flags and the bundle-zip input form are under [Invocation](#invocation). (The old `render-*` command spellings were removed in v0.11.0.) - **Current release:** plugin **v0.12.0** — skills `solution-thesis-render` v0.7.0 · `sow-render` v0.1.0 · `spec-manifest-render` v0.2.0 (the versions their eval suites declare). Release notes: `CHANGES.md` and [Version history](#version-history). - **Sources (v0.12.0, E9-S2-WP1; ADR-PL-024):** the live graph, or a supplied rosetta-archaeology run bundle. `db/engagements/` left `main` at the DT-RX-036 switch; no skill reads it from the checkout, and a render with no live engagement and no bundle HARD FAILS with a pointer. `--source files` is retired. - **Cowork bundle:** `engagement-codex-.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//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: ]` 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-codex:solution-thesis-render --tone seller /engagement-codex:solution-thesis-render --tone customer /engagement-codex:solution-thesis-render --tone leadership /engagement-codex:solution-thesis-render /engagement-codex:solution-thesis-render --tone seller /engagement-codex:solution-thesis-render --tone leadership ``` The first form renders the live engagement `eng-` (v0.12.0: it never reads `db/engagements/` from the checkout; the classes the live surface does not serve need a bundle). The bundle-zip form extracts to a scratch directory and reads from there, live-first where the engagement is live. 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) ```bash # Render from a Cowork bundle zip (audit tone by default): make solution-thesis-render BUNDLE=/path/to/rosetta-archaeology--runall-.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 ```bash # 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) Live-graph-first: the live twin and the engagement-scoped compile serve the CAs, DecisionTraces and readiness verdict. Otherwise, and for the classes the live surface does not serve, the inputs come from a supplied rosetta-archaeology run bundle; the paths below are **bundle-internal** (since v0.12.0 never read from a checkout): | Path | Source | Required | | --- | --- | --- | | `db/engagements//00-domain.cypher` | engagement leaf KnowledgeDomain | yes | | `db/engagements//10-context-artifacts.cypher` | Phase 3 Context Artifacts | yes | | `db/engagements//13-decision-traces.cypher` | Phase 3 DecisionTraces v1.3 | yes | | `db/engagements//14-promotion-candidates.cypher` | Phase 4 PromotionCandidates | optional (Phase 4 only) | | `outputs/plugins/rosetta-archaeology//research/classification-readiness-verdict.md` | Phase 3 eleven-dimension verdict | yes | | `outputs/plugins/rosetta-archaeology//seller/solution-thesis.md` | Cowork runtime's rhetorical thesis | optional (Q-2.C preferred) | | `outputs/plugins/rosetta-archaeology//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// ├── 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//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.` per the defensive-parser contract. ## Constitutional alignment The plugin operates within the rosetta-platform invariants (`CLAUDE.md`): - **C-2 (Cypher canonical; ADR-PL-024 since the switch).** The skill is read-only against the live graph and the supplied bundle; it never authors Cypher or writes the twin. - **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//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//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//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//delivery/spec-manifest.md` with a date-stamped sibling. Reads a per-engagement `db/engagements//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: of 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//13-decision-traces.cypher`) instead of `dt.commitmentName`. Missing gloss → verbatim fallback + MANIFEST WARNING `leadership-gloss-missing: `. 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//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: at §5` - `decision-brief-partial: ` - `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=` 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..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 ` == 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..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 `..md` in the same directory. Example (seller-tone render on 2026-05-16): ``` outputs/plugins/engagement-codex//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.