@smartmemory/compose 0.3.6-beta → 0.3.8

package/.claude/skills/compose/SKILL.md

@@ -391,111 +391,65 @@ If Stratum unavailable, continue with flat prompt chain.
 
 Triage is implicit on entry (severity, scope, path) — it gates which steps to run, not a Stratum step itself. Phases 6 (plan), 9 (docs) are folded into `fix` and `ship` respectively.
 
-### Spec Template
+### Spec Template (TS engine grammar, post-cutover)
+
+The TS engine's spec IR (validated by `stratum/ts/src/ir/validate.js`) differs
+from the retired python grammar: `version` is the number `1`, contracts use
+string shorthand, `flows.entry` names the entry flow, and steps use
+`do`/`out`/`after`/`ensure`/`attempts` (NOT `function`/`inputs`/`depends_on`).
+MCP `stratum_plan` currently reports grammar violations as a bare
+"spec validation failed" (smartmemory/stratum#26) — get the template right.
 
 ```yaml
-version: "0.1"
+version: 1
 contracts:
-  ResearchResult:
-    findings: {type: array}
-    relevant_files: {type: array}
   DesignResult:
-    path: {type: string}
-    word_count: {type: integer}
+    path: string
+    words: number
   BlueprintResult:
-    path: {type: string}
+    path: string
   ImplementResult:
-    files_changed: {type: array}
-    tests_pass: {type: boolean}
-
-functions:
-  research:
-    mode: compute
-    intent: "Explore the codebase with compose-explorer agents and surface patterns relevant to the feature."
-    input: {description: {type: string}}
-    output: ResearchResult
-    ensure:
-      - "len(result.findings) > 0"
-    retries: 2
-
-  write_design:
-    mode: compute
-    intent: "Run Phase 1 (and optional Phases 2-3) — explore, gate, write design.md."
-    input: {description: {type: string}}
-    output: DesignResult
-    ensure:
-      - "file_exists(result.path)"
-      - "result.word_count > 200"
-    retries: 2
-
-  write_blueprint:
-    mode: compute
-    intent: "Run Phases 4-5 — blueprint, verification. Gate before returning."
-    input: {description: {type: string}}
-    output: BlueprintResult
-    ensure:
-      - "file_exists(result.path)"
-    retries: 2
-
-  implement:
-    mode: compute
-    intent: "Run Phase 7 — TDD, E2E, review loop, coverage sweep."
-    input: {description: {type: string}}
-    output: ImplementResult
-    ensure:
-      - "result.tests_pass == True"
-      - "len(result.files_changed) > 0"
-    retries: 2
+    files_changed: string
+    tests_pass: boolean
 
 flows:
+  entry: compose_feature
   compose_feature:
-    input: {description: {type: string}}
-    output: ImplementResult
+    input:
+      goal: string
+    output:
+      from: "${implement.output}"
+      contract: ImplementResult
     steps:
-      - id: research
-        function: research
-        inputs: {description: "$.input.description"}
-        output_schema:
-          type: object
-          required: [findings]
-          properties:
-            findings: {type: array, items: {type: string}}
-            relevant_files: {type: array, items: {type: string}}
-
       - id: write_design
-        function: write_design
-        inputs: {description: "$.input.description"}
-        depends_on: [research]
-        output_schema:
-          type: object
-          required: [path, word_count]
-          properties:
-            path: {type: string}
-            word_count: {type: integer}
+        do: "Run Phase 1 (and optional 2-3) — explore, gate, write design.md. Codex design gate to REVIEW CLEAN."
+        out: DesignResult
+        ensure:
+          - file_contains: {path: "docs/features/<code>/design.md", text: "Design"}
+        attempts: 3
 
       - id: write_blueprint
-        function: write_blueprint
-        inputs: {description: "$.input.description"}
-        depends_on: [write_design]
-        output_schema:
-          type: object
-          required: [path]
-          properties:
-            path: {type: string}
+        after: [write_design]
+        do: "Run Phases 4-5 — blueprint grounded in real code, corrections table, verify every file:line ref."
+        out: BlueprintResult
+        ensure:
+          - file_contains: {path: "docs/features/<code>/blueprint.md", text: "Corrections"}
+        attempts: 3
 
       - id: implement
-        function: implement
-        inputs: {description: "$.input.description"}
-        depends_on: [write_blueprint]
-        output_schema:
-          type: object
-          required: [files_changed, tests_pass]
-          properties:
-            files_changed: {type: array, items: {type: string}}
-            tests_pass: {type: boolean}
-
+        after: [write_blueprint]
+        do: "Run Phase 7 — TDD, E2E, review loop, coverage sweep."
+        out: ImplementResult
+        ensure:
+          - file_exists: "docs/features/<code>/design.md"
+        attempts: 3
 ```
 
+Step results are reported via `stratum_step_done` with the step's `dispatchToken`;
+`result.output` must match the step's `out` contract exactly (string shorthand
+means scalar fields — e.g. `files_changed` is one string, not an array; extra
+keys are rejected).
+
 The bugfix flow lives in `compose/pipelines/bug-fix.stratum.yaml` (8 steps + bisect, ships with compose). The CLI entry `compose fix <bug-code>` (in `bin/compose.js`) reads `docs/bugs/<code>/description.md` (scaffolds and exits if missing) and dispatches `runBuild(code, { mode: 'bug', template: 'bug-fix', description })`.
 
 ### Hard-bug machinery (COMP-FIX-HARD, 2026-05-01)

