forgedock 1.1.1 → 1.1.3

package/docs/spec/eval-run-result.md

@@ -0,0 +1,147 @@
+# Eval Run-Result JSON Schema
+
+**Spec version**: 1.0.0
+**Stable since**: issue #1285
+
+This document defines the machine-readable JSON shapes consumed and produced by
+the ForgeDock pipeline eval harness:
+
+- **Per-run result** — one object per issue, written by the batch driver
+  (`bin/batch-runner.mjs`) after each headless `/work-on` run.
+- **Scorecard** — aggregate computed by `scripts/eval-scorecard-aggregator.mjs`
+  from an array of per-run results; consumed by the CI regression gate
+  (`scripts/eval-gate-scorecard.mjs`, issue #1286) and the publishing pipeline.
+
+---
+
+## Per-Run Result
+
+Each headless run of a single corpus issue produces one JSON object:
+
+```jsonc
+{
+  // Required fields
+  "issue": 1234,                // integer — GitHub issue number
+  "status": "success",          // "success" | "failure" | "incomplete" | "error"
+  "wallClockMs": 42000,         // integer — wall-clock duration of the run (ms)
+  "interventionCount": 0,       // integer — number of human interventions (see below)
+
+  // Optional fields (nullable — do NOT block on missing upstream data)
+  "cost": null,                 // null | number — token/USD cost; null until #1255 lands
+  "iterations": 23,             // integer — tool-use loop iteration count
+  "stopReason": "end_turn",     // string — Anthropic stop_reason or "max_iterations"
+  "error": null,                // null | string — error message when status === "error"
+  "specVersion": "1.0.21",      // string — forgedock package version at run time
+  "model": "claude-sonnet-4-5", // string — model used for the run
+  "runAt": "2026-07-04T00:00:00.000Z" // ISO-8601 timestamp
+}
+```
+
+### `status` values
+
+| Value        | Meaning                                                                      |
+|--------------|------------------------------------------------------------------------------|
+| `success`    | Run completed; the issue reached `workflow:merged` or equivalent terminal state |
+| `failure`    | Run completed but the issue did not reach a terminal success state           |
+| `incomplete` | Run stopped due to `max_tokens` or `max_iterations` — result is unreliable  |
+| `error`      | The runner threw an unhandled exception (network, API, crash)                |
+
+### `interventionCount` definition
+
+A human intervention is counted when **any** of the following occur during a run:
+
+1. The `needs-human` label is applied to the issue by the pipeline.
+2. A manual `gh` command is executed outside the automated runner loop.
+3. A FORGE annotation comment is posted by a human (not the bot account) during the run window.
+
+Runs where no human interaction occurs have `interventionCount: 0`.
+
+---
+
+## Batch Driver Output File
+
+`bin/batch-runner.mjs` writes a JSON object containing the per-run array plus
+top-level metadata:
+
+```jsonc
+{
+  "corpus_version": "v1",        // string | null — corpus version label
+  "spec_version": "1.0.21",      // string | null — forgedock version at run time
+  "model": "claude-sonnet-4-5",  // string | null — model used
+  "generated_at": "2026-07-04T00:00:00.000Z",
+  "runs": [ ...PerRunResult ]
+}
+```
+
+---
+
+## Corpus File
+
+The batch driver accepts a corpus file (JSON) listing issues to run:
+
+```jsonc
+{
+  "corpus_version": "v1",        // string — semver or label for the corpus snapshot
+  "run_id": "run-2026-07-04-1",  // string — optional unique run identifier
+  "run_mode": "full",            // "full" | "subset" — passed through to scorecard
+  "spec_sha": "abc123",          // string | null — git SHA of commands/ at run time
+  "issues": [1001, 1002, 1003]   // integer[] — GitHub issue numbers
+}
+```
+
+---
+
+## Scorecard
+
+`scripts/eval-scorecard-aggregator.mjs` reads the batch driver output and emits
+a scorecard in the format consumed by `scripts/eval-gate-scorecard.mjs` (#1286):
+
+```jsonc
+{
+  "schema_version": "1",          // string — always "1" (schema identifier)
+  "run_id": "run-2026-07-04-1",   // string | null — from corpus metadata
+  "generated_at": "2026-07-04T00:00:00.000Z",
+  "corpus_size": 20,              // integer — from corpus metadata (defaults to issues_run)
+  "issues_run": 20,               // integer — total runs in the input
+  "successful_runs": 17,          // integer — runs with status === "success"
+  "failed_runs": 2,               // integer — runs with status === "failure"
+  "success_rate_pct": 85,         // number [0,100] — successful_runs / issues_run * 100 (2dp)
+  "mean_wall_clock_ms": 38200,    // number | null — arithmetic mean wall-clock
+  "median_wall_clock_ms": 35000,  // number | null — median wall-clock
+  "total_intervention_count": 1,  // integer — sum of interventionCount across all runs
+  "cost": null,                   // null | number — sum of per-run cost; null if any run has cost: null
+  "run_mode": "full",             // "full" | "subset"
+  "spec_sha": "abc123"            // string | null — git SHA of commands/ at run time
+}
+```
+
+**Important**: `incomplete` and `error` status runs count against `success_rate_pct`
+(they reduce `issues_run` denominator's numerator). This ensures the gate catches
+hangs and crashes, not just logic failures.
+
+### Methodology rules (enforced by the scorecard aggregator)
+
+1. **Minimum sample size**: fewer than `MIN_RUNS` (currently **5**) scoreable
+   (`success` or `failure`) runs causes the aggregator to exit non-zero rather
+   than emit a misleading rate. Mirrors `bench-scorecard.mjs`'s `MIN_RUNS` rule.
+2. **Malformed input**: missing required fields (`issue`, `status`,
+   `wallClockMs`, `interventionCount`) or non-integer/non-string values cause
+   exit code 1 (validation error).
+3. **Cost is nullable**: if any run has `cost: null`, the scorecard's
+   `cost` is `null`. The field becomes numeric only when every run reports a
+   real cost value (post-#1255).
+4. **Rate consistency**: `success_rate_pct` is always computed as
+   `round(successful_runs / issues_run * 100, 2)`. The CI gate (#1286) validates
+   this computed value matches the reported value.
+
+---
+
+## Stability contract
+
+- Field names are stable. New **optional** fields may be added at any time
+  without a version bump.
+- Removing or renaming a field is a breaking change and requires a spec version
+  bump and a GitHub issue.
+- Consumers **must** treat unknown fields as ignorable (forward-compatibility).
+- The CI gate sub-issue (#1286) and publishing sub-issue (#1287) may depend on
+  this schema without waiting for upstream changes.

package/docs/spec/forge-protocol-v1.md

@@ -453,6 +453,15 @@ artifact so a sub-issue builder can fetch upstream context directly.
 
 These markers carry no Markdown body; their presence is the signal.
 
+**Phase boundary markers** (appear in pipeline command specs):
+
+| Marker | Meaning |
+|--------|---------|
+| `<!-- FORGE:DISPATCHER — {desc} -->` | Marks the Universal Phase Dispatcher — the single source of truth for phase transitions and routing logic |
+| `<!-- FORGE:PHASE_COMPLETE — {desc} -->` | Inter-phase boundary; documents that a phase completed and names the next phase so agents do not treat an intermediate result as terminal |
+
+**Issue-comment control markers** (posted to issue comments):
+
 | Marker | Meaning |
 |--------|---------|
 | `<!-- FORGE:REVIEW_STARTED -->` | The review phase has been invoked for this issue |
@@ -466,6 +475,255 @@ needed.
 
 ---
 
+### 4.4 Design pipeline annotations
+
+These annotations drive the UI Taste Harness — the design-generation pipeline
+that produces a landing page from a design-blind product brief. They carry
+design intent across the investigate → architect → generate → critique → close
+stages, exactly as the lifecycle annotations carry code context across
+investigate → build → review.
+
+#### `FORGE:DESIGN_CONTEXT`
+
+- **Written by**: the `/design` design-investigate stage
+- **Read by**: design-architect stage (grounds the rationale), close phase (audit trail)
+- **Completion sentinel**: `<!-- FORGE:DESIGN_CONTEXT:COMPLETE -->`
+
+The design analog of `FORGE:CONTEXT`: the parsed brief (message / audience /
+single objection), the grammar pulled from the reference corpus, and the recent
+signature moves / archetypes / palettes from design-memory that this design must
+diverge from. Opens the `FORGE:DESIGN_*` chain.
+
+```
+<!-- FORGE:DESIGN_CONTEXT -->
+## Design Context — {product}
+
+**Message:** {one thing the page must say}
+**Audience / objection:** {who} — must overcome: {objection}
+**Corpus grammar:** {relevant traits / archetype priors}
+**Diverge from (memory):** {recent signature moves / archetypes / palettes to avoid}
+<!-- FORGE:DESIGN_CONTEXT:COMPLETE -->
+```
+
+#### `FORGE:DESIGN_RATIONALE`
+
+- **Written by**: the design-architect agent
+- **Read by**: the generate agent (the spec it produces), the render → vision-critique loop, and reviewers
+- **Emitted**: before `FORGE:DESIGN_SPEC`
+
+The designer's diary — the reasoning-before-generation step. Captures a
+seven-element chain of thought (intent/feeling, audience/objection,
+communication hierarchy, direction + rejected alternatives, signature move,
+what's being tried this time, non-goals). MUST carry at least one explicitly
+rejected alternative, a named signature move, and a `→ Produces DESIGN_SPEC`
+link.
+
+```
+<!-- FORGE:DESIGN_RATIONALE -->
+## Design Rationale — {product}
+
+**Intent / feeling:** {one message} · {one feeling}
+**Audience / objection:** {who} — must overcome: {objection}
+**Communication hierarchy:** 1) {…} 2) {…} 3) {…}
+**Direction:** {archetype} — because {reasoning}
+  - Considered & rejected: {alt A} (because {…}); {alt B} (because {…})
+**Signature move:** {the one non-obvious idea}
+**Trying this time:** {technique/learning} (from memory: avoiding {prior move})
+**Non-goals:** {what this won't do}
+
+→ Produces DESIGN_SPEC: {link}
+```
+
+#### `FORGE:DESIGN_CANDIDATES`
+
+- **Written by**: the generate agent (divergent-generation step)
+- **Read by**: the taste-judge (selects the winner), close phase (audit trail), design-memory (to diverge from past winners)
+- **Emitted**: after `FORGE:DESIGN_RATIONALE`, before `FORGE:DESIGN_SPEC`
+
+The variance lever's audit record: the one committed archetype (never blended),
+the N distinct directions generated within it, and the independent taste-judge's
+scores and selection. The selection judge is distinct from the critique loop —
+anti-Goodhart.
+
+```
+<!-- FORGE:DESIGN_CANDIDATES -->
+## Design Candidates — {product}
+
+**Archetype (committed):** {one of the corpus ids}
+**Directions:**
+1. {concept} — signature: {move} — {distinguishing grammar/tokens}
+2. {concept} — signature: {move} — {…}
+**Judge scores:** 1) {score} 2) {score} …
+**Selected:** #{n} — because {reason}
+
+→ Winner produces DESIGN_SPEC: {link}
+```
+
+#### `FORGE:DESIGN_SPEC`
+
+- **Written by**: the design-architect agent
+- **Read by**: the generate agent (constrains output), the deterministic anti-slop linter, the render → vision-critique loop, and the close phase agent
+
+A structured, machine-checkable representation of one page's design language.
+Produced by `FORGE:DESIGN_RATIONALE` — not authored from nowhere. The flow is
+rationale → spec → page. Full field-by-field schema lives in
+`docs/design/design-spec-schema.md`.
+
+````
+<!-- FORGE:DESIGN_SPEC -->
+## Design Spec — {product}
+
+```jsonc
+{
+  "meta":          { "product": "…", "archetype": "…", "corpus_version": "…", "rationale_ref": "…" },
+  "typography":    { "display_family": "…", "body_family": "…", "scale_ratio": …, "weights": […] },
+  "color":         { "mode": "…", "background": "#…", "foreground": "#…", "accent": "#…",
+                     "rules": ["no-default-tailwind-palette", "contrast>=4.5"] },
+  "spacing":       { "base_unit_px": …, "scale": […] },
+  "radius":        { "scale": […] },
+  "shadow":        { "tokens": […] },
+  "motion":        { "vocabulary": […], "reduced_motion": "required" },
+  "layout_grammar":{ "sections": [ { "id": "…", "purpose": "…", "density": "…" } ], "rhythm": "…" },
+  "effects_plan":  { "per_section": [ … ], "budget": { … }, "never": [ … ] },
+  "negatives":     [ … ],
+  "acceptance":    { "perf_budget": { … }, "a11y": { … }, "divergence_ref": "…" }
+}
+```
+
+→ Produced by FORGE:DESIGN_RATIONALE: {link}
+````
+
+#### `FORGE:CRITIQUE`
+
+- **Written by**: the vision-critique loop (one annotation per iteration)
+- **Read by**: the iterate step (consumes its findings), close phase (improvement trajectory audit)
+- **Completion sentinel**: `<!-- FORGE:CRITIQUE:COMPLETE -->`
+
+One annotation per render → critique iteration — the page's improvement
+trajectory as an auditable trail. Records the deterministic lint floor result,
+the desktop+mobile render, the perceptual findings, and the verdict. The critic
+is strictly independent from the benchmark judge — anti-Goodhart.
+
+```
+<!-- FORGE:CRITIQUE -->
+## Critique — {product} · iteration {i}/{max}
+
+**Lint floor:** {PASS | fixed N hard findings}
+**Render:** desktop + mobile captured
+**Perceptual findings:**
+- N{n}: {what was observed in the render} → {correction}
+**Verdict:** {PASS | ITERATE | BUDGET-EXHAUSTED}
+<!-- FORGE:CRITIQUE:COMPLETE -->
+```
+
+#### `FORGE:USER_FEEDBACK`
+
+- **Written by**: the `/design` user-feedback stage
+- **Read by**: the surgical re-generation step, close phase (audit trail)
+- **Completion sentinel**: `<!-- FORGE:USER_FEEDBACK:COMPLETE -->`
+- **Not produced** in automated (benchmark) runs
+
+The structured record of one user-feedback round. There MAY be multiple
+`FORGE:USER_FEEDBACK` annotations on a single issue if the user iterates.
+`FORGE:USER_FEEDBACK` MAY modify a section's visual execution but MUST NOT
+change the committed `meta.archetype` or the signature move from
+`FORGE:DESIGN_RATIONALE` — those choices are locked once the spec is committed.
+
+```
+<!-- FORGE:USER_FEEDBACK -->
+## User Feedback — {product} · round {n}
+
+**Section target:** {section ID from layout_grammar.sections, or "all" for page-wide feedback}
+**Feedback type:** {asset | emotion | direction | freeform}
+**Asset URL:** {URL or "none"}
+**Modification:** {structured description of what to change}
+**Emotion target:** {trust | speed | power | craft | play | unchanged}
+**Satisfied:** {yes | no — "no" loops back after re-generation}
+**Freeform notes:** {verbatim user input not captured in the structured fields}
+<!-- FORGE:USER_FEEDBACK:COMPLETE -->
+```
+
+#### `FORGE:BENCH_SCORECARD`
+
+- **Written by**: the `/design-bench` benchmark rig
+- **Read by**: harness developers (fitness signal), milestone tracker, pipeline-health
+- **Completion sentinel**: `<!-- FORGE:BENCH_SCORECARD:COMPLETE -->`
+
+The result of one ABC benchmark run. Arm A is the harness output, arm B is a
+raw one-shot model, arm C is the real reference page (gold standard). The
+annotation carries win-rates, the A-vs-B harness delta, rubric distributions
+(mean + stdev) across n≥3 runs, mean slop counts, and a judge-calibration check
+(C must beat A and B — otherwise the judge is miscalibrated).
+
+````
+<!-- FORGE:BENCH_SCORECARD -->
+## ABC Benchmark Scorecard
+
+**Corpus version**: {ver} · **Generation model (A & B)**: {model} · **Judge model**: {independent judge}
+**Products**: {n_products} · **Runs/product**: {n}
+
+| Arm | Win-rate vs C | A-vs-B | Mean slop |
+|-----|---------------|--------|-----------|
+| A   | {wr}          | {a_vs_b} | {slop_A} |
+| B   | {wr}          | —        | {slop_B} |
+
+**Judge calibration**: {ok | MISCALIBRATED — N runs where C lost (suspect)}
+
+```json
+{scorecard.json from bench-scorecard.mjs}
+```
+
+<!-- FORGE:BENCH_SCORECARD:COMPLETE -->
+````
+
+#### `FORGE:DESIGN_SHIPPED`
+
+- **Written by**: the `/design` design-close stage
+- **Read by**: design-memory (persists the realized outcome), milestone tracker, pipeline-health
+- **Completion sentinel**: `<!-- FORGE:DESIGN_SHIPPED:COMPLETE -->`
+- **Terminal annotation** for the design pipeline (analogous to `workflow:merged` for code)
+
+Closes the design pipeline. Posted only when the design passes the full
+definition of done — critique-rubric threshold, perf budget, a11y check, and
+the divergence check. Records the final realized outcome written to design-memory
+so the next design can diverge from it.
+
+```
+<!-- FORGE:DESIGN_SHIPPED -->
+## Design Shipped — {product}
+
+**Archetype:** {committed id} · **Signature move:** {the hook}
+**Gates:** rubric {pass} · perf {pass} · a11y {pass} · divergence {distinct from prior}
+**Critique iterations:** {n}
+**Written to memory:** {palette/type/effects/learnings summary}
+<!-- FORGE:DESIGN_SHIPPED:COMPLETE -->
+```
+
+---
+
+### 4.5 Audit annotations
+
+These annotations are posted to issue or PR comments by audit commands
+(`/audit`, `/audit-agents`, `/security-audit`) after running structured code
+audits.
+
+#### `FORGE:AUDIT`
+
+- **Written by**: audit command agents (`/audit`, `/audit-agents`)
+- **Location**: issue or PR comment
+
+Posted after running a structured code or agent audit. Body content varies by
+audit type.
+
+#### `FORGE:SECURITY_AUDIT`
+
+- **Written by**: the `/security-audit` command
+- **Location**: issue comment
+
+Posted after completing a 4-phase security posture audit.
+
+---
+
 ## 5. The Context Chain
 
 Lifecycle annotations form an ordered chain. Each stage reads the outputs of all
@@ -512,22 +770,11 @@ Annotations record *what happened*; labels record *where a unit of work is* so a
 consumer can determine the current stage without reading every comment. The
 protocol reserves the `workflow:` label namespace:
 
-| Label | Meaning |
-|-------|---------|
-| `workflow:investigating` | Investigation in progress |
-| `workflow:ready-to-build` | Investigation complete, build not started |
-| `workflow:building` | Build in progress |
-| `workflow:in-review` | Pull request open, review active |
-| `workflow:merged` | Pull request merged, work item closed |
-| `workflow:invalid` | Closed as invalid |
-| `workflow:decomposed` | Split into sub-issues |
-| `needs-human` | Blocked; human intervention required |
-
-**Terminal labels** (processing stops when any is set): `workflow:merged`,
-`workflow:invalid`, `workflow:decomposed`, `needs-human`.
-
-Labels and annotations are complementary: labels give a fast state lookup,
-annotations give the full context behind that state.
+> **Canonical reference**: [`docs/spec/label-state-machine.md`](label-state-machine.md)
+>
+> The full state table, transition diagram, terminal labels, and label-exclusivity
+> pattern are defined there. Labels and annotations are complementary: labels give
+> a fast state lookup, annotations give the full context behind that state.
 
 ---
 
@@ -739,7 +986,141 @@ which tool or model produced it — interoperates with this consumer unchanged.
 
 ---
 
-## 10. Versioning
+## 10. Nested-Command Decomposition Pattern
+
+Large command specs that grow past ~50 KB become expensive to load in full on
+every invocation, even when a given run only exercises a fraction of the spec's
+surface. The **nested-command decomposition pattern** addresses this by splitting
+a large spec into a top-level file and one or more supporting sub-files in a
+subdirectory of the same name.
+
+### 10.1 When to decompose
+
+Decompose a command spec into a `commands/<name>/` directory when **any two** of
+the following are true:
+
+- The spec file exceeds **~30 KB** (token budget becomes significant).
+- The spec has **two or more separable sub-phases** that are only reached along
+  specific execution paths (e.g., a build phase that is skipped for trivial
+  tasks).
+- The spec delegates to **distinct named skill scopes** (e.g.,
+  `work-on:build:context`, `work-on:build:architect`) that have their own
+  input/output contracts.
+- The spec is invoked by other commands that benefit from loading only a subset
+  of its logic (e.g., `orchestrate` spawns `work-on` but only needs its outer
+  routing logic, not every inline sub-phase).
+
+Do **not** decompose for organizational preference alone. Every subdirectory
+adds a graph node and must be maintained when the parent spec changes. If a spec
+is small and its phases are always executed together, keep it as a single file.
+
+### 10.2 Naming convention
+
+```
+commands/
+  work-on.md              ← top-level entry point (dispatcher + universal rules)
+  work-on/                ← sub-specs, same name as the top-level file
+    build.md              ← sub-command (invocable as work-on:build)
+    build/                ← sub-sub-specs for build
+      context.md
+      architect.md
+      implement.md
+      validate.md
+    investigate.md
+    review.md
+    close.md
+    decompose.md
+```
+
+Rules:
+- The subdirectory name **MUST** match the stem of the top-level spec file
+  (e.g., `work-on.md` → `work-on/`).
+- Sub-files are named after the sub-phase they implement (lowercase,
+  hyphenated). They are invocable as `<parent>:<sub-file-stem>` via the Skill
+  tool (e.g., `Skill(skill="work-on:build:context", ...)`).
+- Sub-files that go to depth 3 (e.g., `work-on/build/context.md`) follow the
+  same pattern recursively: their subdirectory is `work-on/build/context/` if
+  further decomposition is ever needed.
+
+### 10.3 Automatic pick-up by the installer and graph
+
+No manual registration is required. Two mechanisms pick up sub-files
+automatically:
+
+**Installer (`bin/forgedock.mjs`)**: The `findMarkdownFiles()` helper performs a
+recursive directory walk over `commands/` (skipping `node_modules` and
+dot-directories). Every `.md` file discovered — at any depth — is symlinked into
+`~/.claude/commands/` at the same relative path. A file at
+`commands/work-on/build/context.md` is installed as
+`~/.claude/commands/work-on/build/context.md`, making it reachable by Claude
+Code's Skill resolver as `work-on:build:context`.
+
+**Spec graph builder (`scripts/build-spec-graph.mjs`)**: The `walk()` function
+in the builder performs the same recursive directory walk over `commands/`,
+discovering all spec files regardless of nesting depth. Each discovered file
+becomes a graph node. The `load-set` query uses `CONTAINS` edges (written when a
+parent spec references a sub-spec via `Skill()`) to resolve the minimal spec set
+for a given entry command.
+
+### 10.4 Token-saving effect
+
+Because the installer symlinks sub-specs at their actual nested paths, Claude
+Code's selective spec loading (Phase 0 of `/work-on`) can load each sub-spec
+only when execution reaches that sub-phase — skipped sub-phases contribute zero
+tokens to the session context. The spec knowledge graph's `load-set` query
+computes the minimal reachable set from the entry command, excluding sub-specs
+that are never reached by that command's execution graph.
+
+The measured token savings from decomposing `/work-on` and applying
+`load-set`-driven selective loading are documented in
+`docs/articles/command-decomposition-token-savings.md`. The same methodology
+can be applied to any command spec that meets the decomposition criteria in
+Section 10.1.
+
+---
+
+## 11. Adopting FORGE in Your Own Pipeline <!-- renumbered from §10 -->
+
+FORGE is an open format. Any tool that can read and write platform comments can
+participate — no dependency on a specific framework, model, or vendor.
+
+**Minimum viable adoption**:
+
+1. Pick the annotation types relevant to your pipeline (`FORGE:INVESTIGATOR` +
+   `FORGE:BUILDER` is a good starting point).
+2. Write your agent prompts to post annotated comments after each phase.
+3. Write downstream agent prompts to read those comments before starting.
+
+**Implementation checklist**:
+
+1. **Read existing annotations** before starting work on an issue:
+
+   ```bash
+   gh api repos/{OWNER}/{REPO}/issues/{NUMBER}/comments \
+     --jq '.[] | select(.body | contains("FORGE:")) | {id: .id, body: .body}'
+   ```
+
+2. **Write annotations** using the schemas in Section 4 after completing each phase.
+
+3. **Check for existing annotations** before writing (idempotency):
+
+   ```bash
+   EXISTING=$(gh api repos/{OWNER}/{REPO}/issues/{NUMBER}/comments \
+     --jq '.[] | select(
+       .body | (contains("FORGE:INVESTIGATOR") and contains("INVESTIGATION:COMPLETE"))
+     ) | .id')
+   if [ -n "$EXISTING" ]; then echo "Already investigated — skip"; fi
+   ```
+
+4. **Respect label state** — check `workflow:*` labels (Section 6) to determine
+   the current phase and whether the work item is in a terminal state.
+
+5. **Use text-contains filtering** as the primary query interface. All FORGE
+   implementations can assume `gh api` or equivalent is available.
+
+---
+
+## 12. Versioning
 
 This document specifies **version 1.0**.
 
@@ -754,7 +1135,36 @@ Annotations do not carry an explicit version field. Conforming consumers
 
 ---
 
-## 11. Acknowledgements
+## 13. Reference Implementation
+
+The canonical reference implementation of this specification is published as a
+separate, MIT-licensed npm package:
+
+**`@forgedock/protocol`** — available at `packages/protocol/` in the ForgeDock
+repository.
+
+It provides:
+
+- `parse(commentBody)` — extracts all annotations from a comment body string
+- `validate(annotation)` — checks conformance per §3–4; returns `{ valid, errors, warnings }`
+- `emit(type, fields)` — produces well-formed annotation strings
+- `emitPartial(type)` — produces the partial sentinel for a type (§3.3)
+
+A conformance suite in `packages/protocol/fixtures/` covers all 13 reserved
+types with valid and invalid examples. The CLI runner can be invoked against any
+fixtures directory:
+
+```bash
+npx @forgedock/protocol fixtures/
+```
+
+**Library version and spec version move together**: a library at version `1.x`
+implements spec version 1.0. Breaking spec changes (§11, major revisions)
+require a library major version bump.
+
+---
+
+## 14. Acknowledgements
 
 The FORGE Annotation Protocol was first developed and proven in a production
 autonomous-development pipeline, where it coordinated investigator, builder,
@@ -762,6 +1172,19 @@ and reviewer agents across tens of thousands of issues. This specification
 generalizes that wire format into a tool-neutral, openly licensed standard so
 that any agent pipeline can adopt and interoperate with it.
 
+### Conformance note — Codex adapter (second implementation)
+
+The Codex-native adapter (`.agents/skills/*/SKILL.md` in the ForgeDock
+repository) constitutes a second independent implementation of this protocol.
+It reads the same `commands/*.md` workflow specs and produces/consumes FORGE
+annotations through a different runtime (different tool calls, different
+worktree paths, different repo-resolution conventions) than the Claude Code
+path. Both implementations have been validated against
+`scripts/conformance-check.mjs`, the repository's automated conformance suite
+for this specification. This provides concrete evidence of vendor neutrality —
+the wire format is not incidentally compatible with one runtime; it functions
+as designed across distinct agent frameworks.
+
 ---
 
 *FORGE Annotation Protocol v1.0 — released under