@loomfsm/bundle-code 0.1.0

package/schemas/finding.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "finding.schema.json",
+  "title": "Finding",
+  "description": "A single issue surfaced by a reviewer or validator. Designed for clustering, metrics, and self-learning.",
+  "type": "object",
+  "required": ["schema_version", "id", "agent", "severity", "category", "summary"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0",
+      "description": "Schema version. Bump on breaking field changes; orchestrator switches by version."
+    },
+    "id": {
+      "type": "string",
+      "description": "Stable id: f-<YYYY-MM-DD>-<random6>",
+      "pattern": "^f-\\d{4}-\\d{2}-\\d{2}-[a-z0-9]{6}$"
+    },
+    "agent": {
+      "type": "string",
+      "enum": [
+        "logic-reviewer",
+        "challenger-reviewer",
+        "style-reviewer",
+        "security",
+        "performance",
+        "acceptance",
+        "plan-conformance",
+        "plan-grounding-check",
+        "context-doc-verifier",
+        "ui-consistency",
+        "api-contract",
+        "playwright",
+        "test",
+        "implementer"
+      ]
+    },
+    "iteration": { "type": "integer", "minimum": 1 },
+    "task_id": {
+      "type": "string",
+      "description": "Links to pipeline-state.json task_id"
+    },
+    "file": {
+      "type": ["string", "null"],
+      "description": "Path relative to repo root, or null when finding is not file-bound (e.g. plan-level issue)"
+    },
+    "line_start": { "type": ["integer", "null"], "minimum": 1 },
+    "line_end": { "type": ["integer", "null"], "minimum": 1 },
+    "severity": {
+      "type": "string",
+      "enum": ["blocking", "warn", "info"]
+    },
+    "category": {
+      "type": "string",
+      "description": "Controlled vocab — must match an entry in templates/schemas/category-vocab.json for the finding's agent. If a new pattern is being recorded, use 'other' and populate proposed_new_category."
+    },
+    "proposed_new_category": {
+      "type": ["string", "null"],
+      "description": "When category='other', describe the proposed new vocab entry. Reviewed via /agent-feedback before being added to vocab.",
+      "maxLength": 60
+    },
+    "pattern_id": {
+      "type": ["string", "null"],
+      "description": "When this finding matches a known past-miss pattern: <agent>:<category>:<short-slug>. null if novel."
+    },
+    "summary": {
+      "type": "string",
+      "description": "One-line description of the issue. <=200 chars.",
+      "maxLength": 200
+    },
+    "evidence_excerpt": {
+      "type": ["string", "null"],
+      "description": "Short code excerpt anchoring the finding. Trim to <=400 chars.",
+      "maxLength": 400
+    },
+    "suggested_fix": {
+      "type": ["string", "null"],
+      "description": "Concrete proposed fix or pointer to an approach. <=300 chars.",
+      "maxLength": 300
+    },
+    "status": {
+      "type": "string",
+      "enum": ["open", "fixed", "accepted_by_human", "dismissed"],
+      "default": "open"
+    },
+    "ref_rule_id": {
+      "type": ["string", "null"],
+      "description": "When the finding cites a senior-pattern reference rule (e.g. 'redis.md#hot-keys'), include the anchor for traceability."
+    }
+  }
+}

package/schemas/pipeline-state.schema.json

