@smartmemory/compose 0.1.27-beta → 0.1.29-beta

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

@@ -182,6 +182,7 @@ Present all proposals, trade-offs, your recommendation. User picks. Write to `do
 - Read every critical file, note patterns with line references
 - Build corrections table (spec assumption vs reality)
 - Write to `docs/features/<feature-code>/blueprint.md`
+- **Boundary Map (when feature has 2+ work units):** append a `## Boundary Map` section per `.claude/skills/compose/templates/boundary-map.md`. Each entry must name a concrete code symbol with a kind in `{interface, type, function, class, const, hook, component}`. Endpoints, event payloads, file formats, and invariants belong in prose, not in Boundary Map entries.
 
 **Gate:** Corrections table empty or all corrections documented.
 
@@ -194,11 +195,13 @@ For every file:line reference in the blueprint:
 4. Confirm imports/exports
 5. Flag stale references
 
+If the blueprint contains a `## Boundary Map` section, run `validateBoundaryMap` from `lib/boundary-map.js` against the blueprint. Append every violation as a row in the Verification Table; warnings render as informational rows but do not block the gate. The four checks are: File-Plan-or-disk, symbol presence (untouched dependencies only), topology (every `from S##` references an earlier slice), producer/consumer match.
+
 Produce a verification table, append to `blueprint.md`. If any stale/wrong, loop back to Phase 4.
 
-**Gate:** All file:line references verified. Zero stale entries.
+**Gate:** All file:line references verified. Zero stale entries. Zero Boundary Map violations (warnings allowed).
 
-**Skip when:** Blueprint written in the same session immediately after reading all referenced files.
+**Skip when:** Blueprint written in the same session immediately after reading all referenced files **and** the blueprint has no Boundary Map.
 
 ## Fix Mode Phases (F1–F3)
 

package/.claude/skills/compose/templates/boundary-map.md

@@ -0,0 +1,94 @@
+# Boundary Map — Authoring Template
+
+A **Boundary Map** is an opt-in `## Boundary Map` section inside `blueprint.md` that declares, at file→symbol granularity, what each slice (sub-feature, parallel task, or work unit) **produces** and **consumes**. The Phase 5 verifier runs `validateBoundaryMap` from `lib/boundary-map.js` against any Boundary Map present.
+
+---
+
+## When to author
+
+If your feature has **2+ work units** (slices, sub-features, or parallel tasks under STRAT-PAR), append a `## Boundary Map` section **after `## File Plan`** and **before `## Verification Table`**.
+
+Single-unit features have no boundaries to map — skip it.
+
+---
+
+## Format spec
+
+```markdown
+## Boundary Map
+
+### S01: auth primitives
+Produces:
+  src/lib/auth/types.ts → User, Session, AuthToken (interface)
+  src/lib/auth/tokens.ts → generateToken, verifyToken, refreshToken (function)
+
+Consumes: nothing (leaf node)
+
+### S02: HTTP layer
+Produces:
+  src/server/api/auth/login.ts → loginHandler (function)
+  src/server/middleware/auth.ts → authMiddleware (function)
+
+
+
+Consumes:
+  from S01: src/lib/auth/tokens.ts → generateToken, verifyToken
+
+### S03: client integration
+Produces:
+  src/client/auth/useAuth.ts → useAuth (hook)
+
+Consumes:
+  from S01: src/lib/auth/types.ts → User, Session
+  from S02: src/server/api/auth/login.ts → loginHandler
+```
+
+---
+
+## Grammar
+
+- **Slice headings:** `### S## [: <human name>]`. The `S##` id is mandatory and must be unique within the blueprint. Names are human guidance, not parsed.
+- **Produces entries:** `<file-path> → <symbol>[, <symbol>...] (<kind>)`. The `(<kind>)` parenthetical is **mandatory** on every Produces line.
+- **Consumes entries:** `from S##: <file-path> → <symbol>[, <symbol>...]`. The trailing `(<kind>)` is optional and ignored — the kind already lives on the matching upstream Produces entry.
+- **Leaf slices** (no upstream dependencies) use the literal form `Consumes: nothing`. An optional trailing parenthetical comment such as `(leaf node)` is ignored.
+- **Sink slices** (no downstream-visible exports — integration-only slices) use the literal form `Produces: nothing`. An optional trailing parenthetical comment such as `(integration only)` is ignored.
+- **Arrows:** both `→` (U+2192, preferred) and ASCII `->` are accepted.
+- **File paths** are repo-relative.
+- **Symbols** are identifiers expected to appear (or eventually appear) in the named file.
+
+### Kind allow-list
+
+`<kind>` must be one of:
+
+```
+interface, type, function, class, const, hook, component
+```
+
+### Symbol-only restriction
+
+Boundary Map entries name **code symbols only**. Endpoints, event payloads, file formats, and invariants belong in the surrounding blueprint prose — they are not grep-checkable identifiers and are out of scope for the v1 validator.
+
+---
+
+## What the validator checks
+
+Phase 5 runs `validateBoundaryMap({ blueprintText, blueprintPath, repoRoot })` and applies four checks in order:
+
+1. **File-Plan-or-disk.** Every referenced file must either appear in the blueprint's File Plan with an allow-listed write action (`new`, `create`, `add`, `edit`, `modify`, `update`, `refactor`, `replace`) **or** exist on disk.
+2. **Symbol presence.** For files **not** marked as planned writes that exist on disk, each declared symbol must appear (substring match) somewhere in the file. Files in the File Plan as planned writes are skipped — the symbol may legitimately not exist yet.
+3. **Topology.** Every `from S##` reference must point to a slice that appears earlier in the map (backward edges only; the consumes-graph is acyclic by construction).
+4. **Producer/consumer match.** Every consumed `(file, symbol)` must be declared as a Produces entry on the named upstream slice with a matching file and a superset of symbols.
+
+Violations block the Phase 5 gate; warnings (`no_file_plan`, `unknown_action`) render as informational rows but do not block.
+
+---
+
+## Worked example: 3-slice auth feature
+
+The example above (S01: auth primitives → S02: HTTP layer → S03: client integration) demonstrates:
+
+- A **leaf slice** (S01) using `Consumes: nothing (leaf node)`.
+- **Multiple kinds** in a single slice (S01 has both `interface` and `function` Produces).
+- **Multi-symbol** Produces and Consumes entries (S01 produces three tokens; S02 consumes two of them).
+- **Cross-slice fan-in** (S03 consumes from both S01 and S02).
+- **Backward-only edges** — every `from S##` references an earlier slice.

