@garygentry/feature-forge 0.2.13 → 0.3.0

package/adapters/pi/skills/forge-6-docs/SKILL.md

@@ -0,0 +1,202 @@
+---
+# GENERATED — DO NOT EDIT. Source: skills/forge-6-docs/SKILL.md. Regenerate: python3 scripts/build-adapters.py
+name: forge-6-docs
+description: Generate developer-focused architecture documentation for a forge pipeline feature. Use when user runs /skill:forge-6-docs or asks to generate docs after implementation is complete. Do NOT trigger for general documentation writing, README creation, or doc generation outside the forge pipeline.
+---
+
+# forge-6-docs — Architecture Documentation Generator
+
+Generate developer-focused architecture documentation for a feature, suitable for onboarding, reference, and maintenance.
+
+## Prerequisites
+
+Read and follow `references/shared-conventions.md` for feature name validation, configuration reading, and force mode handling before proceeding.
+
+**Turn structure reminder:** Output analysis/context as text, then route ALL questions through `AskUserQuestion`. Never embed questions in text output — the user will not be prompted and the session will stall.
+
+## Step 1: Read Context
+
+Resolve the feature directory via the **Feature Directory Resolution** block in `references/shared-conventions.md` (so a standalone feature resolves to its flat `{specsDir}/{feature}/` path exactly as today, and an epic member resolves to its nested path). Use the resulting `{resolvedFeatureDir}` everywhere this skill previously wrote `{specsDir}/{feature}/`.
+
+Read `{resolvedFeatureDir}/.pipeline-state.json` to understand what exists.
+
+### Gather Sources
+
+Load into context:
+1. **Specs**: PRD.md, tech-spec.md, all implementation specs
+2. **Implementation**: Read the actual source code for this feature's package
+3. **Existing docs**: Check `{docsDir}/` for other features' docs to match conventions
+4. **README**: Check if the feature package has its own README.md
+
+### Implementation Completeness Check
+
+Check `{resolvedFeatureDir}/backlog.json` (or `{backlogDir}/{feature}/backlog.json` if configured). Count items with status `complete` vs total. If implementation is less than 80% complete, use `AskUserQuestion` to warn: "Implementation is only N% complete. Documentation will be based primarily on specs and may need updates after implementation. Proceed?" If user proceeds, add a `PRE-IMPLEMENTATION` notice at the top of each generated doc.
+
+Also check `.pipeline-state.json` for `stages.forge-5-loop`. If it exists and has status `in-progress` (some items incomplete), include this in the warning: "The rauf loop has not fully completed — {done}/{total} items done. Documentation may need updates after remaining items are implemented."
+
+### Impl-Verify Backstop
+
+Check `.pipeline-state.json` for `stages.forge-verify-impl`. If it is **absent** or has status `"skipped"`, use `AskUserQuestion` to warn with the cost of skipping: "Implementation hasn't been verified yet. Recommended: run `/skill:forge-verify {feature} impl` first to audit the loop's output — docs generated over unverified code can document bugs or gaps as if they were intended behavior, and readers will trust them. Generate docs anyway?" Offer **Verify first (recommended)** · **Generate docs anyway**. This mirrors `forge-4-backlog`'s pre-stage verification check and backstops a skipped impl-verify regardless of how the loop ended. If `stages.forge-verify-impl` shows it already ran (`findings-applied`, `findings-reported`, or `passed`), proceed with no warning.
+
+### Epic-Level Documentation (epic members only)
+
+If the resolved feature has an `epic` back-pointer in its `.pipeline-state.json`, run:
+
+```bash
+R="$(bash -c 'for d in "${FEATURE_FORGE_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
+[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
+python3 "$R/scripts/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
+```
+
+If `render-status` fails, skip the epic-level offer and proceed with the per-feature docs only; surface the error per the exit-1/exit-2 split in the **Feature Directory Resolution** block of `references/shared-conventions.md` (exit 1 → parse `{findings[]}` from stdout; exit 2 → surface the plain `Error:` stderr line verbatim).
+
+**Only if `rollup.total > 0 AND rollup.complete == rollup.total`** (every member is complete-for-orchestration; the `total > 0` guard excludes an empty epic), offer the extra doc as a statement the user can take or leave — not a forced question:
+
+"All {total} features in the '{epic}' epic are complete. I can also generate an **epic-level architecture document** spanning the features, alongside {feature}'s per-feature docs — say the word and I'll add it."
+
+If the user asks for it, synthesize a doc at **`{docsDir}/{epic}/`** sourced from: the `EPIC.md` narrative, each member's per-feature docs, and the manifest contracts (each feature's `exposes`/`consumes`). When the epic-level doc is written, the Step 5 commit also stages `{docsDir}/{epic}/`.
+
+If not all members are complete (or the feature has no `epic` back-pointer), **do not offer** — the per-feature doc flow proceeds unchanged.
+
+Read `references/doc-conventions.md` for documentation standards.
+
+## Step 2: Plan Documentation Structure
+
+Based on feature complexity and existing doc conventions, propose a doc plan:
+
+**Minimum (simple feature):**
+```
+{docsDir}/{feature}/
+├── README.md          — Overview, quick start, key concepts
+└── api-reference.md   — Exported APIs, types, configuration
+```
+
+**Standard (typical feature):**
+```
+{docsDir}/{feature}/
+├── README.md          — Overview, quick start, key concepts
+├── architecture.md    — Design decisions, data flow, component relationships
+├── api-reference.md   — Exported APIs, types, configuration
+└── guides/
+    └── integration.md — How to integrate this feature into an app
+```
+
+**Comprehensive (complex feature):**
+```
+{docsDir}/{feature}/
+├── README.md          — Overview, quick start, key concepts
+├── architecture.md    — Design decisions, data flow, component relationships
+├── api-reference.md   — Exported APIs, types, configuration
+├── configuration.md   — All configuration options with examples
+├── guides/
+│   ├── getting-started.md  — Step-by-step setup
+│   ├── integration.md      — How to integrate with other packages
+│   └── troubleshooting.md  — Common issues and solutions
+└── decisions/
+    └── adr-001-*.md   — Architecture decision records (if significant decisions were made)
+```
+
+Present the plan as a statement and invite edits before writing — not a forced confirmation gate: "Here's the doc plan I'll generate. Tell me if you want to add, remove, or restructure any documents; otherwise I'll proceed." Write the docs unless the user asks for changes.
+
+## Step 3: Write Documentation
+
+### Key Principles
+
+**Write for the reader, not the writer.**
+- A developer encountering this feature for the first time should be able to understand it from the docs alone
+- Lead with the "what" and "why" before the "how"
+- Include code examples for every exported API
+- Don't assume familiarity with the spec documents
+
+**Be accurate to the implementation, not the spec.**
+- If the implementation diverged from the spec, document the implementation
+- Specs are the source of truth for design intent; code is the source of truth for behavior
+- Read the actual source code to verify your documentation is correct
+
+**Don't cite or link spec files in the generated docs.**
+- Read the specs freely for context, but the docs you write are shipped implementation artifacts — they must be self-contained
+- Never link or reference `PRD.md`, `tech-spec.md`, or the numbered implementation specs (`specs/{feature}/NN-*.md`); these are pre-implementation artifacts that may be archived or deleted
+- Reference only the code, runtime contracts/configuration, and other generated docs. If you need to convey design intent, write it directly into the doc rather than pointing at a spec
+
+**Match existing conventions.**
+- If other features' docs use a specific heading structure, follow it
+- If they include diagrams, include diagrams
+- If they use a specific tone (formal, casual, tutorial-style), match it
+
+### README.md Structure
+
+```markdown
+# {Feature Name}
+
+{One-paragraph description of what this feature does and why it exists.}
+
+## Quick Start
+
+{Minimal code to get started — import, configure, use.}
+
+## Key Concepts
+
+{Explain the domain model and core abstractions in plain language.}
+
+## Package Exports
+
+{Table of subpath exports and what each contains.}
+
+| Export / Entry Point | Description |
+|---------------------|-------------|
+| `{module}` | Shared types and utilities |
+| `{module}/server` | Server-side functionality |
+| ...    | ... |
+
+Adapt export paths to match the project's module/package conventions.
+
+## Configuration
+
+{Key configuration options with defaults.}
+
+## Further Reading
+
+- [Architecture](./architecture.md) — Design decisions and data flow
+- [API Reference](./api-reference.md) — Complete API documentation
+- [Integration Guide](./guides/integration.md) — How to use with other packages
+```
+
+## Step 4: Review with User
+
+Present the docs as text. Then use `AskUserQuestion` to collect feedback — do NOT include these questions in your text output:
+
+"1. Does this accurately reflect the implementation? 2. Is the level of detail appropriate for your team? 3. Any areas that need more explanation?"
+
+## Step 5: Update Pipeline State and Commit
+
+Write pipeline state conforming to `references/pipeline-state-schema.json`.
+
+1. Update `{resolvedFeatureDir}/.pipeline-state.json`:
+   - Set `currentStage` to `complete`
+   - Record `artifacts`
+   - Set `stages.forge-6-docs.basedOnVersions` to include versions for all completed upstream stages. Always include forge-1-prd, forge-2-tech, forge-3-specs. Include forge-4-backlog and forge-5-loop ONLY if they have status `complete`.
+2. If `gitCommitAfterStage` is true, follow the Git Commit Protocol in `references/shared-conventions.md`: stage files (`git add {docsDir}/{feature}/ {resolvedFeatureDir}/` — and **also** `{docsDir}/{epic}/` when an epic-level doc was written in Step 1), attempt commit with message `"{commitPrefix}({feature}): complete architecture docs"` (marking `stages.forge-6-docs.status` `complete` with `commitHash: null` in that commit), then record the artifact-commit hash via the protocol's two-commit follow-up (never `--amend`) only on success. If commit fails, leave status as `in-progress`.
+4. Tell user: "Documentation complete. Feature pipeline for '{feature}' is finished!\n  `/skill:forge {feature}` to see the final pipeline status." Then **hand off to the next unit of work** — do not dead-end here (Issue #124):
+
+   - **Epic member** (the resolved feature has an `epic` back-pointer in its `.pipeline-state.json`): reuse the `render-status "{epic}" --specs-dir "{specsDir}" --json` output from Step 1's Epic-Level Documentation block (re-run it if you skipped that block). If `actionable` is non-empty, point at the next member: "Epic '{epic}' has {total−complete} feature(s) left — next up: **{actionable[0].name}**. Start it with `{actionable[0].nextCommand}`." (Offer to start it now if the host can invoke it — honor `autoInvokeNextStage` + `Skill`-tool availability; else just print the command.) If `actionable` is empty but the epic is not fully complete, note the remaining members are blocked on dependencies. If the epic is fully complete (`rollup.complete == rollup.total`, `total > 0`), congratulate on the whole epic — the epic-level architecture doc was already offered in Step 1 — and point at `/skill:forge {epic}` for the finished dashboard.
+   - **Standalone** (no `epic` back-pointer): offer the next feature — "Start a new feature: `/skill:forge-1-prd <feature-name>` (or group several with `/skill:forge-0-epic <epic-name>`). Run `/skill:forge` to see any other active pipelines." Defer the full recency-ranked list of other pipelines to the navigator (`/skill:forge`) rather than duplicating it here.
+
+## Gotchas
+
+- Don't just rephrase the specs. Documentation should explain the implemented system, not the planned system. Read the actual code.
+- Don't cite spec files (PRD.md, tech-spec.md, numbered specs) as sources or "further reading" in the generated docs — specs are pre-implementation artifacts that may not survive. Keep the docs self-contained; link only to code, configuration, and other docs.
+- If the implementation doesn't exist yet (backlog hasn't been run), document based on specs but note prominently that docs are pre-implementation and may need updating.
+- API reference should include actual function signatures from the code, not from the spec (they may differ).
+- Don't generate docs that will immediately be stale. Focus on concepts, architecture, and patterns rather than line-by-line code walkthroughs.
+- Include "When to use" and "When NOT to use" sections — they save developers more time than any other documentation pattern.
+
+---
+
+## Host execution notes (Pi)
+
+This Pi bundle preserves Claude's `AskUserQuestion` references because it ships a Pi compatibility extension registering an `AskUserQuestion` tool. On Pi:
+
+- **User input:** use `AskUserQuestion` for genuine user decisions. It supports multiple questions, option descriptions, recommended ordering, multi-select, previews, and free-form Other/custom answers.
+- **Skill dispatch:** Pi uses `/skill:<name>` commands. If you cannot invoke a skill directly, print the exact `/skill:<name> ...` command for the user to run.
+- **Subagents:** this bundle declares its custom agents (`forge-researcher`, `forge-spec-writer`, `forge-verifier`) as package agents. If a `subagent` tool is registered, dispatch one with `{ agent: "forge-verifier", task: "..." }`, or fan several out concurrently with `{ tasks: [{ agent: "forge-spec-writer", task: "..." }, ...] }`. If no `subagent` tool is available, run that step inline yourself.
+- **Background / monitoring:** run long-lived commands in the foreground and report progress as it arrives.

