@smartmemory/compose 0.3.6-beta → 0.3.8

package/presets/team-feature.stratum.yaml

@@ -4,47 +4,65 @@
 # Pattern:     Decompose → parallel implement with files_owned → verify
 # Capability:  Orchestrator decomposes, implementers have full access
 # Isolation:   worktree (each task in its own worktree)
-# Merge:       sequential_apply (patches applied in topo order)
+# Merge:       sequential (patches applied in topo order)
 #
 # Use with:    compose build <feature-code> --team feature
-# Customize:   Copy to your project's pipelines/ as team-feature.stratum.yaml and edit.
+# Customize:   Copy BOTH team-feature.stratum.yaml AND team-feature.profiles.json into
+#              your project's pipelines/ and edit. Copying only the YAML is a trap:
+#              a project-local spec wins resolution, but profiles load only from an
+#              ADJACENT sidecar and fail open — so the tool restrictions vanish.
+#
+# COMP-PIPELINE-QUARANTINE: re-authored from v0.3 to TS v1.
+#   - `parallel_dispatch` + `source`/`intent_template` becomes a `fanout:` block
+#     with `over`/`dispatch: consumer`/`steps`, matching the construct the build
+#     conversion settled on. The per-item prompt reads `${item}` rather than
+#     `{task.*}`, so the item's own fields (id, description, files_owned,
+#     files_read) travel as data instead of being string-substituted.
+#   - Agent PROFILE strings move to team-feature.profiles.json — v1 accepts only
+#     the bare `claude`/`codex` literals, and compose re-applies the profiles at
+#     invocation.
+#   - `no_file_conflicts(...)` is not an engine predicate; file-ownership
+#     exclusivity is stated as a hard rule in the decompose prompt (as the build
+#     pipeline's own decompose step does) and remains enforced compose-side.
+#   - `retries: 2` -> `attempts: 3`.
+#   - An `execute_merge` gate was ADDED after the worktree fanout: the engine
+#     requires one (CONSUMER_WORKTREE_GATE_REQUIRED) and the v0.3 preset had none,
+#     so merging per-task worktree patches was never a decision point.
 
-version: "0.3"
+version: 1
 
 contracts:
   TaskGraph:
-    tasks:
-      type: array
-      values: [{type: object}]
-  VerifyResult:
-    tests_pass: {type: string}
-    summary: {type: string}
+    tasks: object[]
 
-workflow:
-  name: team-feature
-  description: "Multi-agent parallel feature implementation"
-  input:
-    featureCode:
-      type: string
-      required: true
-    description:
-      type: string
-      required: true
+  TaskResult:
+    outcome: string
+    summary: string
+    files_changed: string[]?
+
+  VerifyResult:
+    tests_pass: string
+    summary: string
 
 flows:
-  team-feature:
+  entry: team_feature
+  team_feature:
     input:
-      featureCode: {type: string}
-      description: {type: string}
-    output: VerifyResult
+      featureCode: string
+      description: string
+    output:
+      from: "${verify.output}"
+      contract: VerifyResult
+    # Required by the engine once any gate declares on_revise, since a revise edge
+    # is what makes a flow able to loop (GATE_REVISE_REQUIRES_MAX_ROUNDS).
+    max_rounds: 10
     steps:
       - id: decompose
-        type: decompose
-        agent: "claude:orchestrator"
-        intent: >
-          Read the feature description and any existing plan/blueprint docs.
-          Break down this feature into parallel implementation tasks.
-          Each task must have:
+        agent: claude
+        do: >
+          Read the description for ${input.featureCode} (${input.description}) and
+          any existing plan/blueprint docs. Break the feature down into parallel
+          implementation tasks. Each task must have:
           - id: unique short identifier
           - description: what to implement
           - files_owned: list of files this task may create or modify
@@ -52,54 +70,63 @@ flows:
           - depends_on: list of task ids that must complete first (empty if independent)
 
           Rules:
-          - No two tasks may share files_owned (each file has exactly one owner)
+          - No two tasks may share files_owned (each file has exactly one owner).
+            Reject the decomposition and redo it if any file would have two owners.
           - Minimize dependencies — prefer independent parallel tasks
           - Each task should be completable in one focused session
           - Target 2-4 tasks for a typical feature
