@smartmemory/compose 0.1.0

package/pipelines/build.stratum.yaml

@@ -0,0 +1,498 @@
+# metadata:
+#   id: build
+#   label: "Feature Build"
+#   description: "Execute a feature through the full Compose lifecycle — design, plan, implement, review, test, ship"
+#   category: development
+#   steps: 16
+#   estimated_minutes: 120
+
+version: "0.3"
+
+workflow:
+  name: build
+  description: "Execute a feature through the full Compose lifecycle"
+  input:
+    featureCode:
+      type: string
+      required: true
+    description:
+      type: string
+      required: true
+
+contracts:
+  PhaseResult:
+    phase:    {type: string}
+    artifact: {type: string}
+    outcome:  {type: string, values: [complete, skipped, failed]}
+    summary:  {type: string}
+
+  ReviewResult:
+    clean:    {type: boolean}
+    summary:  {type: string}
+    findings: {type: array}
+
+  TestResult:
+    passing:  {type: boolean}
+    summary:  {type: string}
+    failures: {type: array}
+
+  TaskGraph:
+    tasks: {type: array}
+
+  LensFinding:
+    lens:       {type: string}
+    file:       {type: string}
+    line:       {type: number}
+    severity:   {type: string, values: [must-fix, should-fix, nit]}
+    finding:    {type: string}
+    confidence: {type: number}
+
+  LensTask:
+    id:              {type: string}
+    lens_name:       {type: string}
+    lens_focus:      {type: string}
+    confidence_gate: {type: number}
+    exclusions:      {type: string}
+
+  TriageResult:
+    tasks:    {type: array}
+
+  LensResult:
+    clean:    {type: boolean}
+    findings: {type: array, items: LensFinding}
+
+  MergedReviewResult:
+    clean:      {type: boolean}
+    summary:    {type: string}
+    findings:   {type: array, items: LensFinding}
+    lenses_run: {type: array}
+    auto_fixes: {type: array, items: LensFinding}
+    asks:       {type: array, items: LensFinding}
+
+functions:
+  design_gate:
+    mode: gate
+    timeout: 3600
+
+  plan_gate:
+    mode: gate
+    timeout: 3600
+
+  ship_gate:
+    mode: gate
+    timeout: 1800
+
+flows:
+  # --- Sub-flow: review ---
+  # Single-step: codex reviews, stratum retries via ensure_failed.
+  # Cross-agent fix (claude) is dispatched by build.js when ensure_failed
+  # fires with a recovery_agent configured on the parent flow step.
+  review_check:
+    input:
+      task:      {type: string}
+      blueprint: {type: string}
+    output: ReviewResult
+    steps:
+      - id: review
+        agent: codex
+        intent: >
+          Review the implementation against the blueprint. Return structured JSON:
+          { "clean": boolean, "summary": string, "findings": string[] }.
+          Set clean=true only if no actionable findings with confidence >= 80 remain.
+        inputs:
+          task: "$.input.task"
+          blueprint: "$.input.blueprint"
+        output_contract: ReviewResult
+        ensure:
+          - "result.clean == True"
+        retries: 5
+
+  # --- Sub-flow: parallel_review ---
+  # Multi-lens review: triage selects lenses, parallel dispatch runs them,
+  # merge deduplicates and classifies findings. Falls back to review_check
+  # if parallel dispatch is unavailable.
+  parallel_review:
+    input:
+      task:               {type: string}
+      blueprint:          {type: string}
+      diff:               {type: string}
+      prior_dirty_lenses: {type: array, optional: true}
+    output: MergedReviewResult
+    steps:
+      - id: triage
+        agent: "claude:orchestrator"
+        intent: >
+          Decide which review lenses to activate.
+
+          RETRY PATH — If the file .compose/prior_dirty_lenses.json exists, read it.
+          It contains a JSON array of lens IDs that had actionable findings in the prior
+          review run. In this case:
+            - Activate all lenses listed in that array.
+            - Always also include diff-quality and contract-compliance (baseline lenses —
+              they re-run on every retry to catch regressions introduced by the fix, even
+              if they passed clean last time).
+            - Skip all other lenses — they already passed clean.
+
+          FIRST RUN PATH — If .compose/prior_dirty_lenses.json does not exist:
+            - Always include diff-quality and contract-compliance.
+            - Add security if files touch auth, crypto, SQL, HTTP handlers.
+            - Add framework if detected framework files (React, Express, Next.js, etc).
+
+          Return JSON: { "tasks": LensTask[] } where each task has id, lens_name,
+          lens_focus, confidence_gate, exclusions.
+        inputs:
+          diff: "$.input.diff"
+        output_contract: TriageResult
+
+      - id: review_lenses
+        type: parallel_dispatch
+        agent: "claude:read-only-reviewer"
+        source: "$.steps.triage.output.tasks"
+        max_concurrent: 4
+        isolation: none
+        intent_template: >
+          You are a {lens_name} reviewer. Review ONLY through the {lens_name} lens.
+          Focus: {lens_focus}
+          Confidence gate: only report findings with confidence >= {confidence_gate}.
+          False-positive exclusions: {exclusions}
+          Return JSON: { "clean": boolean, "findings": LensFinding[] }
+          where each finding has: lens, file, line, severity (must-fix|should-fix|nit),
+          finding (description), confidence (1-10).
+        require: all
+
+      - id: merge
+        agent: "claude:orchestrator"
+        intent: >
+          Merge findings from all review lenses. The input contains the parallel
+          dispatch aggregate with tasks[].result for each lens.
+          1. Collect all findings arrays from completed task results.
+          2. Deduplicate: same file + same issue = one finding, keep highest confidence.
+          3. Assign severity: must-fix (blocks ship), should-fix (next iteration), nit (logged).
+          4. Classify: auto_fixes (mechanical: formatting, simple tests, obvious typos)
+             vs asks (requires judgment).
+          5. lenses_run = IDs of lenses that produced must-fix or should-fix findings.
+          Return JSON: MergedReviewResult with clean, summary, findings, lenses_run,
+          auto_fixes, asks. Set clean=true only if zero must-fix and zero should-fix findings.
+        inputs:
+          results: "$.steps.review_lenses.output"
+          task: "$.input.task"
+          blueprint: "$.input.blueprint"
+        output_contract: MergedReviewResult
+        depends_on: [review_lenses]
+
+  # --- Sub-flow: coverage ---
+  # Single-step: claude runs tests, stratum retries via ensure_failed.
+  # Cross-agent fix is dispatched by build.js on ensure_failed.
+  coverage_check:
+    input:
+      task: {type: string}
+      plan: {type: string}
+    output: TestResult
+    steps:
+      - id: run_tests
+        agent: "claude::fast"
+        intent: >
+          Run the project test suite. Return structured JSON:
+          { "passing": boolean, "summary": string, "failures": string[] }.
+        inputs:
+          task: "$.input.task"
+        output_contract: TestResult
+        ensure:
+          - "result.passing == True"
+        retries: 15
+
+  # --- Main flow: compose feature lifecycle ---
+  build:
+    input:
+      featureCode: {type: string}
+      description: {type: string}
+    output: PhaseResult
+    max_rounds: 10
+    steps:
+      # Phase: Explore & Design
+      - id: explore_design
+        agent: claude
+        intent: >
+          Explore the codebase and write a design doc for this feature.
+          Launch 2-3 explorer subagents in parallel to map architecture,
+          find similar features, and analyze related implementations.
+          Write the design to docs/features/{featureCode}/design.md.
+          Return the artifact path in the "artifact" field.
+        inputs:
+          featureCode: "$.input.featureCode"
+          description: "$.input.description"
+        output_contract: PhaseResult
+        ensure:
+          - "result.outcome == 'complete'"
+          - "file_exists(result.artifact)"
+        retries: 2
+
+      # Gate: Design review
+      - id: design_gate
+        function: design_gate
+        on_approve: prd
+        on_revise: explore_design
+        on_kill: null
+        depends_on: [explore_design]
+
+      # Phase: PRD (skippable)
+      - id: prd
+        agent: claude
+        intent: >
+          Write a product requirements document for this feature.
+          Write to docs/features/{featureCode}/prd.md.
+          Return the artifact path in the "artifact" field.
+        inputs:
+          featureCode: "$.input.featureCode"
+          description: "$.input.description"
+        output_contract: PhaseResult
+        ensure:
+          - "result.outcome == 'complete'"
+          - "file_exists(result.artifact)"
+        retries: 2
+        skip_if: "true"
+        skip_reason: "PRD skipped by default — set skip_if to false to enable"
+        depends_on: [design_gate]
+
+      # Phase: Architecture (skippable)
+      - id: architecture
+        agent: claude
+        intent: >
+          Write an architecture doc with competing proposals.
+          Write to docs/features/{featureCode}/architecture.md.
+          Return the artifact path in the "artifact" field.
+        inputs:
+          featureCode: "$.input.featureCode"
+          description: "$.input.description"
+        output_contract: PhaseResult
+        ensure:
+          - "result.outcome == 'complete'"
+          - "file_exists(result.artifact)"
+        retries: 2
+        skip_if: "true"
+        skip_reason: "Architecture skipped by default — set skip_if to false to enable"
+        depends_on: [prd]
+
+      # Phase: Blueprint
+      - id: blueprint
+        agent: "claude::critical"
+        intent: >
+          Write an implementation blueprint with file:line references to existing code.
+          Ground every reference in actual files. Write to docs/features/{featureCode}/blueprint.md.
+          Return the artifact path in the "artifact" field.
+        inputs:
+          featureCode: "$.input.featureCode"
+          description: "$.input.description"
+        output_contract: PhaseResult
+        ensure:
+          - "result.outcome == 'complete'"
+          - "file_exists(result.artifact)"
+        retries: 3
+        depends_on: [architecture]
+
+      # Phase: Blueprint Verification
+      - id: verification
+        agent: claude
+        intent: >
+          Verify every file:line reference in the blueprint against the actual codebase.
+          Flag stale or incorrect references. Return { verified: true } only if all
+          references are valid. Return { verified: false, staleRefs: [...] } otherwise.
+        inputs:
+          featureCode: "$.input.featureCode"
+          description: "$.input.description"
+        output_contract: PhaseResult
+        ensure:
+          - "result.outcome == 'complete'"
+        retries: 2
+        on_fail: blueprint
+        depends_on: [blueprint]
+
+      # Phase: Implementation Plan
+      - id: plan
+        agent: claude
+        intent: >
+          Write an ordered implementation plan with tasks, dependencies, file paths (new/existing),
+          and acceptance criteria. Write to docs/features/{featureCode}/plan.md.
+          Return the artifact path in the "artifact" field.
+        inputs:
+          featureCode: "$.input.featureCode"
+          description: "$.input.description"
+        output_contract: PhaseResult
+        ensure:
+          - "result.outcome == 'complete'"
+          - "file_exists(result.artifact)"
+        retries: 2
+        depends_on: [verification]
+
+      # Gate: Plan review
+      - id: plan_gate
+        function: plan_gate
+        on_approve: decompose
+        on_revise: plan
+        on_kill: null
+        depends_on: [plan]
+
+      # Phase: Decompose — analyze the plan and emit a task graph
+      - id: decompose
+        type: decompose
+        agent: claude
+        intent: >
+          Read the implementation plan and decompose it into independent tasks.
+          For each task, identify files_owned (exclusive write), files_read (read-only),
+          and depends_on (tasks that must complete first).
+          Return a TaskGraph with the task array.
+        output_contract: TaskGraph
+        ensure:
+          - "no_file_conflicts(result.tasks)"
+          - "len(result.tasks) >= 1"
+        retries: 2
+        depends_on: [plan_gate]
+
+      # Phase: Execute — parallel dispatch of decomposed tasks
+      - id: execute
+        type: parallel_dispatch
+        source: "$.steps.decompose.output.tasks"
+        agent: claude
+        max_concurrent: 3
+        isolation: worktree
+        capture_diff: true
+        defer_advance: true
+        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}
+
+          Feature: {task.id}
+        depends_on: [decompose]
+
+      # Sub-flow: Review (parallel multi-lens review; falls back to review_check)
+      # Parent-step ensure drives the fix loop: ensure_failed -> build.js fix ->
+      # retry the whole parallel_review sub-flow, which re-runs fresh triage/lenses/merge.
+      - id: review
+        flow: parallel_review
+        inputs:
+          task: "$.steps.execute.output.outcome"
+          blueprint: "$.steps.blueprint.output.artifact"
+          diff: "$.steps.execute.output.tasks"
+        ensure:
+          - "result.clean == True"
+        depends_on: [execute]
+
+      # Sub-flow: Codex review (independent cross-model pass after Claude lenses + fixes)
+      - id: codex_review
+        flow: review_check
+        inputs:
+          task: "$.steps.execute.output.outcome"
+          blueprint: "$.steps.blueprint.output.artifact"
+        ensure:
+          - "result.clean == True"
+        depends_on: [review]
+
+      # Sub-flow: Coverage (claude runs tests; build.js dispatches fix on ensure_failed)
+      - id: coverage
+        flow: coverage_check
+        inputs:
+          task: "$.steps.execute.output.outcome"
+          plan: "$.input.description"
+        ensure:
+          - "result.passing == True"
+        depends_on: [codex_review]
+
+      # Phase: Report (skippable)
+      - id: report
+        agent: claude
+        intent: >
+          Write a post-implementation report documenting what was built,
+          deviations from the plan, and lessons learned.
+          Write to docs/features/{featureCode}/report.md.
+          Return the artifact path in the "artifact" field.
+        inputs:
+          featureCode: "$.input.featureCode"
+          description: "$.input.description"
+        output_contract: PhaseResult
+        ensure:
+          - "result.outcome == 'complete'"
+          - "file_exists(result.artifact)"
+        retries: 2
+        skip_if: "true"
+        skip_reason: "Report skipped by default — set skip_if to false to enable"
+        depends_on: [coverage]
+
+      # Phase: Update Docs
+      - id: docs
+        agent: claude
+        intent: >
+          Update project documentation for this feature. You MUST:
+
+          1. CHANGELOG.md — Add an entry under today's date with the feature code
+             and a bullet list of what was built. Read the existing format first.
+          2. ROADMAP.md — Find this feature's row and change its status to COMPLETE.
+             If this completes a parent feature, update the parent header too.
+          3. README.md — Update ONLY if the feature changes user-facing setup,
+             commands, or capabilities. Skip if purely internal.
+          4. CLAUDE.md — Update ONLY if new conventions, commands, or architecture
+             patterns were introduced. Skip if no changes.
+          5. Public docs — If the feature introduces or changes any of these, update
+             the relevant file in docs/:
+               - New CLI commands or flags → docs/compose-one-pager.md
+               - New connector or agent type → docs/connectors.md
+               - New workflow or lifecycle change → docs/use-cases.md
+               - API or config changes → docs/PRODUCT-SPEC.md
+             Read each file before editing. Skip if the feature is purely internal
+             with no user-facing changes.
+
+          Read each file before editing. Do not skip CHANGELOG and ROADMAP —
+          they are always required. Commit nothing — the ship step handles commits.
+        inputs:
+          featureCode: "$.input.featureCode"
+          description: "$.input.description"
+        output_contract: PhaseResult
+        retries: 2
+        depends_on: [report]
+
+      # Phase: Ship
+      - id: ship
+        agent: "claude::critical"
+        intent: >
+          Final verification and commit. You MUST:
+
+          1. Run the test suite (npm test or node --test test/*.test.js).
+             If tests fail, fix them before proceeding.
+          2. Run the build (npx vite build). Must pass.
+          3. Check git status — verify CHANGELOG.md and ROADMAP.md were updated
+             by the docs step. If they weren't, update them now.
+          4. Stage all changed files for this feature (git add — be explicit,
+             never stage worktrees, pycache, or node_modules).
+          5. Commit with message: "feat(<featureCode>): <one-line summary>"
+          6. Push to remote.
+          7. Read docs/features/{featureCode}/plan.md and extract acceptance criteria
+             as plan_items: an array of objects { text, file, critical } where:
+             - text is the checkbox item text
+             - file is the backtick-quoted file path in the item (null if none)
+             - critical is true if the item mentions MUST, required, security, or tests
+             Use lib/plan-parser.js (parsePlanItems) to do this extraction.
+          8. Collect the list of files you staged as files_changed.
+
+          Include plan_items and files_changed in your result JSON.
+          Report the commit hash and files changed.
+        inputs:
+          featureCode: "$.input.featureCode"
+          description: "$.input.description"
+        output_contract: PhaseResult
+        ensure:
+          - "plan_completion(result.plan_items, result.files_changed)"
+        retries: 2
+        depends_on: [docs]
+
+      # Gate: Ship review
+      - id: ship_gate
+        function: ship_gate
+        on_approve: null
+        on_revise: ship
+        on_kill: null
+        depends_on: [ship]

package/pipelines/content.stratum.yaml

@@ -0,0 +1,112 @@
+# metadata:
+#   id: content
+#   label: "Content"
+#   description: "Write documentation or content — research, draft, review, publish"
+#   category: documentation
+#   steps: 4
+#   estimated_minutes: 20
+
+version: "0.1"
+
+# content pipeline
+#
+# Four-step flow for documentation and content creation:
+#   1. research  — gather context, read existing docs, identify gaps
+#   2. draft     — write the content
+#   3. review    — review for accuracy, completeness, and clarity
+#   4. publish   — finalize and commit
+#
+# Inputs:
+#   task — what to write (doc type, topic, target audience)
+#
+# Usage:
+#   stratum_plan <this yaml> "content" {"task": "..."}
+
+contracts:
+  ContentResult:
+    phase:    {type: string}
+    artifact: {type: string}
+    summary:  {type: string}
+    outcome:  {type: string, values: [complete, failed]}
+
+  ReviewResult:
+    clean:    {type: boolean}
+    summary:  {type: string}
+    findings: {type: array}
+
+functions:
+  research:
+    mode: compute
+    intent: >
+      Gather context for the content. Read existing documentation, related
+      code, and prior art. Identify gaps and outline key topics to cover.
+      Return a summary of research findings.
+    input:
+      task: {type: string}
+    output: ContentResult
+    retries: 1
+
+  draft:
+    mode: compute
+    intent: >
+      Write the content based on research findings. Follow existing
+      documentation conventions and standards. Write to the appropriate
+      file path. Return the artifact path.
+    input:
+      task: {type: string}
+    output: ContentResult
+    ensure:
+      - "result.outcome == 'complete'"
+    retries: 2
+
+  review:
+    mode: compute
+    intent: >
+      Review the drafted content for accuracy, completeness, and clarity.
+      Check that all claims are supported by code or documentation.
+      Return { "clean": boolean, "summary": string, "findings": string[] }.
+    input:
+      task: {type: string}
+    output: ReviewResult
+    ensure:
+      - "result.clean == true"
+    retries: 3
+
+  publish:
+    mode: compute
+    intent: >
+      Finalize the content. Update any cross-references (README, CHANGELOG,
+      index files). Commit with a descriptive message.
+    input:
+      task: {type: string}
+    output: ContentResult
+    retries: 1
+
+flows:
+  content:
+    input:
+      task: {type: string}
+    output: ContentResult
+    steps:
+      - id: research
+        function: research
+        inputs:
+          task: "$.input.task"
+
+      - id: draft
+        function: draft
+        inputs:
+          task: "$.input.task"
+        depends_on: [research]
+
+      - id: review
+        function: review
+        inputs:
+          task: "$.input.task"
+        depends_on: [draft]
+
+      - id: publish
+        function: publish
+        inputs:
+          task: "$.input.task"
+        depends_on: [review]

package/pipelines/coverage-sweep.stratum.yaml

@@ -0,0 +1,52 @@
+# metadata:
+#   id: coverage-sweep
+#   label: "Coverage Sweep"
+#   description: "Run test suite in a loop until all tests pass"
+#   category: quality
+#   steps: 1
+#   estimated_minutes: 10
+
+version: "0.1"
+
+# coverage-sweep pipeline
+#
+# Runs the test suite in a loop until all tests pass.
+# Same pattern as review-fix.stratum.yaml but for test coverage.
+#
+# Inputs:
+#   task — what to test (feature description, file paths, etc.)
+#
+# Usage:
+#   stratum_plan <this yaml> "coverage_sweep" {"task": "..."}
+
+contracts:
+  CoverageResult:
+    passing:  {type: boolean}
+    summary:  {type: string}
+    failures: {type: array}
+
+functions:
+  run_coverage:
+    mode: compute
+    intent: >
+      Run the project test suite. Return structured JSON:
+      { "passing": boolean, "summary": string, "failures": string[] }.
+      Set passing=true only if all tests pass with no failures.
+      If tests fail, list each failing test name in the failures array.
+    input:
+      task: {type: string}
+    output: CoverageResult
+    ensure:
+      - "result.passing == true"
+    retries: 15
+
+flows:
+  coverage_sweep:
+    input:
+      task: {type: string}
+    output: CoverageResult
+    steps:
+      - id: sweep
+        function: run_coverage
+        inputs:
+          task: "$.input.task"