forgedock 1.1.1 → 1.1.2

package/docs/spec/label-state-machine.md

@@ -0,0 +1,55 @@
+# Workflow Label State Machine
+
+**Canonical reference** — all pipeline commands and docs point here instead of restating this table inline.
+
+See also: [FORGE Annotation Protocol §6](forge-protocol-v1.md#6-label-state-machine) for the protocol-level specification.
+
+---
+
+## States
+
+| Label | Meaning | Set by |
+|-------|---------|--------|
+| `workflow:investigating` | Investigation phase active | Investigator agent |
+| `workflow:ready-to-build` | Investigation complete, build not started | Investigator agent |
+| `workflow:building` | Build phase active | Builder agent |
+| `workflow:in-review` | PR created, review active | Orchestrator agent |
+| `workflow:merged` | PR merged, issue closed | Close phase agent |
+| `workflow:invalid` | Issue closed as invalid | Investigator agent |
+| `workflow:decomposed` | Issue decomposed into sub-issues | Decomposer agent |
+| `needs-human` | Pipeline blocked, human intervention required | Any agent on error |
+
+## Transitions
+
+```
+(open)
+  → workflow:investigating      [Phase 1: Investigate]
+  → workflow:ready-to-build     [Phase 2: Investigation complete]
+  → workflow:building           [Phase 3: Build started]
+  → workflow:in-review          [Phase 4: PR created]
+  → workflow:merged  [TERMINAL] [Phase 5: PR merged]
+  → workflow:invalid [TERMINAL] [Any phase: closed as invalid]
+  → workflow:decomposed [TERMINAL] [Phase 2: split into sub-issues]
+  → needs-human     [TERMINAL]  [Any phase: pipeline blocked]
+```
+
+## Terminal Labels
+
+Processing stops when any of these labels is set:
+
+- `workflow:merged`
+- `workflow:invalid`
+- `workflow:decomposed`
+- `needs-human`
+
+## Label Exclusivity
+
+At most one `workflow:*` label should be active on an issue at any time. When transitioning, always remove all other `workflow:*` labels:
+
+```bash
+gh issue edit {NUMBER} -R {REPO} \
+  --add-label "workflow:building" \
+  --remove-label "workflow:investigating,workflow:ready-to-build,workflow:in-review,workflow:merged,workflow:invalid,workflow:decomposed"
+```
+
+This is enforced by `scripts/transition-label.sh` — use `resolve_script 'transition-label'` rather than calling `gh issue edit` directly when possible.

package/docs/spec/review-protocol.md

@@ -0,0 +1,158 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# Review Protocol — Normative Reference
+
+**This is the single normative source for the Evidence-Based Review Protocol and the Structured Findings Protocol.**
+
+These protocols are referenced by:
+- `commands/review-pr-agents.md` — agent catalog (includes this via pointer)
+- `commands/review-pr.md` — PR review orchestrator (reads agent catalog which references this)
+- `commands/review-pr-staging.md` — staging review orchestrator (references this directly)
+
+Do not duplicate these protocols in any other file. When updating either protocol, update only this file.
+
+---
+
+## Evidence-Based Review Protocol (ALL Agents Follow)
+
+Every agent MUST follow this protocol:
+
+### 1. Start From the PR Diff
+```bash
+# Verify review is still current before reading diff
+CURRENT_SHA=$(gh pr view [PR_NUMBER] --json headRefOid --jq '.headRefOid')
+if [ "$CURRENT_SHA" != "[REVIEW_SHA]" ]; then
+    echo "WARNING: PR HEAD changed during review. Review may be stale."
+    echo "Review pinned to: [REVIEW_SHA_SHORT]"
+    echo "Current HEAD: $(echo $CURRENT_SHA | cut -c1-7)"
+fi
+
+gh pr diff [PR_NUMBER] --name-only
+gh pr diff [PR_NUMBER]
+```
+
+**Hot-spot prior**:
+[CHURN_CONTEXT]
+
+If a file you are reviewing is listed above as a hot-spot, apply deeper scrutiny to it — high historical churn correlates with defect density. Prefer tracing that file's full code paths (Evidence-Based Review Protocol §2) over a quick pattern scan, and weight ambiguous findings in hot-spot files toward LIKELY rather than POSSIBLE.
+
+### 2. Dynamic Exploration
+- From each changed file, follow imports and function calls
+- Trace data flows across service boundaries (API → Redis → Worker)
+- Search for related code: `grep -rn "function_name" services/`
+
+### 3. Validation Before Reporting
+
+| Confidence | Criteria | Action |
+|------------|----------|--------|
+| **CONFIRMED** | Traced the full code path, found specific lines proving the bug | Report as blocking — P1 issue |
+| **LIKELY** | Code pattern suggests issue but mitigations might exist elsewhere | Report with caveat — P2 issue |
+| **POSSIBLE** | Suspicious pattern but couldn't trace the full flow | Report as informational — P3 advisory (non-blocking) |
+| **UNFOUNDED** | Looked for the issue but found mitigations/correct handling | Do NOT report |
+
+### 3.5 REPRODUCTION GATE — Required Before CONFIRMED Classification
+
+**MANDATORY**: Before classifying any finding as CONFIRMED, you MUST document one of the following forms of reproduction evidence in your report. A pattern match alone is not sufficient.
+
+**Acceptable reproduction evidence (one of)**:
+- **(a) Full code path trace**: List the execution chain from PR-changed code to the failure point. Minimum: 3 steps with specific file + line for each. Example: `services/api/app/routers/billing.py:142 → credits.py:check_balance():87 → returns None → caller at billing.py:148 raises AttributeError`. The chain must terminate at the actual failure — not at "and then it could fail."
+- **(b) Specific input demonstration**: Provide concrete input values that trigger the failure. Example: `POST /api/v1/scrape with {"url": "http://internal:6432/"}` → `requests.get()` hits internal DB port → SSRF confirmed. The values must be specific (not "if an attacker provides a malicious URL") and must map to actual code in the PR diff.
+
+**Downgrade rule**: If you cannot produce either (a) or (b) after a reasonable trace attempt, you MUST classify the finding as **POSSIBLE** — not CONFIRMED or LIKELY. Do NOT use CONFIRMED when the finding is based on:
+- A suspicious pattern without tracing whether the condition is reachable via changed code
+- A theoretical exploit path not grounded in specific lines from the diff
+- A heuristic ("this type of code often has X bug") without verification
+
+**POSSIBLE findings are informational advisories** — they are logged and tracked but do NOT block merge and do NOT trigger mandatory fix PRs. When in doubt, POSSIBLE is the correct classification. <!-- Added: forge#371 -->
+
+### 4. SEVERITY CLASSIFICATION — TRACE THE IMPACT
+
+**CRITICAL RULE: Never dismiss a finding as "minor", "cosmetic", or "harmless" without tracing its downstream impact.** If you spot something unusual (redundant code, odd patterns, duplicated values), ask: "Does this cause a runtime error, data corruption, or wrong behavior in any code path that touches it?" Trace forward through every consumer of the construct.
+
+**Severity decision tree:**
+1. Will this error at runtime? → **HIGH or CRITICAL** (not "minor redundancy")
+2. Will this produce wrong data silently? → **HIGH**
+3. Will this cause degraded performance? → **MEDIUM**
+4. Is it genuinely cosmetic with no runtime impact after tracing all consumers? → **LOW**
+
+If you're unsure whether something is cosmetic or a runtime error, **assume it's a runtime error** and flag it for investigation. A false positive costs a minute of review time. A missed runtime error costs production downtime.
+
+### 5. INTERACTION ANALYSIS — "Pre-existing" Is Not "Safe"
+
+**CRITICAL RULE: Never dismiss a finding as "pre-existing, not introduced by this PR" without checking whether NEW code in the PR interacts with the pre-existing construct to create a bug.**
+
+A redundant import, an unused variable, or a duplicated constant may be harmless in isolation. But new code added in the same scope can turn it into a crash. Example: a local `import os` inside a function is harmless until new code above it calls `os.getenv()` — Python treats `os` as local for the entire function scope, causing `UnboundLocalError` before the import line is reached.
+
+**Before dismissing anything as "pre-existing":**
+1. List every NEW line in the PR that references the pre-existing construct
+2. For each reference, ask: "Does the pre-existing construct cause this new line to fail at runtime?"
+3. If yes → CONFIRMED finding, not a dismissal
+
+### 6. FALSE POSITIVE PREVENTION
+
+**Before claiming variable scope issues:** Read the FULL function, count indentation levels, check if/else structure.
+
+**Before claiming type/unit mismatches:** Trace the variable to its source. Check if naming is misleading (e.g., `balanceCents` might hold microcents).
+
+**Before claiming missing functions/imports:** `grep -rn "functionName" .` — check re-exports, aliases.
+
+**Before claiming unreachable code:** Check all callers, dynamic dispatch, test code.
+
+**Before dismissing redundant imports as harmless:** In Python, a local `import X` inside a function makes `X` a local variable for the ENTIRE function scope. Any use of `X` before that import line will raise `UnboundLocalError`. Check whether any code (existing or new) references `X` before the local import. This is a CONFIRMED CRITICAL if found — it crashes at runtime.
+
+### 7. Report Format
+
+Every finding must include:
+- **File:Line** — Exact location
+- **Code snippet** — The problematic code
+- **Evidence** — Why this is a bug (show the code path)
+- **Confidence** — CONFIRMED/LIKELY/POSSIBLE
+- **What you checked** — List files you read to verify
+
+---
+
+## Structured Findings Protocol
+
+**All review agents MUST include a machine-readable findings block at the end of their PR comment.** This is NON-OPTIONAL. Without structured findings, the review system cannot create GitHub issues, and findings die as unread PR comments. Every finding that doesn't become a GitHub issue is a finding that will never be addressed.
+
+### Format
+
+Append this block at the very end of your comment (after the `---` footer line, still inside the EOF heredoc). It uses HTML comments so it's invisible in rendered markdown:
+
+`<!-- REVIEW-FINDINGS-START -->`
+`<!-- FINDING:PREFIX-N|CONFIDENCE|SEVERITY|file.py:line|One-line summary -->`
+`<!-- REVIEW-FINDINGS-END -->`
+
+### Rules
+
+1. **Include ALL findings at CONFIRMED, LIKELY, and POSSIBLE confidence** — every finding becomes a GitHub issue. Nothing stays as just a PR comment. **POSSIBLE findings are informational advisories (P3/non-blocking)** — they are tracked but do not require a fix PR and do not block merge. CONFIRMED and LIKELY findings are blocking at P1/P2 respectively.
+2. **One line per finding** — sequential numbering (PREFIX-1, PREFIX-2, ...)
+3. **Confidence**: `CONFIRMED`, `LIKELY`, or `POSSIBLE`
+4. **Severity**: `CRITICAL`, `HIGH`, `MEDIUM`, or `LOW`
+5. **Location**: Exact `file:line` reference
+6. **Summary**: Concise one-line description (no pipe `|` characters in summary)
+7. **Empty block**: If no findings at all, include just the START/END markers
+8. **HTML comments**: The block is invisible in rendered markdown but parseable by the review system
+
+### Domain Prefixes
+
+| Agent | Prefix |
+|-------|--------|
+| General Security | `SEC` |
+| Auth Conventions | `AUTH` |
+| Billing Integrity | `BILL` |
+| Concurrency | `CONC` |
+| Scraper Logic | `SCRP` |
+| Frontend Quality | `FE` |
+| API Design | `API` |
+| Database & Migration | `DB` |
+| Infrastructure | `INFRA` |
+| Config Schema | `CFG` |
+
+### Example
+
+`<!-- REVIEW-FINDINGS-START -->`
+`<!-- FINDING:SEC-1|CONFIRMED|HIGH|services/api/app/routers/scrape.py:45|SQL injection via unsanitized user input in query parameter -->`
+`<!-- FINDING:SEC-2|LIKELY|MEDIUM|services/worker/worker/queues.py:312|Potential SSRF through user-controlled proxy URL -->`
+`<!-- REVIEW-FINDINGS-END -->`

package/docs/spec-graph-schema.md

@@ -395,3 +395,31 @@ task-relevant spec set instead of letting the agent load blindly.
 
 Shipping the wiring is deferred because no hook-infrastructure layer exists in
 the repo yet; this section is the spec that a later issue implements against.
+
+## Nested-Command Decomposition and the Graph
+
+The spec graph's `walk()` function (in `build-spec-graph.mjs`) and the
+`load-set` query together enable the nested-command decomposition pattern. A
+brief summary is given here; the full naming convention, decomposition criteria,
+and token-saving effect are documented in
+**`docs/spec/forge-protocol-v1.md` § 10 (Nested-Command Decomposition
+Pattern)**.
+
+**How nested specs become graph nodes**: `walk()` recursively discovers every
+`commands/**/*.md` file at any depth. Each file is registered as a `cmd:` node
+whose id follows the Skill() colon-delimited form (`cmd:work-on:build:context`
+for `commands/work-on/build/context.md`). `CONTAINS` edges are inferred when a
+parent spec references a child via `Skill(skill="<name>", ...)`.
+
+**How `load-set` exploits decomposition**: `load-set <command>` seeds at the
+command's node and walks `CONTAINS` and `REQUIRES` edges forward. A decomposed
+command like `work-on` returns only the 11 files its execution graph actually
+reaches — not the full ~44-spec corpus. Sub-specs that belong to `work-on/build/`
+but are only invoked under specific conditions (e.g., `context.md` is skipped for
+TRIVIAL tasks) can be added or removed from the reachable set by updating the
+`CONTAINS` edges in the parent spec, without changing the query logic.
+
+**Token-saving measurement**: See
+`docs/articles/command-decomposition-token-savings.md` for before/after token
+counts for `/review-pr` and `/orchestrate` following their spec decompositions
+in #1271 and #1272.

package/docs/superpowers/specs/2026-07-04-economic-self-governance-design.md

@@ -0,0 +1,181 @@
+# Economic Self-Governance — Design Spec
+
+**Date:** 2026-07-04
+**Status:** Design — ready to build
+**Tracking:** #1317 (economics layer), epic #1320 (five foundations of autonomy)
+**Scope:** Risk×cost go/no-go scoring function, budget-aware scheduler, and backpressure model. Unifies #1313 (preserve `needs-human`) and #1314 (autopilot `--yes` for low-risk) into a single decision model.
+
+---
+
+## 1. Motivation
+
+Safety Rule 3 in `/orchestrate` today reads: "no artificial concurrency limit — spawn as many agents as there are issues." That is the opposite of autonomy. Autonomy is **knowing when not to act**.
+
+The current decision surface has three static switches:
+
+| Surface | Policy | Problem |
+|---------|--------|---------|
+| `/work-on` solo | Ask human at every ambiguity | Over-asks on clear issues |
+| `/orchestrate` | "NEVER ask… merge anyway" | Under-asks on high-risk changes |
+| `/autopilot` | Gate every fix | Blocks low-risk wins behind human review |
+
+None of these is a decision — they are static switches baked into prose. The result: an agent either burns compute on issues it should not touch, or stalls on issues it could safely auto-run. Neither is economic.
+
+The fix is a **self-governing scheduler** that treats compute as a budget and makes an explicit go/no-go per issue before spawning any agent.
+
+---
+
+## 2. Goals / Non-goals
+
+**Goals**
+- A scoring function `(expected_cost, risk_tier, confidence) → {auto, escalate, defer}` runs before each issue is dispatched.
+- Per-run and per-wave budget caps with backpressure replace the "no artificial concurrency limit" rule.
+- `#1313` (preserve `needs-human` for high-risk) and `#1314` (autopilot `--yes` for low-risk) both fall out of the single model as threshold configurations — not separate flags.
+- The decision and its inputs are recorded in `FORGE:ECONOMICS` so runs are auditable.
+
+**Non-goals**
+- Real-time token streaming cost measurement (post-run accounting only, fed by #1255/#1295).
+- The durable engine state machine (#1256) — assumed as a substrate but not implemented here.
+- Per-turn interruption of in-flight agents (this spec is pre-dispatch).
+
+---
+
+## 3. Locked Decisions
+
+1. **Decision granularity: per-issue, pre-dispatch.** The go/no-go is computed once before an agent is spawned. Mid-run escalation is a separate concern.
+2. **Three-outcome model: `auto | escalate | defer`.** `auto` = spawn with no human gate. `escalate` = post a comment and wait for human approval. `defer` = place back in queue with lower priority, do not block the wave.
+3. **Budget authority: the orchestrator holds the budget, not individual agents.** Agents report estimated cost; the orchestrator decides whether to spend it.
+4. **Score inputs are observable.** Every input to the scoring function is logged in `FORGE:ECONOMICS` before any agent runs — so a human can audit why an issue was auto-run or escalated.
+5. **Thresholds are configurable in `forge.yaml`.** Default thresholds ship with the spec; operators can tighten or loosen them without editing command files.
+
+---
+
+## 4. Architecture
+
+### 4.1 Scoring Function
+
+```
+score(issue) → { decision, reasoning, estimated_cost, risk_tier, confidence }
+```
+
+**Inputs:**
+
+| Input | Source | Type |
+|-------|--------|------|
+| `expected_cost` | Historical cost-per-issue data (#1255/#1295) or heuristic (label + size estimate) | USD float |
+| `risk_tier` | Domain risk tag on issue label (`risk:low`, `risk:medium`, `risk:high`) or inferred from affected paths | `low \| medium \| high` |
+| `confidence` | FORGE:INVESTIGATOR confidence field, or `0.5` if no investigation comment exists | 0.0–1.0 |
+| `budget_remaining` | Current wave budget minus committed spend | USD float |
+| `needs_human` | Issue has `needs-human` label | bool |
+
+**Decision matrix (defaults):**
+
+| risk_tier | confidence | expected_cost | decision |
+|-----------|-----------|---------------|----------|
+| `low` | ≥ 0.7 | ≤ $0.50 | `auto` |
+| `low` | ≥ 0.7 | > $0.50 | `escalate` |
+| `low` | < 0.7 | any | `escalate` |
+| `medium` | ≥ 0.8 | ≤ $0.30 | `auto` |
+| `medium` | any other | any | `escalate` |
+| `high` | any | any | `escalate` |
+| any | any | > budget_remaining | `defer` |
+| `needs_human=true` | any | any | `escalate` (always) |
+
+Thresholds are overridable via `forge.yaml → economics`:
+
+```yaml
+economics:
+  auto_cost_ceiling_usd: 0.50       # max cost for auto-run (low risk)
+  medium_auto_cost_ceiling_usd: 0.30
+  auto_confidence_floor: 0.70
+  medium_confidence_floor: 0.80
+  wave_budget_usd: 5.00             # per-wave budget cap
+  run_budget_usd: 20.00             # per-run (session) budget cap
+```
+
+### 4.2 Budget Tracker
+
+A simple stateful accumulator maintained by the orchestrator across the wave:
+
+```
+budget_tracker = {
+  wave_limit: float,        # from forge.yaml or --budget flag
+  wave_committed: float,    # sum of expected_cost for auto-dispatched issues
+  wave_actual: float,       # sum of reported actual cost from completed agents
+  run_limit: float,
+  run_committed: float,
+}
+```
+
+`defer` fires when `wave_committed + expected_cost > wave_limit * 0.90` (10% buffer to absorb cost overruns).
+
+Backpressure: when the wave budget is exhausted, remaining issues are set to `workflow:deferred` label and the orchestrator reports a budget summary. They are the first candidates in the next wave.
+
+### 4.3 FORGE:ECONOMICS Annotation
+
+Written to the issue before the agent is spawned (or before posting the escalation comment):
+
+```html
+<!-- FORGE:ECONOMICS
+decision: auto
+risk_tier: low
+confidence: 0.82
+expected_cost_usd: 0.18
+budget_remaining_usd: 3.47
+wave: 1
+rationale: "low-risk label, high investigation confidence, well within budget"
+timestamp: 2026-07-04T12:00:00Z
+-->
+```
+
+Downstream stages (verification gate, provenance) can read this annotation to understand the economic context of the decision.
+
+### 4.4 Integration Points
+
+**`/orchestrate`**: Phase 2B (issue selection) gains a `score_issues()` step before dispatching agents. Issues that score `escalate` are held; `auto` issues proceed; `defer` issues are re-queued.
+
+**`/autopilot`**: The `--fix` phase queries the scoring function instead of the current "gate every fix" heuristic. `--yes` flag sets `auto_confidence_floor: 0.0` and raises cost ceilings — effectively the current `--yes` behavior, but explicit and auditable.
+
+**`/work-on`**: Solo interactive use is unaffected. The scoring function is opt-in via `forge.yaml → economics.solo_mode: enabled`.
+
+---
+
+## 5. Implementation Plan
+
+### Increment 1: Scoring function + FORGE:ECONOMICS (no budget tracking)
+- Add `score_issue()` logic to `/orchestrate` Phase 2B.
+- Read domain risk labels and FORGE:INVESTIGATOR confidence.
+- Emit `FORGE:ECONOMICS` annotation.
+- `escalate` path posts a comment and adds `needs-human` label; agent is not spawned.
+- `defer` path is treated as `escalate` in this increment.
+
+### Increment 2: Budget tracker + backpressure
+- Add `budget_tracker` state to orchestrator.
+- Read `forge.yaml → economics` thresholds.
+- `defer` path sets `workflow:deferred` label and skips the issue.
+- Post wave budget summary at end of orchestrator run.
+
+### Increment 3: Unify #1313 and #1314
+- Remove hard-coded "NEVER ask" language from `/orchestrate`.
+- Remove hard-coded "gate every fix" from `/autopilot`.
+- Both commands delegate to the scoring function with appropriate threshold profiles (`orchestrate` uses `medium_confidence_floor`, `autopilot --yes` raises ceilings).
+
+---
+
+## 6. Open Questions
+
+- **Cost estimation without history**: For issues with no historical data, the default heuristic is label-based (`bug` → $0.20, `feat` → $0.40, `epic` → $1.00). This needs calibration once #1255 data is available.
+- **Risk tag inference**: If no `risk:*` label exists, infer from affected paths (e.g., changes to `bin/`, `commands/quality-gate.md`, or CI workflows → `risk:high`). Path-based inference is a follow-on to Increment 1.
+- **Wave vs. run budget interaction**: A "run" spans multiple waves in `/autopilot`. The run budget should be the outer limit; wave budget is the inner pacing mechanism.
+
+---
+
+## 7. References
+
+- #1317 — this issue
+- #1255, #1295, #1296, #1297 — cost-per-issue accounting (feeds `expected_cost`)
+- #1249 — per-agent model/effort tiering (feeds `expected_cost`)
+- #1313 — preserve `needs-human` for high-risk (subsumed by this spec)
+- #1314 — autopilot `--yes` for low-risk (subsumed by this spec)
+- #1320 — five foundations epic (economics layer)
+- #1256 — durable engine (substrate for stateful budget tracking)

package/docs/superpowers/specs/2026-07-04-provenance-trail-design.md

@@ -0,0 +1,189 @@
+# Signed, Replayable Provenance Trail — Design Spec
+
+**Date:** 2026-07-04
+**Status:** Design — ready to build
+**Tracking:** #1318 (provenance layer), epic #1320 (five foundations of autonomy)
+**Depends on:** #1256 (durable engine run-log — replayability requires a committed step log)
+**Scope:** Integrity guarantee + replayability layer on top of the existing FORGE annotation protocol (#1291–1294). Every autonomous PR carries a signed attestation linking decisions → verification evidence → alternatives rejected.
+
+---
+
+## 1. Motivation
+
+For an organization to allow autonomous merges to production, every change needs a complete, verifiable record of *why it was made, what was verified, and what alternatives were considered and rejected* — reproducibly.
+
+Today provenance is scattered `FORGE:*` comments with no integrity guarantee:
+
+| Gap | Current state | Problem |
+|-----|--------------|---------|
+| Integrity | Comments are plain Markdown, mutable | Any party can edit or delete them after the fact |
+| Completeness | Each annotation covers one phase | No single artifact links decision → evidence → alternatives |
+| Replayability | State is prose — humans can read it but tools cannot deterministically replay it | Resume re-parses prose heuristically |
+| Attestation | No signed artifact exists | Human reviewers have no cryptographic basis to trust "the agent said it was safe" |
+
+**Trust, not capability, is the blocker to auto-merge.** This spec adds integrity + replayability + a signed attestation on top of the existing FORGE protocol, without replacing it.
+
+---
+
+## 2. Goals / Non-goals
+
+**Goals**
+- Each autonomous PR carries a `FORGE:PROVENANCE` attestation that links: investigation decision → build decisions → verification evidence → rejected alternatives.
+- A run is replayable from its provenance record + durable engine run-log (#1256).
+- The provenance record validates against the FORGE protocol conformance suite (#1291).
+- Integrity is achieved via a content hash over the structured annotation chain — no external PKI required for v1.
+
+**Non-goals**
+- Hardware-rooted signing (TPM, HSM) — out of scope for v1; the content hash gives tamper-evidence without it.
+- Retroactive provenance for runs completed before this spec ships.
+- Per-turn provenance (this spec is per-run / per-PR granularity, matching the durable engine's per-phase checkpoint).
+- Provenance for interactive `/work-on` runs (headless/orchestrated first, interactive later).
+
+---
+
+## 3. Locked Decisions
+
+1. **Attestation format: structured HTML comment (`FORGE:PROVENANCE`) on the PR.** Consistent with the existing annotation protocol. Readable by humans in the PR thread and queryable by the same text-contains filters used today.
+2. **Integrity mechanism: SHA-256 content hash over a canonical serialization of the annotation chain.** The hash is computed over the ordered sequence of `FORGE:*` annotation bodies (canonically serialized as JSON). Anyone with the run-log can recompute it.
+3. **Replayability: the durable engine run-log is the replay substrate.** The `FORGE:PROVENANCE` record carries a pointer to the run-log location (issue comment ID sequence). A conformant replayer reads those comments in order and reconstructs the pipeline state.
+4. **Chain of custody: each annotation carries a `seq` (sequence number) and `prev_hash` (hash of the prior annotation).** This forms a tamper-evident linked list. Adding, removing, or reordering annotations breaks the hash chain.
+5. **The attestation is written by the durable engine, not by individual phase agents.** Agents write their phase annotations as today; the engine writes the final `FORGE:PROVENANCE` after the merge gate passes.
+
+---
+
+## 4. Architecture
+
+### 4.1 Annotation Chain Extension
+
+Existing FORGE annotations gain two new fields (backward-compatible — consumers that do not understand them ignore them):
+
+```
+<!-- FORGE:INVESTIGATOR
+seq: 1
+prev_hash: "genesis"
+...existing fields...
+body_hash: "sha256:a1b2c3..."
+-->
+```
+
+| New field | Type | Description |
+|-----------|------|-------------|
+| `seq` | integer | Position in the annotation chain for this run (1-indexed) |
+| `prev_hash` | string | SHA-256 of the prior annotation's canonical body, or `"genesis"` for the first |
+| `body_hash` | string | SHA-256 of this annotation's canonical body (self-hash, written last) |
+
+**Canonical body**: the annotation content between the `<!-- FORGE:TAG` opening and the `-->` closing, with leading/trailing whitespace stripped and line endings normalized to `\n`, serialized as a UTF-8 JSON string.
+
+### 4.2 FORGE:PROVENANCE Annotation
+
+Written to the PR by the durable engine after the merge gate passes, before the merge commit:
+
+```html
+<!-- FORGE:PROVENANCE
+run_id: "run-abc123"
+issue: 1317
+pr: 1460
+pipeline_version: "1.0.21"
+agent_model: "claude-sonnet-4-6"
+
+chain:
+  - seq: 1  tag: INVESTIGATOR  comment_id: 2345678901  body_hash: "sha256:a1b2..."
+  - seq: 2  tag: ARCHITECT      comment_id: 2345678910  body_hash: "sha256:b2c3..."
+  - seq: 3  tag: BUILDER        comment_id: 2345678920  body_hash: "sha256:c3d4..."
+  - seq: 4  tag: REVIEWER       comment_id: 2345678930  body_hash: "sha256:d4e5..."
+  - seq: 5  tag: QUALITY_GATE   comment_id: 2345678940  body_hash: "sha256:e5f6..."
+  - seq: 6  tag: ECONOMICS      comment_id: 2345678950  body_hash: "sha256:f6a7..."
+
+chain_hash: "sha256:0123456789abcdef..."
+verification_passed: true
+alternatives_considered:
+  - "Inline fix without issue — rejected: no traceability"
+  - "Defer to manual review — rejected: low-risk score 0.82"
+merge_authorized_by: "economic-self-governance"
+timestamp: 2026-07-04T18:00:00Z
+forge_protocol_version: "1.0"
+-->
+<!-- FORGE:PROVENANCE:COMPLETE -->
+```
+
+**`chain_hash`**: SHA-256 of the concatenated `body_hash` values in `seq` order, joined with `\n`. Recomputable from the listed comment IDs alone.
+
+### 4.3 Replayability Contract
+
+A conformant replayer MUST be able to reconstruct the pipeline state for a given `run_id` by:
+
+1. Reading the `FORGE:PROVENANCE` annotation from the PR to get the `chain` (comment ID list).
+2. Fetching each comment in `seq` order from the GitHub API.
+3. Parsing each `FORGE:*` annotation body.
+4. Recomputing the `chain_hash` and asserting it matches the recorded value.
+5. Replaying the durable engine run-log (from `#1256`) for per-phase step details.
+
+Step 4 is the integrity check. A mismatch means the annotation chain was tampered with after the run.
+
+### 4.4 Conformance Suite Integration (#1291)
+
+The FORGE protocol conformance suite gains a new test category: **Provenance Conformance**.
+
+| Test | Pass condition |
+|------|---------------|
+| `P-01` | PR has exactly one `FORGE:PROVENANCE` annotation followed by `FORGE:PROVENANCE:COMPLETE` |
+| `P-02` | All `seq` values in the chain are contiguous starting from 1 |
+| `P-03` | Each `prev_hash` matches the `body_hash` of the prior annotation (or `"genesis"` for seq=1) |
+| `P-04` | `chain_hash` recomputes correctly from the listed `body_hash` values |
+| `P-05` | All annotations referenced in the chain are fetchable and parse as valid FORGE annotations |
+| `P-06` | `timestamp` is an ISO 8601 UTC datetime |
+| `P-07` | `forge_protocol_version` is present and a known value |
+
+### 4.5 Integration Points
+
+**Durable engine (`#1256`)**: After merge gate passes, the engine invokes `write_provenance()`:
+- Collects all annotation comment IDs from the run-log.
+- Fetches each annotation body and computes `body_hash` values.
+- Computes `chain_hash`.
+- Posts `FORGE:PROVENANCE` to the PR.
+
+**Quality gate (`/quality-gate`)**: Gains a new check: `PROVENANCE` — verifies `P-01` through `P-07`. Fails the gate if any check fails on an autonomous run. Human-initiated runs emit a warning (not a hard failure) if provenance is absent.
+
+**`/replay` command**: Uses the `chain` from `FORGE:PROVENANCE` as the replay index instead of scanning all comments for `FORGE:*` annotations. This is faster and guaranteed-ordered.
+
+---
+
+## 5. Implementation Plan
+
+### Increment 1: Chain fields on existing annotations (non-breaking)
+- Modify durable engine to write `seq`, `prev_hash`, and `body_hash` on each annotation it posts.
+- No consumer changes required — fields are additive.
+- Validate that existing annotations without these fields are still parseable.
+
+### Increment 2: FORGE:PROVENANCE annotation
+- Engine writes `FORGE:PROVENANCE` to the PR after merge gate passes.
+- Includes `chain`, `chain_hash`, `verification_passed`, `timestamp`.
+- `/replay` updated to use the chain index when present.
+
+### Increment 3: Conformance tests + quality gate check
+- Add `P-01` through `P-07` tests to the conformance suite (#1291).
+- Add `PROVENANCE` check to `/quality-gate` (warning on human runs, hard failure on autonomous runs).
+
+### Increment 4: Replayability validation
+- Add a `verify_provenance(run_id)` script to `scripts/`.
+- Script fetches the PR, reads `FORGE:PROVENANCE`, fetches all chained comments, recomputes `chain_hash`, and reports pass/fail.
+
+---
+
+## 6. Open Questions
+
+- **Comment mutability**: GitHub allows editing comments. The hash chain detects tampering but does not prevent it. For v2, consider posting annotations to an immutable artifact (e.g., a GitHub Release asset or a signed commit note) as an optional hardened mode.
+- **`body_hash` for legacy annotations**: If an annotation was written before this spec (no `body_hash` field), the chain is broken. Acceptable for v1: the `FORGE:PROVENANCE` chain only covers annotations written by the durable engine (which will be updated atomically). Legacy runs have no provenance claim.
+- **`alternatives_considered` source**: In v1 this is written by the engine based on the economics decision (#1317) and the quality-gate outcome. A richer alternatives record (e.g., architect alternatives from `FORGE:ARCHITECT`) can be pulled in a later increment.
+
+---
+
+## 7. References
+
+- #1318 — this issue
+- #1291–1294 — FORGE protocol conformance suite (seed schema)
+- #1256 — durable engine (run-log substrate; required for replayability)
+- #1315 — outcome-based acceptance gate (supplies "what was verified" evidence)
+- #1317 — economic self-governance (supplies `merge_authorized_by` and `alternatives_considered`)
+- #1320 — five foundations epic (provenance layer)
+- `docs/spec/forge-protocol-v1.md` — FORGE annotation protocol v1.0