-        inputs:
-          featureCode: "$.input.featureCode"
-          description: "$.input.description"
-        output_contract: TaskGraph
+        out: TaskGraph
         ensure:
-          - "len(result.tasks) >= 1"
-          - "len(result.tasks) <= 6"
-          - "no_file_conflicts(result.tasks)"
-        retries: 2
+          - expr: "len(result.tasks) >= 1"
+          - expr: "len(result.tasks) <= 6"
+        attempts: 3
 
       - id: execute
-        type: parallel_dispatch
-        source: "$.steps.decompose.output.tasks"
-        agent: "claude:implementer"
-        max_concurrent: 3
-        isolation: worktree
-        require: all
-        merge: sequential_apply
-        intent_template: >
-          Implement this task using TDD. Write the test first, watch it fail,
-          implement, watch it pass.
-
-          Task: {task.description}
-          You own these files (may create/modify): {task.files_owned}
-          You may read (but NOT modify): {task.files_read}
+        after: [decompose]
+        fanout:
+          over: "${decompose.output.tasks}"
+          dispatch: consumer
+          concurrency: 3
+          isolation: worktree
+          require: all
+          merge: sequential
+          steps:
+            - agent: claude
+              do: >
+                Implement the task described by ${item} using TDD. Write the test
+                first, watch it fail, implement, and watch it pass. Honor the
+                item's id, description, files_owned (you may create/modify these)
+                and files_read (you may read but NOT modify these).
+                Return {outcome, summary, files_changed}.
+              out: TaskResult
 
-          Feature: {task.id}
-        depends_on: [decompose]
+      # Engine invariant (CONSUMER_WORKTREE_GATE_REQUIRED): a consumer worktree
+      # fanout must be followed by an unconditional gate. The v0.3 preset had no
+      # such step — it declared `merge: sequential_apply` and moved straight on —
+      # so the merge of per-task worktree patches was never a decision point.
+      # This is the same execute -> execute_merge pairing build.stratum.yaml uses.
+      - id: execute_merge
+        after: [execute]
+        gate:
+          on_approve: verify
+          on_revise: execute
+          on_kill: null
+          max_rounds: 10
 
       - id: verify
-        agent: "claude:orchestrator"
-        depends_on: [execute]
-        intent: >
-          All implementation tasks are complete and merged. Run the test suite
-          to verify everything works together. Check that:
+        after: [execute_merge]
+        agent: claude
+        do: >
+          All implementation tasks for ${input.featureCode} are complete and
+          merged. Run the test suite to verify everything works together. Check
+          that:
           1. All tests pass
           2. No merge conflicts remain
-          3. The feature matches the original task description
+          3. The feature matches the original description
 
           Report tests_pass as "true" or "false" with details.
-        inputs:
-          featureCode: "$.input.featureCode"
-        output_contract: VerifyResult
+        out: VerifyResult
         ensure:
-          - "result.tests_pass == 'true'"
-          - "result.summary != ''"
-        retries: 2
+          - expr: "result.tests_pass == 'true'"
+          - expr: "len(result.summary) > 0"
+        attempts: 3

package/presets/team-research.profiles.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "COMP-PIPELINE-QUARANTINE: compose-owned agent profiles for team-research.stratum.yaml. The TS engine accepts only the literal claude|codex agent, so the profile strings (tool restrictions + model tier) that the v0.3->v1 conversion stripped live here, keyed by step id, and are applied compose-side at invocation (lib/build.js loadPipelineProfiles). These are load-bearing, not cosmetic: the explore fanout runs at isolation:none, so without the read-only restriction its explorers would hold full write capability while claiming to be read-only exploration.",
+  "plan": "claude:orchestrator",
+  "explore": "claude:read-only-reviewer",
+  "synthesize": "claude:orchestrator"
+}

package/presets/team-research.stratum.yaml

@@ -1,108 +1,117 @@
 # TEAM PRESET: research
 #
 # Purpose:     Parallel exploration for cold-start discovery