@@ -0,0 +1,238 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "pipeline-state.schema.json",
+  "title": "Pipeline State",
+  "description": "Single source of truth for an in-flight task. Orchestrator updates after every agent completion. /done parses mechanically — no LLM needed.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "bundle",
+    "task_id",
+    "task",
+    "complexity",
+    "started_at",
+    "phases",
+    "gates",
+    "agents_count"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.1" },
+    "bundle": {
+      "type": "string",
+      "description": "Which bundle this state belongs to. Selects the matching bundle-extension schema in templates/schemas/bundle-extensions/<bundle>.schema.json."
+    },
+    "task_id": {
+      "type": "string",
+      "pattern": "^t-\\d{4}-\\d{2}-\\d{2}-[a-z0-9]{4,}(?:-[a-f0-9]{4})?$",
+      "description": "t-<YYYY-MM-DD>-<short-slug>"
+    },
+    "task": { "type": "string" },
+    "complexity": { "type": "string", "enum": ["simple", "medium", "complex"] },
+    "tests_mode": { "type": "string", "enum": ["tdd", "regression-only"] },
+    "stack": {
+      "type": "object",
+      "required": ["language"],
+      "properties": {
+        "language": { "type": "string" },
+        "package_manager": { "type": ["string", "null"] },
+        "test_command": { "type": ["string", "null"] },
+        "lint_command": { "type": ["string", "null"] },
+        "build_command": { "type": ["string", "null"] },
+        "project_type": { "type": ["string", "null"], "enum": [null, "frontend-app", "backend", "library", "monorepo"] }
+      },
+      "additionalProperties": true
+    },
+    "started_at": { "type": "string", "format": "date-time" },
+    "ended_at": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "Item 11: set by pipeline_finish so the metrics row + post-hoc analysis can compute wall-clock duration."
+    },
+    "refs_loaded": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Senior-pattern reference paths resolved at STEP 1 (rule #24)."
+    },
+    "refs_dropped_due_to_cap": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "team_knowledge_refs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Project-scoped shared knowledge files injected into every agent prompt (item 7 of v2.2.5). Populated by pipeline_init from <project>/.claude/pipeline.config.json.team_knowledge_refs[]."
+    },
+    "phases": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "context": { "$ref": "#/$defs/phase_status" },
+        "planning": {
+          "allOf": [
+            { "$ref": "#/$defs/phase_status" },
+            {
+              "type": "object",
+              "properties": {
+                "gate1_revisions": { "type": "integer", "minimum": 0 },
+                "grounding_mismatches": { "type": "integer", "minimum": 0 }
+              }
+            }
+          ]
+        },
+        "test_first": {
+          "allOf": [
+            { "$ref": "#/$defs/phase_status" },
+            {
+              "type": "object",
+              "properties": {
+                "skipped_reason": {
+                  "type": ["string", "null"],
+                  "enum": [null, "regression-only", "no-test-framework-tdd-blocked", "user-override-no-tests"]
+                },
+                "test_spec_count_in_plan": { "type": ["integer", "null"], "minimum": 0 },
+                "tests_written_count": { "type": ["integer", "null"], "minimum": 0 },
+                "test_files_written": { "type": "array", "items": { "type": "string" } },
+                "test_files_hashes_post_red": {
+                  "type": "object",
+                  "description": "Map of test_file_path → sha256 hash, captured immediately after RED. Used by plan-conformance to detect implementer modification.",
+                  "additionalProperties": { "type": "string" }
+                }
+              }
+            }
+          ]
+        },
+        "implementation": {
+          "allOf": [
+            { "$ref": "#/$defs/phase_status" },
+            {
+              "type": "object",
+              "properties": {
+                "antipattern_candidates_count": { "type": "integer", "minimum": 0 },
+                "caller_context_sites_count": { "type": "integer", "minimum": 0 },
+                "gate2_revisions": { "type": "integer", "minimum": 0 },
+                "logic_vs_challenger_disagreement": { "type": "boolean", "default": false },
+                "plan_conformance": {
+                  "type": ["string", "null"],
+                  "enum": [null, "CONFORMS", "DRIFT", "PARTIAL"]
+                },
+                "drift_files_count": { "type": "integer", "minimum": 0 },
+                "test_files_modified_by_implementer": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Files in test_files_written whose post-GREEN hash differs from test_files_hashes_post_red. MUST be empty unless human approved at a gate. Non-empty → blocking."
+                },
+                "checkpoint_results": {
+                  "type": "array",
+                  "description": "Mechanical checkpoint runs by Implementer; failing-count must be monotonically non-increasing.",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "step": { "type": "integer" },
+                      "failing_before": { "type": "integer" },
+                      "failing_after": { "type": "integer" },
+                      "test_files_hashed_match": { "type": "boolean" }
+                    }
+                  }
+                }
+              }
+            }
+          ]
+        },
+        "validation": { "$ref": "#/$defs/phase_status" },
+        "final": { "$ref": "#/$defs/phase_status" }
+      }
+    },
+    "reviewer_verdicts": {
+      "type": "array",
+      "description": "Append-only per agent run. One entry per spawn.",
+      "items": {
+        "type": "object",
+        "required": ["agent", "iteration", "verdict"],
+        "properties": {
+          "agent": { "type": "string" },
+          "phase": {
+            "type": "string",
+            "description": "Pipeline phase this verdict came from. String-typed at the schema layer — runtime validates against the active flow's declared phases[]. Lets the same agent appear in multiple phases without verdicts collapsing into an indistinguishable bag."
+          },
+          "iteration": { "type": "integer", "minimum": 1 },
+          "verdict": { "type": "string" },
+          "blocking_issues": { "type": "integer", "minimum": 0 },
+          "non_blocking": { "type": "integer", "minimum": 0 },
+          "past_misses_applied": { "type": "integer", "minimum": 0 },
+          "past_miss_matches": { "type": "integer", "minimum": 0 },
+          "categories_seen": { "type": "array", "items": { "type": "string" } }
+        },
+        "additionalProperties": false
+      }
+    },
+    "findings_path": {
+      "type": "string",
+      "description": "Pointer to .claude/findings.jsonl — append-only stream of all findings emitted across the run.",
+      "default": ".claude/findings.jsonl"
+    },
+    "files": {
+      "type": "object",
+      "properties": {
+        "created": { "type": "array", "items": { "type": "string" } },
+        "modified": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "gates": {
+      "type": "object",
+      "properties": {
+        "gate0": { "type": "string", "enum": ["pending", "approved", "rejected", "skipped"], "default": "pending" },
+        "gate1": { "type": "string", "enum": ["pending", "approved", "rejected", "skipped"], "default": "pending" },
+        "gate2": { "type": "string", "enum": ["pending", "approved", "rejected", "skipped"], "default": "pending" },
+        "gate1_feedback": { "type": ["string", "null"] },
+        "gate2_feedback": { "type": ["string", "null"] }
+      }
+    },
+    "agents_count": { "type": "integer", "minimum": 0 },
+    "tests_written": {
+      "type": ["integer", "string", "null"],
+      "description": "Count of new test cases, 0, 'skip', or null if not yet known"
+    },
+    "blockers_found": { "type": "integer", "minimum": 0 },
+    "verdict": {
+      "type": ["string", "null"],
+      "enum": [null, "accepted", "rejected"]
+    },
+    "pipeline_violation": {
+      "type": ["string", "null"],
+      "description": "Set when pipeline integrity was breached (e.g. missing-state-file recovery)."
+    },
+    "owner_id": {
+      "type": ["string", "null"],
+      "description": "Opaque, platform-agnostic identifier of the entity that started this task. Populated at task start from the first non-empty owner/session env var the host transport supplies. Finalization paths compare against this to refuse cross-session completion. Transports (HTTP API, CLI, other providers) set their own owner_id via env vars; the substrate stays transport-agnostic."
+    }
+  },
+  "$defs": {
+    "phase_status": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": { "type": "string", "enum": ["pending", "in_progress", "completed", "skipped"] },
+        "started_at": { "type": ["string", "null"], "format": "date-time" },
+        "completed_at": { "type": ["string", "null"], "format": "date-time" },
+        "agents": { "type": "array", "items": { "type": "string" } },
+        "open_spawns": {
+          "type": "array",
+          "description": "Spawns that have been begun (via pipeline_begin_agent) but not yet recorded. Must be empty before the phase can transition to 'completed' (INV_012).",
+          "items": {
+            "type": "object",
+            "required": ["id", "agent", "started_at"],
+            "properties": {
+              "id": { "type": "string", "pattern": "^ar-[0-9a-f-]+$" },
+              "agent": { "type": "string" },
+              "model": { "type": ["string", "null"] },
+              "started_at": { "type": "string", "format": "date-time" }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/reviewer-output.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "reviewer-output.schema.json",
+  "title": "Reviewer Output Header",
+  "description": "JSON block emitted at the top of every reviewer/validator agent output. Markdown narrative follows below the block; this header is the machine-parseable surface.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "agent",
+    "task_id",
+    "iteration",
+    "verdict",
+    "findings",
+    "summary_line"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.0" },
+    "agent": {
+      "type": "string",
+      "enum": [
+        "logic-reviewer",
+        "challenger-reviewer",
+        "style-reviewer",
+        "security",
+        "performance"
+      ]
+    },
+    "task_id": { "type": "string" },
+    "iteration": { "type": "integer", "minimum": 1 },
+    "verdict": {
+      "type": "string",
+      "enum": ["APPROVE", "REQUEST_CHANGES", "WARN"],
+      "description": "REQUEST_CHANGES iff at least one finding has severity=blocking. WARN allowed only for security/performance."
+    },
+    "summary_line": {
+      "type": "string",
+      "maxLength": 150,
+      "description": "Human-readable one-liner. Shown in pipeline-state and dashboards. The 150-char cap accommodates legitimate single-line summaries on complex tasks that exceed 100."
+    },
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "finding.schema.json" },
+      "description": "All issues found, blocking AND non-blocking. Drives metrics, clustering, past-miss promotion."
+    },
+    "past_misses_applied": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Count of past-miss patterns the reviewer was given to check against this run."
+    },
+    "past_miss_matches": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "pattern_ids of past-misses that matched this diff (subset of past_misses_applied)."
+    },
+    "ref_rules_consulted": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Senior-pattern reference anchors that contributed to findings (e.g. 'redis.md#hot-keys')."
+    }
+  }
+}

package/schemas/state-extension.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "state-extension.schema.json",
+  "title": "Code bundle — bundle_state extension",
+  "description": "Shape of the bundle_state JSON column for the code bundle. Every field is optional and populated as the flow progresses; the column is null before the first write.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "diff_snapshot": {
+      "type": "object",
+      "description": "Snapshot of the substrate's file accounting at the pre-review step. Reviewers read this for a stable, replayable picture of the change surface.",
+      "properties": {
+        "files_modified": { "type": "array", "items": { "type": "string" } },
+        "files_created": { "type": "array", "items": { "type": "string" } },
+        "modified_count": { "type": "integer", "minimum": 0 },
+        "created_count": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "test_files_modified_by_implementer": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Test/spec files the implementation run modified. Non-empty means the final gate must be human-approved (sacred-tests invariant)."
+    },
+    "test_files_written": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Test files authored during a test-first flow."
+    },
+    "lint_result": {
+      "$ref": "#/$defs/checkResult",
+      "description": "Deterministic lint result. Read by the safety floor when the final role's policy is auto; the writer is a deterministic lint shell-out the deployment supplies."
+    },
+    "test_run": {
+      "$ref": "#/$defs/checkResult",
+      "description": "Deterministic test-run result. Read by the safety floor under an auto final policy."
+    },
+    "typecheck": {
+      "$ref": "#/$defs/checkResult",
+      "description": "Deterministic typecheck result. Read by the safety floor under an auto final policy."
+    }
+  },
+  "$defs": {
+    "checkResult": {
+      "type": "object",
+      "properties": {
+        "status": { "type": "string", "enum": ["ok", "failed", "skipped"] },
+        "summary": { "type": "string" }
+      },
+      "required": ["status"],
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/validator-output.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "validator-output.schema.json",
+  "title": "Validator Output Header",
+  "description": "JSON block for validator agents (Acceptance, Plan Conformance, Plan Grounding Check, Context-Doc Verifier). Verdict vocabulary differs from reviewers; agent-specific extensions live in 'details'.",
+  "type": "object",
+  "required": ["schema_version", "agent", "task_id", "verdict", "summary_line"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "type": "string", "const": "1.0" },
+    "agent": {
+      "type": "string",
+      "enum": [
+        "acceptance",
+        "plan-conformance",
+        "plan-grounding-check",
+        "context-doc-verifier",
+        "ui-consistency",
+        "api-contract",
+        "playwright",
+        "test"
+      ]
+    },
+    "task_id": { "type": "string" },
+    "iteration": { "type": "integer", "minimum": 1 },
+    "verdict": {
+      "type": "string",
+      "enum": [
+        "PASS", "FAIL", "PASS_WITH_WARNINGS",
+        "CONFORMS", "DRIFT", "PARTIAL",
+        "GROUNDED", "NEEDS_REVISION", "NO_CITATIONS",
+        "VERIFIED", "NEEDS_RERUN", "WARN",
+        "APPROVE", "REQUEST_CHANGES",
+        "RED", "ERROR"
+      ]
+    },
+    "summary_line": { "type": "string", "maxLength": 150 },
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "finding.schema.json" }
+    },
+    "details": {
+      "type": "object",
+      "description": "Agent-specific structured details. Examples: plan-conformance → drift_files/unfinished_steps/ac_coverage; grounding-check → mismatches; verifier → claim_check_count.",
+      "additionalProperties": true
+    }
+  }
+}