package/bin/compose.js

@@ -112,6 +112,7 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log('  feature   Add a single feature (folder, design seed, ROADMAP entry)')
   console.log('  build     Run a feature through the headless lifecycle')
   console.log('  fix       Run a bug through the headless bug-fix lifecycle')
+  console.log('  gsd       Per-task fresh-context dispatch from existing blueprint+Boundary Map')
   console.log('  pipeline  View and edit the build pipeline')
   console.log('  roadmap            Show roadmap status and next buildable features')
   console.log('  roadmap generate   Regenerate ROADMAP.md from feature.json files')
@@ -1913,6 +1914,32 @@ if (cmd === 'build') {
       process.exit(1)
     })
   })
+} else if (cmd === 'gsd') {
+  // compose gsd <feature-code> — runs the per-task fresh-context dispatch
+  // pipeline (pipelines/gsd.stratum.yaml). Hard-requires existing
+  // docs/features/<code>/blueprint.md with a parseable Boundary Map.
+  const gsdCode = args.find(a => !a.startsWith('-'))
+  if (!gsdCode) {
+    console.error('Usage: compose gsd <feature-code>')
+    console.error('')
+    console.error('Runs the per-task fresh-context dispatch pipeline (COMP-GSD-2).')
+    console.error('Hard-requires docs/features/<code>/blueprint.md with a valid Boundary Map.')
+    console.error('')
+    console.error('Options:')
+    console.error('  --cwd <path>   Working directory (defaults to current)')
+    process.exit(1)
+  }
+  const { root: gsdCwd } = resolveCwdWithWorkspace(args)
+  const cwdIdx = args.indexOf('--cwd')
+  const gsdAgentCwd = cwdIdx !== -1 ? resolve(args[cwdIdx + 1]) : gsdCwd
+  const { runGsd } = await import('../lib/gsd.js')
+  try {
+    const result = await runGsd(gsdCode, { cwd: gsdAgentCwd })
+    console.log(`gsd complete: ${result.blackboardEntries} task results captured.`)
+  } catch (err) {
+    console.error(`gsd failed: ${err.message}`)
+    process.exit(1)
+  }
 } else if (cmd === 'triage') {
   const triageCode = args.find(a => !a.startsWith('-'))
   if (!triageCode) {

package/contracts/task-result.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "task-result.json",
+  "_source": "docs/features/COMP-GSD-2/blueprint.md",
+  "_roadmap": "COMP-GSD-2",
+  "title": "TaskResult",
+  "description": "Per-task post-execution capture written by the task agent at .compose/gsd/<featureCode>/results/<task_id>.json and committed as part of its diff. After execute step completion, runGsd walks the merged base cwd, reads each per-task file, and writes the consolidated blackboard.json. This schema is the post-execution audit/retro substrate (consumed by GSD-7 milestone reports), NOT a runtime channel between tasks.",
+  "type": "object",
+  "required": ["status", "files_changed", "summary", "produces", "gates", "attempts"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["passed", "failed"],
+      "description": "Whether the agent considered the task complete with all gates green."
+    },
+    "files_changed": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Repo-relative paths the agent touched in its worktree."
+    },
+    "summary": {
+      "type": "string",
+      "description": "One- or two-paragraph machine-readable summary of what was done."
+    },
+    "produces": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Realized symbol map: { symbolName: signature-or-shape-string }. Mirrors the task's declared produces but with the actually-implemented signatures."
+    },
+    "gates": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/GateRun" },
+      "description": "One entry per gate command run. Array (not lint/build/test object) so arbitrary project-configured gateCommands are supported."
+    },
+    "attempts": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of internal TDD-loop iterations the agent took before declaring done."
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "GateRun": {
+      "type": "object",
+      "required": ["command", "status", "output"],
+      "properties": {
+        "command": { "type": "string", "minLength": 1 },
+        "status": {
+          "type": "string",
+          "enum": ["pass", "fail"]
+        },
+        "output": {
+          "type": "string",
+          "description": "Truncated stdout/stderr from the gate run (e.g., last 2000 chars)."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/contracts/taskgraph-gsd.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "taskgraph-gsd.json",
+  "_source": "docs/features/COMP-GSD-2/blueprint.md",
+  "_roadmap": "COMP-GSD-2",
+  "title": "TaskGraphGsd",
+  "description": "Output of the gsd pipeline's decompose_gsd step. Extends the bare TaskGraph (from build.stratum.yaml's decompose) with required produces/consumes per task, sourced from the blueprint's Boundary Map. Each task carries a rich `description` string pre-baked with the spec context that Stratum's parallel_dispatch interpolation cannot carry on its own.",
+  "type": "object",
+  "required": ["tasks"],
+  "properties": {
+    "tasks": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/Task" }
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "Task": {
+      "type": "object",
+      "required": ["id", "files_owned", "files_read", "depends_on", "description", "produces", "consumes"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "files_owned": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Files this task may write. Must not overlap with other tasks' files_owned (enforced by no_file_conflicts ensure)."
+        },
+        "files_read": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Files this task may read but not write."
+        },
+        "depends_on": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Task ids that must complete before this one."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Rich prompt fragment containing the per-task spec context (produces/consumes/slice/upstream summary/gates). Packed at decompose time because Stratum's parallel_dispatch only interpolates a fixed set of tokens."
+        },
+        "produces": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/ProducesEntry" },
+          "description": "Symbols this task lands. Sourced from the matching Boundary Map slice."
+        },
+        "consumes": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/ConsumesEntry" },
+          "description": "Symbols this task may import from upstream tasks (resolved at end-of-step merge in topological order)."
+        }
+      },
+      "additionalProperties": true
+    },
+    "ProducesEntry": {
+      "type": "object",
+      "required": ["file", "symbols", "kind"],
+      "properties": {
+        "file": { "type": "string", "minLength": 1 },
+        "symbols": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["interface", "type", "function", "class", "const", "hook", "component"],
+          "description": "Symbol kind. Mirrors lib/boundary-map.js KIND_ALLOWLIST."
+        }
+      },
+      "additionalProperties": false
+    },
+    "ConsumesEntry": {
+      "type": "object",
+      "required": ["from", "file", "symbols"],
+      "properties": {
+        "from": {
+          "type": "string",
+          "pattern": "^S\\d{2,}$",
+          "description": "Upstream slice id (S01, S02, ...)."
+        },
+        "file": { "type": "string", "minLength": 1 },
+        "symbols": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}