-# Pattern:     Triage → parallel_dispatch explorers → synthesize findings
-# Capability:  codebase/docs use read-only-reviewer, web uses read-only-researcher
+# Pattern:     Plan → fanout explorers → synthesize findings
+# Capability:  ALL explorers run read-only-reviewer (see the limitation note below)
 # Isolation:   none (read-only exploration)
 # Merge:       Sequential synthesis step
 #
 # Use with:    compose build <feature-code> --team research
-# Customize:   Copy to your project's pipelines/ as team-research.stratum.yaml and edit.
-
-version: "0.3"
+# Customize:   Copy BOTH team-research.stratum.yaml AND team-research.profiles.json into
+#              your project's pipelines/ and edit. Copying only the YAML is a trap:
+#              a project-local spec wins resolution, but profiles load only from an
+#              ADJACENT sidecar and fail open — so the tool restrictions vanish.
+#
+# COMP-PIPELINE-QUARANTINE: re-authored from v0.3 to TS v1.
+#   - `parallel_dispatch` + `source`/`intent_template`/`output_fields` becomes a
+#     `fanout:` block with `over`/`dispatch: consumer`/`steps`, matching the
+#     construct the build conversion settled on. The per-item prompt reads
+#     `${item}` instead of `{task.*}`.
+#   - Agent PROFILE strings (`claude:orchestrator`, `claude:read-only-reviewer`)
+#     are not engine values — v1 accepts only the bare `claude`/`codex` literals.
+#     They move to team-research.profiles.json, keyed by step id, and compose
+#     re-applies them at invocation. Dropping them instead would silently hand
+#     read-only explorers full write capability.
+#   - `retries: N` -> `attempts: N + 1`.
+#
+# KNOWN LIMITATION, inherited from v0.3 and NOT introduced here: the header used
+# to claim the web lane runs `read-only-researcher`, but a consumer fanout binds
+# ONE profile for the whole step (lib/build.js resolves it per fanout step, not
+# per item), so every explorer gets `explore`'s profile. read-only-reviewer has
+# no WebSearch/WebFetch, so the web task cannot actually search the web. The
+# claim has been corrected rather than left as an aspiration; giving the lanes
+# distinct capabilities needs either per-item profile resolution or three
+# separate steps, which is a redesign.
 
 contracts:
   ResearchTaskList:
-    tasks:
-      type: array
-      values: [{type: object}]
-    topic: {type: string}
+    tasks: object[]
+    topic: string
+
   ExplorerFindings:
-    sources: {type: string}
-    patterns: {type: string}
-    open_questions: {type: string}
+    sources: string
+    patterns: string
+    open_questions: string
+
   ResearchResult:
-    synthesis: {type: string}
-    recommendations: {type: string}
-    summary: {type: string}
+    synthesis: string
+    recommendations: string
+    summary: string
 
-workflow:
-  name: team-research
-  description: "Parallel multi-source research and synthesis"
-  input:
-    featureCode:
-      type: string
-      required: true
-    description:
-      type: string
-      required: true
+version: 1
 
 flows:
-  team-research:
+  entry: team_research
+  team_research:
     input:
-      featureCode: {type: string}
-      description: {type: string}
-    output: ResearchResult
+      featureCode: string
+      description: string
+    output:
+      from: "${synthesize.output}"
+      contract: ResearchResult
     steps:
       - id: plan
-        agent: "claude:orchestrator"
-        intent: >
-          Plan the research for this feature. Read the feature description
-          and any existing docs. Produce a task list with 3 research tasks:
+        agent: claude
+        do: >
+          Plan the research for ${input.featureCode}. Read the feature description
+          (${input.description}) and any existing docs. Produce a task list with
+          exactly 3 research tasks:
 
-          1. id: "codebase", agent: "claude:read-only-reviewer"
-             - Explore the local codebase for relevant patterns, files, conventions
-          2. id: "web", agent: "claude:read-only-researcher"
-             - Search the web for best practices, library docs, similar implementations
-          3. id: "docs", agent: "claude:read-only-reviewer"
-             - Read local docs, READMEs, specs, ADRs for relevant context
+          1. id: "codebase" — explore the local codebase for relevant patterns,
+             files and conventions
+          2. id: "web" — search the web for best practices, library docs and
+             similar implementations
+          3. id: "docs" — read local docs, READMEs, specs and ADRs for context
 
           Each task must have: id, description, agent.
           Also output the research topic derived from the feature description.
-        inputs:
-          featureCode: "$.input.featureCode"
-          description: "$.input.description"
-        output_contract: ResearchTaskList
+        out: ResearchTaskList
         ensure:
-          - "len(result.tasks) == 3"
-        retries: 2
+          - expr: "len(result.tasks) == 3"
+        attempts: 3
 
       - id: explore
-        type: parallel_dispatch
-        source: "$.steps.plan.output.tasks"
-        agent: "claude:read-only-reviewer"
-        max_concurrent: 3
-        isolation: none
-        require: all
-        intent_template: >
-          Research this topic: {task.description}
-
-          Find relevant sources, patterns, and open questions.
-          List sources with file:line references (for code) or URLs (for web).
-          Note patterns that could inform the implementation.
-          List open questions that need answers before implementation.
-        output_fields:
-          sources: {type: string}
-          patterns: {type: string}
-          open_questions: {type: string}
-        ensure:
-          - "result.sources is not None"
-        depends_on: [plan]
+        after: [plan]
+        fanout:
+          over: "${plan.output.tasks}"
+          dispatch: consumer
+          concurrency: 3
+          isolation: none
+          require: all
+          merge: sequential
+          steps:
+            - agent: claude
+              do: >
+                Research the topic described by ${item}. Honor its id, description
+                and agent fields. Find relevant sources, patterns and open
+                questions. List sources with file:line references (for code) or
+                URLs (for web). Note patterns that could inform the
+                implementation. List open questions that need answers before
+                implementation.
+              out: ExplorerFindings
 
       - id: synthesize
-        agent: "claude:orchestrator"
-        depends_on: [explore]
-        intent: >
-          Synthesize findings from all research explorers. Cross-reference
-          sources. Identify consensus patterns and contradictions. Produce
-          actionable recommendations for the feature implementation.
-          Write a one-sentence summary.
-        inputs:
-          research_results: "$.steps.explore.output"
-          topic: "$.steps.plan.output.topic"
-        output_contract: ResearchResult
+        after: [explore]
+        agent: claude
+        do: >
+          Synthesize the findings from all research explorers (${explore.output})
+          on the topic ${plan.output.topic}. Cross-reference sources. Identify
+          consensus patterns and contradictions. Produce actionable
+          recommendations for implementing ${input.featureCode}. Write a
+          one-sentence summary.
+        out: ResearchResult
         ensure:
-          - "result.synthesis != ''"
-          - "result.recommendations != ''"
-          - "result.summary != ''"
-        retries: 2
+          - expr: "len(result.synthesis) > 0"
+          - expr: "len(result.recommendations) > 0"
+          - expr: "len(result.summary) > 0"
+        attempts: 3

package/presets/team-review.profiles.json

@@ -0,0 +1,8 @@
+{
+  "_comment": "COMP-PIPELINE-QUARANTINE: compose-owned agent profiles for team-review.stratum.yaml. The TS engine accepts only the literal claude|codex agent, so the profile strings (tool restrictions + model tier) that the v0.3->v1 conversion stripped live here, keyed by step id, and are applied compose-side at invocation (lib/build.js loadPipelineProfiles). The review_lenses fanout runs at isolation:none and MUST bind the read-only-reviewer restriction — without it the lenses would hold write capability while the preset advertises read-only review.",
+  "_reduceSteps": ["merge"],
+  "_reduceSteps_comment": "ReviewResult-out steps that MERGE/deduplicate rather than review. They get review normalization but never the review scaffold (H1, mirroring build.profiles.json).",
+  "triage": "claude:orchestrator",
+  "review_lenses": "claude:read-only-reviewer",
+  "merge": "claude:orchestrator"
+}

package/presets/team-review.stratum.yaml

@@ -1,56 +1,71 @@
 # TEAM PRESET: review
 #
 # Purpose:     Parallel multi-lens review after implementation
-# Pattern:     Triage → parallel_dispatch reviewers → merge findings → gate
+# Pattern:     Triage → fanout reviewers → merge findings → gate
 # Capability:  Agents use read-only-reviewer profile (Read/Grep/Glob/Agent only)
 # Isolation:   none (reviewers read shared state, don't modify)
 # Merge:       Deduplication step consolidates findings
 #
 # Use with:    compose build <feature-code> --team review
-# Customize:   Copy to your project's pipelines/ as team-review.stratum.yaml and edit.
+# Customize:   Copy BOTH team-review.stratum.yaml AND team-review.profiles.json into
+#              your project's pipelines/ and edit. Copying only the YAML is a trap:
+#              a project-local spec wins resolution, but profiles load only from an
+#              ADJACENT sidecar and fail open — so the tool restrictions vanish, and
+#              the review gate stops seeing its reducer's result entirely.
+#
+# COMP-PIPELINE-QUARANTINE: re-authored from v0.3 to TS v1.
+#   - `parallel_dispatch` becomes a `fanout:` block; the per-lens prompt reads
+#     `${item}` and honors its lens_name/lens_focus/confidence_gate/exclusions
+#     fields rather than string-substituting them.
+#   - Agent PROFILE strings move to team-review.profiles.json. Load-bearing here:
+#     the lenses run at isolation:none, so losing the read-only restriction would
+#     hand "read-only reviewers" full write capability.
+#   - The merge step's `ensure: result.clean == true` is REMOVED and the
+#     cleanliness decision becomes a gate, mirroring what the build conversion
+#     learned (build.stratum.yaml, note I1): a reducer cannot converge by
+#     retrying, because re-running it re-merges the SAME frozen lens outputs.
+#     Keeping the ensure would spin the reducer until its attempts ran out and
+#     then fail the flow, with no chance of the code being fixed in between.
+#     The gate is named `review_gate` because compose resolves THAT id
+#     programmatically — clean approves, dirty runs the corrective fixer and
+#     revises back to triage so the lenses re-run on fixed code. A differently
+#     named gate is inert, which is what the first draft shipped.
+#   - `retries: 2` -> `attempts: 3`.
 
-version: "0.3"
+version: 1
 
 contracts:
   TriageResult:
-    tasks:
-      type: array
-      values: [{type: object}]
-    diff: {type: string}
+    tasks: object[]
+    diff: string
+
   # Canonical schema — STRAT-CLAUDE-EFFORT-PARITY. Local MergedReviewResult removed.
   ReviewResult:
-    clean:      {type: boolean}
-    summary:    {type: string}
-    findings:   {type: array}
-    meta:       {type: object}
-    lenses_run: {type: array}
-    auto_fixes: {type: array}
-    asks:       {type: array}
-
-workflow:
-  name: team-review
-  description: "Parallel multi-lens code review"
-  input:
-    featureCode:
-      type: string
-      required: true
-    description:
-      type: string
-      required: true
+    clean: boolean
+    summary: string
+    findings: object[]
+    meta: object
+    lenses_run: string[]
+    auto_fixes: object[]
+    asks: object[]
 
 flows:
-  team-review:
+  entry: team_review
+  team_review:
     input:
-      featureCode: {type: string}
-      description: {type: string}
-    output: ReviewResult
+      featureCode: string
+      description: string
+    output:
+      from: "${merge.output}"
+      contract: ReviewResult
+    max_rounds: 10
     steps:
       - id: triage
-        agent: "claude:orchestrator"
-        intent: >
-          Gather the git diff for this feature and decide which review lenses
-          to activate. Read the changed files. Produce a task list with one
-          entry per lens. Each task must have:
+        agent: claude
+        do: >
+          Gather the git diff for ${input.featureCode} (${input.description}) and
+          decide which review lenses to activate. Read the changed files. Produce
+          a task list with one entry per lens. Each task must have:
           - id: lens name (e.g. "security", "performance", "architecture")
           - lens_name: same as id
           - lens_focus: one-sentence description of what to look for
@@ -59,55 +74,58 @@ flows:
 
           Always include: security, performance, architecture.
           Include the full git diff in your output.
-        inputs:
-          featureCode: "$.input.featureCode"
-          description: "$.input.description"
-        output_contract: TriageResult
+        out: TriageResult
         ensure:
-          - "len(result.tasks) >= 3"
-        retries: 2
+          - expr: "len(result.tasks) >= 3"
+        attempts: 3
 
       - id: review_lenses
-        type: parallel_dispatch
-        source: "$.steps.triage.output.tasks"
-        agent: "claude:read-only-reviewer"
-        max_concurrent: 4
-        isolation: none
-        require: all
-        intent_template: >
-          You are reviewing a code diff as the {lens_name} reviewer.
-
-          Focus: {lens_focus}
-          Confidence gate: only report findings with confidence >= {confidence_gate}/10.
-          Exclusions: do NOT flag {exclusions}.
+        after: [triage]
+        fanout:
+          over: "${triage.output.tasks}"
+          dispatch: consumer
+          concurrency: 4
+          isolation: none
+          require: all
+          merge: sequential
+          steps:
+            - agent: claude
+              do: >
+                Review the code diff as the reviewer described by ${item}. Honor
+                its lens_name, lens_focus, confidence_gate (only report findings
+                at or above that confidence) and exclusions (never flag those).
 
-          Return JSON: { "clean": boolean, "findings": <ReviewResult finding items> }
-          where each finding has: lens, file, line, severity (must-fix|should-fix|nit),
-          finding (description), confidence (1-10), applied_gate (integer).
-
-          If no issues found, return { "clean": true, "findings": [] }.
-        output_fields:
-          clean: {type: string}
-          findings: {type: string}
-        ensure:
-          - "result.findings is not None"
-        depends_on: [triage]
+                Return the canonical ReviewResult shape. Each finding has: lens,
+                file, line, severity (must-fix|should-fix|nit), finding
+                (description), confidence (1-10), applied_gate (integer).
+                If no issues are found, return clean=true with no findings.
+              out: ReviewResult
 
+      # Reducer: NO ensure by construction — see the header note. It consolidates,
+      # it does not judge, and it cannot fix anything by being retried.
       - id: merge
-        agent: "claude:orchestrator"
-        depends_on: [review_lenses]
-        intent: >
-          Consolidate ReviewResult arrays from all review lenses into a single
-          canonical ReviewResult. Deduplicate findings (same file:line+lens,
-          keep highest confidence; carry over its applied_gate). Rank by
-          severity (must-fix first, then should-fix, then nit). Set clean=true
-          only if zero must-fix AND zero should-fix findings remain. Write a
-          one-sentence summary.
-        inputs:
-          review_results: "$.steps.review_lenses.output"
-          reduce_mode: "true"
-        output_contract: ReviewResult
-        ensure:
-          - "result.clean == True"
-          - "result.summary != ''"
-        retries: 2
+        after: [review_lenses]
+        agent: claude
+        do: >
+          Consolidate the ReviewResults from all review lenses
+          (${review_lenses.output}) into a single canonical ReviewResult.
+          Deduplicate findings (same file:line+lens, keep the highest confidence
+          and carry over its applied_gate). Rank by severity (must-fix first,
+          then should-fix, then nit). Set clean=true only if zero must-fix AND
+          zero should-fix findings remain. Write a one-sentence summary.
+        out: ReviewResult
+        attempts: 3
+
+      # The cleanliness decision, resolved PROGRAMMATICALLY by compose, not by a
+      # human. The gate MUST be called `review_gate`: lib/build.js keys the
+      # corrective-fixer path on that exact id. Named anything else (the first
+      # draft called it `merge_gate`) the gate is inert — approving it can
+      # complete the flow with clean:false, and revising re-reviews unchanged code
+      # because no fixer ever runs. Caught in review.
+      - id: review_gate
+        after: [merge]
+        gate:
+          on_approve: null
+          on_revise: triage
+          on_kill: null
+          max_rounds: 10