package/adapters/pi/skills/forge-6-docs/references/doc-conventions.md

@@ -0,0 +1,126 @@
+# Documentation Conventions
+
+Standards and patterns for feature architecture documentation.
+
+## General Rules
+
+- Write in present tense ("The auth module validates..." not "The auth module will validate...")
+- Use second person for guides ("You can configure..." not "One can configure...")
+- Include code examples for every exported function, class, or component
+- Code examples must be runnable — no pseudocode, no incomplete snippets
+- Use the project's primary language for all code examples
+
+## Heading Structure
+
+- H1: Feature name (only in README.md)
+- H2: Major sections
+- H3: Subsections
+- Don't go deeper than H4
+
+## Code Examples
+
+The following examples use TypeScript. Adapt language and import syntax to your project's stack. The principle — always include imports, show complete runnable examples — applies to all languages.
+
+Always include import statements:
+```typescript
+// Good
+import { createAuthMiddleware } from '@repo/auth/server';
+
+const middleware = createAuthMiddleware({ secret: process.env.JWT_SECRET });
+
+// Bad — missing import, unclear where this comes from
+const middleware = createAuthMiddleware({ secret: process.env.JWT_SECRET });
+```
+
+### Complete Quick Start Example
+
+Here's a complete "Quick Start" section showing the expected quality:
+
+```markdown
+## Quick Start
+
+Install the auth package:
+
+```bash
+bun add @repo/auth
+```
+
+Add the auth middleware to your Hono server:
+
+```typescript
+import { createAuthMiddleware } from '@repo/auth/server';
+import { getConfig } from '@repo/config';
+
+const config = getConfig();
+
+app.use('*', createAuthMiddleware({
+  secret: config.auth.jwtSecret,
+  cookieName: 'session',
+}));
+```
+
+Access the session in any route handler:
+
+```typescript
+app.get('/api/me', (c) => {
+  const session = c.get('session');
+  if (!session) return c.json({ error: 'Not authenticated' }, 401);
+  return c.json({ userId: session.userId, roles: session.roles });
+});
+```
+
+For full configuration options, see [API Reference](./api-reference.md).
+For setting up OAuth providers, see [Integration Guide](./guides/integration.md).
+```
+
+## API Reference Format
+
+For each exported item:
+
+```markdown
+### `functionName(params): ReturnType`
+
+Brief description of what this does.
+
+**Parameters:**
+- `param1` (`Type`) — Description
+- `param2` (`Type`, optional) — Description. Defaults to `defaultValue`.
+
+**Returns:** `ReturnType` — Description
+
+**Throws:** `ErrorType` — When condition
+
+**Example:**
+\`\`\`typescript
+import { functionName } from '@repo/feature';
+
+const result = functionName({ param1: 'value' });
+\`\`\`
+```
+
+## Diagrams
+
+If the feature has complex data flow or component relationships, include a Mermaid diagram:
+
+```markdown
+\`\`\`mermaid
+graph LR
+  A[Request] --> B[Auth Middleware]
+  B --> C{Valid Session?}
+  C -->|Yes| D[Route Handler]
+  C -->|No| E[401 Response]
+\`\`\`
+```
+
+## Cross-References
+
+When referencing other packages or features:
+- Link to their docs if they exist: `[Configuration package](../config/README.md)`
+- Use the package name in backticks: `@repo/config`
+- Don't duplicate their documentation — link to it
+
+## File Naming
+
+- All lowercase with hyphens: `api-reference.md`, `getting-started.md`
+- Guides go in a `guides/` subdirectory
+- ADRs go in a `decisions/` subdirectory with format `adr-NNN-short-title.md`