package/.compose-deps.json

@@ -86,17 +86,5 @@
       "optional": true
     }
   ],
-  "external_binaries": [
-    {
-      "id": "rtk",
-      "detect": "rtk --version",
-      "required_for": [
-        "LLM-bound git-diff compression (build review)",
-        "agent Bash output compression via `rtk init -g` hook"
-      ],
-      "install": "brew install rtk  (or: cargo install --git https://github.com/rtk-ai/rtk)",
-      "recommend": "rtk init -g",
-      "optional": true
-    }
-  ]
+  "external_binaries": []
 }

package/README.md

@@ -1,14 +1,47 @@
 # Compose
 
-Compose is a CLI that drives a product idea from intent to shipped code. It runs YAML-defined multi-step pipelines on top of [Stratum](https://github.com/smartmemory/stratum), dispatching each step to an AI agent (Claude or Codex), checking postconditions, and pausing at human gates between phases. Output: a feature folder with design, blueprint, plan, code, tests, review trail, and an updated `ROADMAP.md` — auditable end-to-end.
+### Structured AI dev pipeline: goal to shipped code, with gates that hold
+
+#### *Your agent writes the code. Compose makes it prove it.*
+
+> Describe what you want. Compose decomposes it, forces the design decisions before any code is written, hands each step to the right agent, and refuses to advance until that step proves it is done. What comes back is a feature folder with the design, the blueprint, the plan, the code, the tests, and the full review trail. Auditable end to end.
 
 ![Compose Cockpit Shell](Screenshot.png)
 
-## Pitch
+## The problem
+
+An agent finishes, reports done, and the suite is green. Weeks later you find the feature. It exists, it has tests, and nothing calls it. The tests exercise a path that real data never enters.
+
+Nobody lied. The agent did what it was asked, the tests assert what they assert, and no step in between ever had to prove the thing was wired to anything. That gap does not show up in a diff review. It shows up in production, or it never shows up at all, which is worse.
+
+Compose sits above Claude Code and Codex rather than in place of them. It decides what the next step is, hands it to whichever agent should do it, and will not advance until the step proves it finished.
+
+## Who it's for
 
-- **Gates everywhere** — every phase transition (design, plan, ship) is approve/revise/kill. Human or Codex review at any point.
-- **Stratum-backed** — pipelines are declarative `.stratum.yaml` specs with typed contracts, `ensure` postconditions, and retry/`on_fail` routing. Specs are editable.
-- **Multi-agent** — Claude (via the Anthropic Agent SDK) and Codex (via the OpenAI CLI) plug in through a uniform connector interface; reviews can run on a different model than implementation.
+- **Solo builders and small teams** shipping more code each week than they can personally review, who need something other than trust to decide when a feature is really done
+- **Tech leads reviewing agent output** who keep finding work that passes its own tests and is wired to nothing
+- **Anyone running more than one agent** (Claude for implementation, Codex for review) who wants the same standard applied no matter which model did the work
+- **Developers who lose the thread at a session boundary** and want the plan, the decisions, and the open questions to outlive the context window instead of living in chat scrollback
+- **Maintainers whose roadmap has drifted from reality** and want status derived from what actually shipped rather than from what someone remembered to update
+- **Teams who have to explain a decision months later**, what was chosen, what was rejected and why, and cannot reconstruct any of it from a diff
+
+## Why Compose
+
+| | Prompting the agent directly | A plan.md or TODO list | **Compose** |
+| --- | --- | --- | --- |
+| **Definition of done** | Whatever the agent says | A checkbox someone ticks | Postconditions checked before the step can pass |
+| **Design decisions** | In the chat, then gone | Sometimes written down | Recorded artifacts, gated before any code |
+| **Survives a session boundary** | No, only scrollback | The text, not the reasoning | Feature folder: design, blueprint, plan, review trail |
+| **Review** | Whenever you remember | Manual | Enforced at every gate, and runnable on a different model than the one that wrote the code |
+| **Catches wired-to-nothing code** | No | No | Implementation review keyed to wiring, not only to tests |
+| **Roadmap status** | Manual | Manual, and it drifts | Generated from what actually shipped |
+| **Recovery mid-build** | Start over | Re-read and guess | Resume from recorded state |
+
+## How it holds the line
+
+- **Gates everywhere.** Every phase transition (design, plan, ship) is approve, revise, or kill. Human or Codex review at any point.
+- **Stratum-backed.** Pipelines are declarative `.stratum.yaml` specs with typed contracts, `ensure` postconditions, and retry/`on_fail` routing. Specs are editable.
+- **Multi-agent.** Claude (via the Anthropic Agent SDK) and Codex (via the OpenAI CLI) plug in through a uniform connector interface. Reviews can run on a different model than implementation.
 
 ## 30-second example
 
@@ -144,6 +177,17 @@ compose tracker sync     # reconcile op-log against remote provider
 
 See [docs/configuration.md](docs/configuration.md) for the full `tracker` config reference.
 
+## Backfilling a completion (guarded workspaces)
+
+Sometimes a feature is finished before its lifecycle was ever walked: it shipped before Compose existed, or the guard was switched off at the time. Compose can record that completion with evidence instead of an override token. Call the MCP tool `backfill_completion` (or `POST /api/vision/items/:id/lifecycle/backfill`) with the completing commit, a test attestation, a reason, and dated phase occurrences. The gate verifies the evidence, merges the occurrences into the phase history by their real dates, and moves the guard to `complete_backfilled`. Readers and the UI show which entries were backfilled.
+
+Features that were never registered with the guard need nothing else. Features registered before this release carry an older policy, and the guard will only accept the new one under a signed upgrade descriptor. The signature is the one thing an agent must never be able to produce on its own, so it is the one thing a human confirms:
+
+- **Once per Mac:** run `compose guard enrol` from a terminal. It installs a root-owned signing key and signer under `/Library/Compose/guard/`, a `sudo` rule that always re-authenticates (Touch ID via `pam_tid`), enrols the public key in stratum's trust root, and verifies the round trip. Two Touch ID prompts, then `done`.
+- **Every later signature is one Touch ID prompt.** When a backfill needs a descriptor that is not yet signed, the gate generates it, asks, verifies, and continues. Nothing else is manual. `compose guard sign` does the same explicitly and `compose guard status` shows custody, enrolment, descriptor freshness and whether the signed generations are committed.
+
+Signed descriptors live in `.compose/guard-upgrades/<sha256>/` (immutable) with `current` pointing at the live generation; commit them like any other workspace canon. A backfill refuses with `signature_not_approved` when the prompt is cancelled or cannot be shown (SSH session, `tmux` without `pam_reattach`), and with `upgrade_descriptor_unavailable` on a machine that has not run `enrol`. Admins who want the "one approval, one signature" property to hold against their own other `sudo` use can add `Defaults timestamp_timeout=0` to sudoers. Without macOS custody (Linux, CI), `compose guard descriptors` still writes the unsigned candidate and prints the `ssh-keygen -Y sign` command for an operator key.
+
 ## Remote access (mobile PWA from anywhere)
 
 The mobile cockpit at `/m` can be reached from outside localhost — bring your own tunnel, compose handles auth and pairing:
@@ -189,6 +233,29 @@ compose smartmemory sync --dry-run       # preview counts without ingesting
 compose smartmemory sync --feature CODE  # scope the sync to one feature
 ```
 
+### Maya colleague panel (opt-in, requires the SmartMemory service stack)
+
+With the SmartMemory fluid provider configured, a `maya` block summons Maya (the SmartMemory
+assistant) as a colleague inside the cockpit: a slide-over panel where you discuss ideas while
+Compose computes the memory findings (challenge, conviction, contradictions) and hands them to
+her as per-turn context. Her replies about a focused idea append to its discussion trail as
+`author: maya`.
+
+```json
+{
+  "maya": {
+    "baseUrl": "http://localhost:9005",
+    "auth": { "mode": "provision" }
+  }
+}
+```
+
+`auth.mode` is `provision` (a dedicated colleague identity minted lazily against the local
+smart-memory-service test surface) or `static` (paste a token in the panel; it is verified
+against the service before being stored). The colleague never runs degraded: without the
+SmartMemory provider the panel explains what to connect instead of falling back to plain chat,
+and capabilities the provider does not declare render as visibly unavailable.
+
 ## Documentation
 
 Topic-scoped reference: