@smartmemory/compose 0.3.6-beta → 0.3.8

package/pipelines/refactor.stratum.yaml

@@ -6,7 +6,7 @@
 #   steps: 7
 #   estimated_minutes: 45
 
-version: "0.1"
+version: 1
 
 # refactor pipeline
 #
@@ -16,154 +16,154 @@ version: "0.1"
 #   3. plan        — write a step-by-step refactoring plan
 #   4. execute     — apply refactoring changes incrementally
 #   5. test        — run full test suite, compare against snapshot
-#   6. review      — codex reviews refactored code for correctness
+#   6. review      — cross-model review of the refactored code for correctness
 #   7. ship        — commit and report
 #
-# Inputs:
-#   task — what to refactor (module, pattern, or scope description)
+# COMP-PIPELINE-QUARANTINE: re-authored from v0.1 to TS v1. Linear chain, no
+# gates or backward routing. `retries: N` -> `attempts: N + 1` (v0.1 counted
+# retries AFTER the first try). The `outcome` enum moved into the contract.
+# review declares `agent: codex` so the cross-model pass the header always
+# promised is an actual dispatch rather than a hope.
 #
-# Usage:
-#   stratum_plan <this yaml> "refactor" {"task": "..."}
+#
+# COMP-PIPELINE-QUARANTINE round 2: the flow input is the RUNNER's envelope, not
+# a bespoke `task`. runBuild derives plan inputs from the MODE, not from the spec
+# (lib/build.js startFresh), and feature mode always sends
+# {featureCode, description, implementer_agent, reviewer_agent} plus an optional
+# pre_merge_gate. Declaring `task` meant this spec resolved but could never plan —
+# making it reachable via `--template` without this change just moved the failure
+# from "not found" to a failed run. `${input.description}` carries what `task` did.
+# Inputs (the runner's feature envelope):
+#   featureCode  — the feature/work code
+#   description  — what to do; this is what the old `task` input carried
 
 contracts:
   RefactorResult:
-    phase:    {type: string}
-    summary:  {type: string}
-    outcome:  {type: string, values: [complete, failed]}
+    phase: string
+    summary: string
+    outcome: complete|skipped|failed   # `skipped` is reachable: compose offers an interactive skip
+
+  # The `ship` step is INTERCEPTED by compose (lib/build.js shouldInterceptShip:
+  # any step named `ship` outside plan mode), which submits this shape regardless
+  # of what the spec declares. It is a SEPARATE contract, not extra optional
+  # fields on the pipeline's own result: outputFieldsToJsonSchema marks every
+  # declared field required and ignores `?`, so widening the shared contract
+  # would instruct every other step to return commit metadata it has no business
+  # producing. Third instance of this defect class; see COMP-SHIP-CONTRACT.
+  ShipResult:
+    phase: string
+    artifact: string
+    outcome: complete|skipped|failed
+    summary: string
+    files_changed: string[]?
+    commit_hash: string?
 
   TestResult:
-    passing:  {type: boolean}
-    summary:  {type: string}
-    failures: {type: array}
-
+    passing: boolean
+    summary: string
+    failures: string[]
+
+  # CANONICAL ReviewResult — STRAT-CLAUDE-EFFORT-PARITY. It MUST carry meta,
+  # lenses_run, auto_fixes and asks even though this pipeline never sets them by
+  # hand: compose enables review normalization for any step whose out contract is
+  # NAMED ReviewResult (deriveOrdinaryReviewScaffold), and the normalizer always
+  # stamps those four fields. Engine contracts are strict, so a narrower
+  # declaration makes every review step fail with unrecognized_keys and exhaust
+  # its attempts — the same defect class as COMP-SHIP-CONTRACT. Caught in review.
   ReviewResult:
-    clean:    {type: boolean}
-    summary:  {type: string}
-    findings: {type: array}
-
-functions:
-  snapshot:
-    mode: compute
-    intent: >
-      Run the full test suite and capture results as a baseline snapshot.
-      Record pass/fail counts and test names. Return a summary of the
-      current test state before any changes.
-    input:
-      task: {type: string}
-    output: RefactorResult
-    retries: 1
-
-  analyze:
-    mode: compute
-    intent: >
-      Analyze the target code for refactoring opportunities. Identify code
-      smells, duplication, coupling issues, and improvement targets.
-      Return a structured summary of findings.
-    input:
-      task: {type: string}
-    output: RefactorResult
-    retries: 1
-
-  plan:
-    mode: compute
-    intent: >
-      Write a step-by-step refactoring plan. Each step should be a safe,
-      incremental change that preserves behavior. Include file paths and
-      expected changes.
-    input:
-      task: {type: string}
-    output: RefactorResult
-    retries: 1
-
-  execute:
-    mode: compute
-    intent: >
-      Apply the refactoring changes incrementally following the plan.
-      Make each change as small as possible. Return a summary of all
-      modifications made.
-    input:
-      task: {type: string}
-    output: RefactorResult
-    retries: 3
-
-  test:
-    mode: compute
-    intent: >
-      Run the full test suite. Compare results against the baseline snapshot.
-      Return structured JSON: { "passing": boolean, "summary": string, "failures": string[] }.
-      All tests that passed before must still pass.
-    input:
-      task: {type: string}
-    output: TestResult
-    ensure:
-      - "result.passing == true"
-    retries: 5
-
-  review:
-    mode: compute
-    intent: >
-      Review the refactored code for correctness and quality. Verify that
-      behavior is preserved and the code is cleaner than before.
-      Return { "clean": boolean, "summary": string, "findings": string[] }.
-    input:
-      task: {type: string}
-    output: ReviewResult
-    ensure:
-      - "result.clean == true"
-    retries: 3
-
-  ship:
-    mode: compute
-    intent: >
-      Commit all changes with a descriptive message. Return a summary.
-    input:
-      task: {type: string}
-    output: RefactorResult
-    retries: 1
+    clean: boolean
+    summary: string
+    findings: array
+    meta: object
+    lenses_run: string[]
+    auto_fixes: array
+    asks: array
 
 flows:
+  entry: refactor
   refactor:
     input:
-      task: {type: string}
-    output: RefactorResult
+      featureCode: string
+      description: string
+      implementer_agent: string?
+      reviewer_agent: string?
+      pre_merge_gate: string[]?
+    output:
+      from: "${ship.output}"
+      contract: ShipResult
     steps:
       - id: snapshot
-        function: snapshot
-        inputs:
-          task: "$.input.task"
+        agent: claude
+        do: >
+          Run the full test suite and capture the results as a baseline snapshot
+          before any changes to ${input.description}. Record pass/fail counts and test
+          names. Return a summary of the current test state.
+        out: RefactorResult
+        attempts: 2
 
       - id: analyze
-        function: analyze
-        inputs:
-          task: "$.input.task"
-        depends_on: [snapshot]
+        after: [snapshot]
+        agent: claude
+        do: >
+          Analyze ${input.description} for refactoring opportunities. Identify code
+          smells, duplication, coupling issues and improvement targets. Return a
+          structured summary of findings.
+        out: RefactorResult
+        attempts: 2
 
       - id: plan
-        function: plan
-        inputs:
-          task: "$.input.task"
-        depends_on: [analyze]
+        after: [analyze]
+        agent: claude
+        do: >
+          Write a step-by-step refactoring plan for ${input.description} addressing
+          ${analyze.output.summary}. Each step must be a safe, incremental change
+          that preserves behavior. Include file paths and expected changes.
+        out: RefactorResult
+        attempts: 2
 
       - id: execute
-        function: execute
-        inputs:
-          task: "$.input.task"
-        depends_on: [plan]
+        after: [plan]
+        agent: claude
+        do: >
+          Apply the refactoring changes incrementally, following the plan:
+          ${plan.output.summary}. Make each change as small as possible. Return
+          a summary of all modifications made.
+        out: RefactorResult
+        attempts: 4
 
       - id: test
-        function: test
-        inputs:
-          task: "$.input.task"
-        depends_on: [execute]
+        after: [execute]
+        agent: claude
+        do: >
+          Run the full test suite and compare the results against the baseline
+          snapshot: ${snapshot.output.summary}. Every test that passed before
+          MUST still pass — this is the behavior-preservation check, not a
+          general green-suite check. Return structured JSON:
+          { "passing": boolean, "summary": string, "failures": string[] }.
+        out: TestResult
+        ensure:
+          - expr: "result.passing == true"
+        attempts: 6
 
       - id: review
-        function: review
-        inputs:
-          task: "$.input.task"
-        depends_on: [test]
+        after: [test]
+        agent: codex
+        do: >
+          Review the refactored code for ${input.description} for correctness and
+          quality. Verify that behavior is preserved and the code is cleaner than
+          before. If this is a retry, fix the previous findings before
+          re-reviewing. Return { "clean": boolean, "summary": string,
+          "findings": string[] }.
+        out: ReviewResult
+        ensure:
+          - expr: "result.clean == true"
+        attempts: 4
 
       - id: ship
-        function: ship
-        inputs:
-          task: "$.input.task"
-        depends_on: [review]
+        after: [review]
+        agent: claude
+        do: >
+          Commit all changes for ${input.description} with a descriptive message.
+          Return a summary.
+        out: ShipResult
+        attempts: 2

package/pipelines/research.stratum.yaml

@@ -6,7 +6,7 @@
 #   steps: 3
 #   estimated_minutes: 15
 
-version: "0.1"
+version: 1
 
 # research pipeline
 #
@@ -15,74 +15,72 @@ version: "0.1"
 #   2. analyze  — synthesize findings, identify patterns and gaps
 #   3. report   — produce a structured summary with recommendations
 #
-# Inputs:
-#   task — research question or topic to explore
+# COMP-PIPELINE-QUARANTINE: re-authored from v0.1 to TS v1. Linear chain, no
+# gates or backward routing. `retries: 1` -> `attempts: 2` (v0.1 counted retries
+# AFTER the first try, so a bare rename would leave every step with no retry at
+# all). The `outcome` enum moved from the old `values:` list into the contract.
 #
-# Usage:
-#   stratum_plan <this yaml> "research" {"task": "..."}
+#
+# COMP-PIPELINE-QUARANTINE round 2: the flow input is the RUNNER's envelope, not
+# a bespoke `task`. runBuild derives plan inputs from the MODE, not from the spec
+# (lib/build.js startFresh), and feature mode always sends
+# {featureCode, description, implementer_agent, reviewer_agent} plus an optional
+# pre_merge_gate. Declaring `task` meant this spec resolved but could never plan —
+# making it reachable via `--template` without this change just moved the failure
+# from "not found" to a failed run. `${input.description}` carries what `task` did.
+# Inputs (the runner's feature envelope):
+#   featureCode  — the feature/work code
+#   description  — what to do; this is what the old `task` input carried
 
 contracts:
   ResearchResult:
-    phase:    {type: string}
-    artifact: {type: string}
-    summary:  {type: string}
-    outcome:  {type: string, values: [complete, failed]}
-
-functions:
-  gather:
-    mode: compute
-    intent: >
-      Collect sources relevant to the research topic. Search the codebase,
-      read documentation, and gather external references. Return a summary
-      of sources found and key data points.
-    input:
-      task: {type: string}
-    output: ResearchResult
-    retries: 1
-
-  analyze:
-    mode: compute
-    intent: >
-      Synthesize the gathered information. Identify patterns, contradictions,
-      gaps, and insights. Organize findings into themes. Return a structured
-      analysis summary.
-    input:
-      task: {type: string}
-    output: ResearchResult
-    retries: 1
-
-  report:
-    mode: compute
-    intent: >
-      Produce a structured research report with findings, analysis, and
-      actionable recommendations. Write to an appropriate file path.
-      Return the artifact path and summary.
-    input:
-      task: {type: string}
-    output: ResearchResult
-    ensure:
-      - "result.outcome == 'complete'"
-    retries: 1
+    phase: string
+    artifact: string
+    summary: string
+    outcome: complete|skipped|failed   # `skipped` is reachable: compose offers an interactive skip
 
 flows:
+  entry: research
   research:
     input:
-      task: {type: string}
-    output: ResearchResult
+      featureCode: string
+      description: string
+      implementer_agent: string?
+      reviewer_agent: string?
+      pre_merge_gate: string[]?
+    output:
+      from: "${report.output}"
+      contract: ResearchResult
     steps:
       - id: gather
-        function: gather
-        inputs:
-          task: "$.input.task"
+        agent: claude
+        do: >
+          Collect sources relevant to the research topic: ${input.description}.
+          Search the codebase, read documentation, and gather external
+          references. Return a summary of sources found and key data points.
+        out: ResearchResult
+        attempts: 2
 
       - id: analyze
-        function: analyze
-        inputs:
-          task: "$.input.task"
-        depends_on: [gather]
+        after: [gather]
+        agent: claude
+        do: >
+          Synthesize the information gathered on ${input.description}. What was found:
+          ${gather.output.summary}. Identify patterns, contradictions, gaps and
+          insights. Organize findings into themes. Return a structured analysis
+          summary.
+        out: ResearchResult
+        attempts: 2
 
       - id: report
-        function: report
-        inputs:
-          task: "$.input.task"
-        depends_on: [analyze]
+        after: [analyze]
+        agent: claude
+        do: >
+          Produce a structured research report on ${input.description} with findings,
+          analysis and actionable recommendations, drawing on the analysis:
+          ${analyze.output.summary}. Write it to an appropriate file path.
+          Return the artifact path and summary.
+        out: ResearchResult
+        ensure:
+          - expr: "result.outcome == 'complete'"
+        attempts: 2

package/pipelines/review-fix.profiles.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "COMP-PIPELINE-QUARANTINE follow-up: compose-owned agent profiles for review-fix.stratum.yaml, applied at invocation by lib/build.js loadPipelineProfiles.",
+  "_reduceSteps": ["review"],
+  "_reduceSteps_comment": "LOAD-BEARING, not an optimization. `review` is the step whose ReviewResult the programmatic review_gate reads to decide clean vs dirty. Without this entry the gate never sees a result, so the corrective fixer never runs and the cross-model repair loop this pipeline exists for does not happen.",
+  "review": "codex:read-only-reviewer"
+}

package/pipelines/review-fix.stratum.yaml

@@ -3,107 +3,134 @@
 #   label: "Review & Fix"
 #   description: "Iterative review-fix loop — Codex reviews, Claude fixes until clean"
 #   category: quality
-#   steps: 2
+#   steps: 3
 #   estimated_minutes: 15
 
-version: "0.1"
+version: 1
 
 # review-fix pipeline
 #
-# Runs a task to completion via a two-phase loop:
-#   1. execute  — claude_run produces the initial implementation
-#   2. review   — codex_run reviews against the blueprint; on failure,
-#                 claude_run fixes findings before codex re-reviews
+# Runs a task to completion via a two-model loop:
+#   1. execute     — the implementer writes the initial implementation
+#   2. review      — the REVIEWER (a different model) reviews it
+#   3. review_gate — clean approves; dirty runs the corrective fixer as the
+#                    IMPLEMENTER and revises, so the reviewer re-reviews the
+#                    fixed code. The two roles never collapse into one model.
 #
-# The fix_and_review step is a single unit so findings always feed back
-# into a fix pass before re-review runs. retries: 10 is the iteration cap.
+# COMP-PIPELINE-QUARANTINE: re-authored from v0.1 to TS v1.
 #
-# Inputs:
-#   task      — what to implement (full task description with file paths, etc.)
-#   blueprint — the feature blueprint to review against (file content or path)
+# The first v1 draft of this file collapsed the whole loop into ONE `agent: codex`
+# step, which meant that on every retry Codex fixed the findings and then reviewed
+# its own repair. That silently destroyed the point of the pipeline — independent
+# cross-model repair — while the header still claimed it. Caught in review.
 #
-# Usage:
-#   stratum_plan <this yaml> "review_fix" {"task": "...", "blueprint": "..."}
+# The loop is now expressed the way the engine and compose actually implement it:
+#   - `review` is the reducer. It carries NO convergence `ensure`: re-running a
+#     reviewer against unchanged code cannot converge, so an ensure here would
+#     just burn attempts and fail (the same lesson as build.stratum.yaml note I1).
+#   - The decision is `review_gate`. Compose resolves that gate id
+#     PROGRAMMATICALLY (lib/build.js): a clean result approves, a dirty one runs
+#     the corrective fixer under `implementerAgent` — a DIFFERENT model from the
+#     reviewer — and then revises back to `review`.
+#   - `review-fix.profiles.json` declares `review` as a `_reduceSteps` entry,
+#     which is what routes its result into that gate decision. Without the
+#     sidecar the gate would never see the review result.
+#
+# Other conversion notes:
+#   - The two `functions:` collapse into inline steps; v1 has no function table.
+#   - `retries: 1` -> `attempts: 2` (v0.1 counted retries after the first try).
+#   - The old `retries: 10` iteration cap becomes the flow's `max_rounds`, which
+#     is where v1 bounds a gate-revise loop.
+#
+#
+# COMP-PIPELINE-QUARANTINE round 2: the flow input is the RUNNER's envelope, not
+# a bespoke `task`. runBuild derives plan inputs from the MODE, not from the spec
+# (lib/build.js startFresh), and feature mode always sends
+# {featureCode, description, implementer_agent, reviewer_agent} plus an optional
+# pre_merge_gate. Declaring `task` meant this spec resolved but could never plan —
+# making it reachable via `--template` without this change just moved the failure
+# from "not found" to a failed run. `${input.description}` carries what `task` did.
+# Inputs (the runner's feature envelope):
+#   featureCode  — the feature code; the blueprint is read from its folder
+#   description  — what to implement; this is what the old `task` input carried
 
 contracts:
   ExecuteResult:
-    summary:  {type: string}
-    findings: {type: array}
+    summary: string
+    findings: string[]
 
+  # CANONICAL ReviewResult — STRAT-CLAUDE-EFFORT-PARITY. It MUST carry meta,
+  # lenses_run, auto_fixes and asks even though this pipeline never sets them by
+  # hand: compose enables review normalization for any step whose out contract is
+  # NAMED ReviewResult (deriveOrdinaryReviewScaffold), and the normalizer always
+  # stamps those four fields. Engine contracts are strict, so a narrower
+  # declaration makes every review step fail with unrecognized_keys and exhaust
+  # its attempts — the same defect class as COMP-SHIP-CONTRACT. Caught in review.
   ReviewResult:
-    clean:    {type: boolean}
-    summary:  {type: string}
-    findings: {type: array}
-
-functions:
-  execute_task:
-    mode: compute
-    intent: >
-      Call the agent_run MCP tool with type "claude" and the given task prompt.
-      Implement the task fully — write all required files and make all required changes.
-      Return a summary of what was done and an empty findings array.
-      Do not review — only implement.
-    input:
-      task: {type: string}
-    output: ExecuteResult
-    retries: 1
-
-  fix_and_review:
-    mode: compute
-    intent: >
-      Implement one full fix-then-review cycle using the agent_run MCP tool.
-
-      Step A — Fix (skip on first attempt if no prior findings):
-        If this is a retry (previous ensure failed with findings), call agent_run
-        with type "claude". Pass the original task plus the previous findings.
-        Instruct Claude to fix every finding before proceeding.
-
-      Step B — Review:
-        Call agent_run with type "codex" and the following JSON Schema for structured output:
-          {
-            "type": "object",
-            "required": ["clean", "summary", "findings"],
-            "properties": {
-              "clean":    { "type": "boolean" },
-              "summary":  { "type": "string" },
-              "findings": { "type": "array", "items": { "type": "string" } }
-            }
-          }
-        The review prompt must include:
-          - the task description
-          - the execute_summary (what was implemented)
-          - the blueprint content
-          - instruction: "List actionable findings with confidence >= 7.
-            Set clean=true only if no actionable findings remain."
-        Pass the schema to agent_run so it returns structured JSON.
-
-      Return the parsed codex ReviewResult directly.
-      Never re-review without fixing first on a retry.
-    input:
-      task:            {type: string}
-      execute_summary: {type: string}
-      blueprint:       {type: string}
-    output: ReviewResult
-    ensure:
-      - "result.clean == true"
-    retries: 10
+    clean: boolean
+    summary: string
+    findings: array
+    meta: object
+    lenses_run: string[]
+    auto_fixes: array
+    asks: array
 
 flows:
+  entry: review_fix
   review_fix:
     input:
-      task:      {type: string}
-      blueprint: {type: string}
-    output: ReviewResult
+      featureCode: string
+      description: string
+      # REQUIRED, not optional: the review step interpolates reviewer_agent, and
+      # the corrective fixer runs as implementer_agent. Hard-coding the reviewer
+      # to codex looked safe until you notice `--implementer codex` is a supported
+      # override — then Codex fixes and reviews its own repair again, which is the
+      # exact defect this file was corrected for. Deriving both roles from the
+      # envelope keeps them whatever the invocation says, and always distinct.
+      implementer_agent: string
+      reviewer_agent: string
+      pre_merge_gate: string[]?
+    output:
+      from: "${review.output}"
+      contract: ReviewResult
+    # Bounds the review -> fix -> re-review loop; the v0.1 `retries: 10` cap.
+    max_rounds: 10
     steps:
       - id: execute
-        function: execute_task
-        inputs:
-          task: "$.input.task"
+        agent: "$.input.implementer_agent"
+        do: >
+          Implement this task fully — write all required files and make all
+          required changes: ${input.description}.
+          Return a summary of what was done and an empty findings array.
+          Do not review — only implement.
+        out: ExecuteResult
+        attempts: 2
 
       - id: review
-        function: fix_and_review
-        inputs:
-          task:            "$.input.task"
-          execute_summary: "$.steps.execute.output.summary"
-          blueprint:       "$.input.blueprint"
-        depends_on: [execute]
+        after: [execute]
+        agent: "$.input.reviewer_agent"
+        do: >
+          Review the implementation against the blueprint. Do NOT fix anything —
+          reviewing is your only job, and a corrective pass runs separately before
+          you are asked again.
+
+          Task: ${input.description}
+          What was implemented: ${execute.output.summary}
+          Blueprint: docs/features/${input.featureCode}/blueprint.md (fall back to design.md if absent)
+
+          List actionable findings with confidence >= 7. Each finding has file,
+          line, severity and a description. Set clean=true only if no actionable
+          findings remain.
+        out: ReviewResult
+        attempts: 3
+
+      # Resolved programmatically by compose, not by a human: clean approves and
+      # ends the flow; dirty runs the corrective fixer as the implementer, then
+      # revises so the reviewer sees the fixed code.
+      - id: review_gate
+        after: [review]
+        gate:
+          on_approve: null
+          on_revise: review
+          on_kill: null
+          max_rounds: 10

package/presets/team-feature.profiles.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "COMP-PIPELINE-QUARANTINE: compose-owned agent profiles for team-feature.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).",
+  "decompose": "claude:orchestrator",
+  "execute": "claude:implementer",
+  "verify": "claude:orchestrator"
+}