package/adapters/pi/skills/forge-6-docs/references/pipeline-state-schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature Forge Pipeline State",
+  "description": "Tracks pipeline progress for a single feature across sessions. Lives at {specsDir}/{feature}/.pipeline-state.json",
+  "type": "object",
+  "required": ["feature", "createdAt", "updatedAt", "currentStage", "stages", "pipelineStatus"],
+  "properties": {
+    "pipelineStatus": {
+      "type": "string",
+      "enum": ["active", "paused", "abandoned"],
+      "default": "active"
+    },
+    "feature": {
+      "type": "string",
+      "description": "Feature name (matches directory name under specsDir)"
+    },
+    "epic": {
+      "type": "string",
+      "description": "Back-pointer to the owning epic's name. Absent for standalone features. The epic-manifest.json is canonical on conflict (REQ-STATE-01)."
+    },
+    "branch": {
+      "type": "string",
+      "description": "Git branch this feature's pipeline work is intended to land on, recorded by the Branch Setup block (shared-conventions.md) at the entry stage. Absent when the project isn't a git repo or branchPerFeature is false. Downstream stages and forge-5-loop compare the current branch against this to detect drift back onto the default branch before committing."
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "currentStage": {
+      "type": "string",
+      "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop", "forge-6-docs", "complete", "forge-verify-prd", "forge-verify-tech", "forge-verify-specs", "forge-verify-backlog", "forge-verify-impl", "forge-0-epic", "forge-verify-epic"],
+      "description": "Where the pipeline IS: the most recently started stage — its `stages[<currentStage>].status` is `in-progress` while that stage is being authored, then `complete` once its artifacts are committed. A stage skill sets this to its own id when it starts. This is deliberately NOT 'the next stage to run': the next stage is DERIVED, never stored — it is the first production stage whose `stages[].status` is not `complete` (see `next_stage()` in forge-session.py, surfaced as the navigator/doctor `nextStage`). Consumers that need 'what runs next' compute it from `stages[].status`, not from this field. `complete` here means the whole pipeline is done. (Legacy/absent value: tools fall back to the derived next stage for display only — `build_rows` in forge-session.py.)"
+    },
+    "notes": {
+      "type": "string",
+      "description": "Free-form notes persisted between sessions (user can add context before stepping away)"
+    },
+    "epicChangeRequests": {
+      "type": "array",
+      "description": "Epic-level change requests raised by a member stage (forge-1-prd/forge-2-tech) when the epic DECOMPOSITION itself must change — distinct from the same-feature `notes` parking lot. Read by forge-0-epic edit mode (which applies them) and by forge-session stage-exit (which routes the exit on `blocksCurrent`). Absent/empty for standalone features. Additive/optional: legacy states without it validate unchanged.",
+      "items": {
+        "type": "object",
+        "required": ["kind", "target", "rationale", "blocksCurrent", "raisedBy", "raisedAt", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["add-feature", "redep", "move-boundary", "split"],
+            "description": "The decomposition change. add-feature/redep map 1:1 onto edit-mode mutators; move-boundary/split are composite (applied guided-manual in v1)."
+          },
+          "target": {
+            "type": "string",
+            "description": "The sibling feature to add, or the feature/boundary affected."
+          },
+          "rationale": {
+            "type": "string",
+            "description": "Why the epic must change; seeds the edit-mode charter/prompt when applied."
+          },
+          "blocksCurrent": {
+            "type": "boolean",
+            "description": "true → the current feature's next stage would build on a soon-to-change decomposition (pause-now: reconcile before proceeding). false → a peer/downstream change (finish-then-edit). Drives stage-exit routing."
+          },
+          "raisedBy": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech"],
+            "description": "The stage that detected the epic-level concern."
+          },
+          "raisedAt": { "type": "string", "format": "date-time" },
+          "status": {
+            "type": "string",
+            "enum": ["open", "applied", "dismissed"],
+            "default": "open",
+            "description": "Lifecycle: open → applied|dismissed. Only forge-0-epic edit mode flips open→applied/dismissed; recording stages only create open entries; navigator/verify only read."
+          }
+        }
+      }
+    },
+    "deferredDecisions": {
+      "type": "array",
+      "description": "Same-feature decisions deliberately postponed to a LATER stage of THIS feature — a structured alternative to burying them in the free-text `notes` string. Distinct from `notes` (unstructured scratch) and from `epicChangeRequests[]` (the epic DECOMPOSITION must change). Use this when a stage would otherwise be tempted to solicit a decision that properly belongs to a downstream stage (e.g. forge-1-prd deferring the concrete cache backend to forge-2-tech): record it here instead of asking now (see the deferred-decisions rule in `references/stage-exit-protocol.md`), and the target stage addresses it. Additive/optional: legacy states without it validate unchanged.",
+      "items": {
+        "type": "object",
+        "required": ["question", "raisedBy", "raisedAt", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "question": {
+            "type": "string",
+            "description": "The decision being deferred, phrased as a concrete question for the target stage to answer."
+          },
+          "rationale": {
+            "type": "string",
+            "description": "Why it is deferred rather than decided now (e.g. depends on information the target stage produces)."
+          },
+          "targetStage": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog", "forge-5-loop", "forge-6-docs"],
+            "description": "The stage that should resolve this decision. Omit when unknown/any-later-stage."
+          },
+          "raisedBy": {
+            "type": "string",
+            "enum": ["forge-1-prd", "forge-2-tech", "forge-3-specs", "forge-4-backlog"],
+            "description": "The stage that deferred the decision."
+          },
+          "raisedAt": { "type": "string", "format": "date-time" },
+          "status": {
+            "type": "string",
+            "enum": ["open", "addressed", "dismissed"],
+            "default": "open",
+            "description": "Lifecycle: open → addressed|dismissed. The target stage flips open→addressed when it resolves the decision (or dismissed if it no longer applies); recording stages only create open entries."
+          }
+        }
+      }
+    },
+    "stages": {
+      "type": "object",
+      "properties": {
+        "forge-0-epic": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-epic": { "$ref": "#/definitions/verifyEntry" },
+        "forge-1-prd": { "$ref": "#/definitions/stageEntry" },
+        "forge-2-tech": { "$ref": "#/definitions/stageEntry" },
+        "forge-3-specs": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-specs": { "$ref": "#/definitions/verifyEntry" },
+        "forge-4-backlog": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-backlog": { "$ref": "#/definitions/verifyEntry" },
+        "forge-5-loop": { "$ref": "#/definitions/stageEntry" },
+        "forge-6-docs": { "$ref": "#/definitions/stageEntry" },
+        "forge-verify-impl": { "$ref": "#/definitions/verifyEntry" },
+        "forge-verify-prd": { "$ref": "#/definitions/verifyEntry" },
+        "forge-verify-tech": { "$ref": "#/definitions/verifyEntry" }
+      }
+    }
+  },
+  "definitions": {
+    "stageEntry": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "in-progress", "complete", "stale"]
+        },
+        "version": {
+          "type": "integer",
+          "description": "Incremented each time this stage's artifacts are revised"
+        },
+        "artifacts": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Relative paths to artifacts produced by this stage"
+        },
+        "startedAt": { "type": ["string", "null"], "format": "date-time" },
+        "completedAt": { "type": ["string", "null"], "format": "date-time" },
+        "commitHash": {
+          "type": ["string", "null"],
+          "description": "Git commit SHA of this stage's artifact commit (Commit 1 of the two-commit Git Commit Protocol in shared-conventions.md). Written by a small follow-up commit so it points at the artifact commit itself, never at an orphaned amend or the hash-recording commit. null until recorded (or when there was no new artifact commit)."
+        },
+        "basedOnVersions": {
+          "type": "object",
+          "description": "Upstream stage versions this artifact was built against",
+          "additionalProperties": { "type": "integer" }
+        }
+      }
+    },
+    "verifyEntry": {
+      "type": "object",
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["pending", "passed", "findings-reported", "findings-applied", "skipped"]
+        },
+        "findingsFile": {
+          "type": ["string", "null"],
+          "description": "Path to the verification findings document"
+        },
+        "findingsCount": {
+          "type": ["integer", "null"],
+          "description": "Number of findings reported"
+        },
+        "verifiedAt": { "type": ["string", "null"], "format": "date-time" },
+        "fixedAt": { "type": ["string", "null"], "format": "date-time" },
+        "commitHash": { "type": ["string", "null"], "description": "Git commit SHA of the verify/fix artifact commit. Recorded via the two-commit Git Commit Protocol (shared-conventions.md) so it points at the artifact commit, never an orphaned amend." },
+        "verifiedStageVersion": { "type": ["integer", "null"], "description": "The production stage's `version` at the moment this verify was resolved. The navigator's freshness ledger compares it to the stage's current `version`: equal means the verify is fresh; a mismatch (artifact revised since) or an absent field (legacy state) means stale, so auto-verify re-fires. Recorded by forge-verify/forge-fix when writing a passed/findings-applied status." }
+      }
+    }
+  }
+}