@cassiomc1/forgeloop 1.5.0 → 1.6.0

package/docs/CLI_REFERENCE.md

@@ -39,11 +39,12 @@ ForgeLoop uses a definition-driven command-line parser:
 
 | Category | Commands |
 | --- | --- |
-| **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`doctor`](#doctor), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
+| **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`doctor`](#doctor), [`metrics`](#metrics), [`eval`](#eval), [`history`](#history), [`trace`](#trace), [`reflect`](#reflect), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
 | **Setup & Maintenance** | [`init`](#init), [`update`](#update), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock), [`task-recover`](#task-recover), [`task-repair-legacy-recovery`](#task-repair-legacy-recovery), [`task-resume`](#task-resume) |
-| **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`reconcile-closure`](#reconcile-closure), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-lock-status`](#task-lock-status), [`task-scope`](#task-scope) |
+| **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-intervention`](#record-intervention), [`record-hypothesis-disposition`](#record-hypothesis-disposition), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`reconcile-closure`](#reconcile-closure), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-lock-status`](#task-lock-status), [`task-scope`](#task-scope) |
 | **Cross-Harness Continuity** | [`continuity`](#continuity), [`record-continuity`](#record-continuity), [`reconcile-continuity`](#reconcile-continuity), [`clear-continuity`](#clear-continuity) |
 | **Verification & Completion** | [`prepare-completion`](#prepare-completion), [`run-check`](#run-check), [`record-check`](#record-check), [`record-terminal-result`](#record-terminal-result), [`audit`](#audit), [`report`](#report), [`validate-receipt`](#validate-receipt) |
+| **Durable Actions & Approvals** | [`run-action`](#run-action), [`action-propose`](#action-propose), [`action-record`](#action-record), [`action-show`](#action-show), [`action-reconcile`](#action-reconcile), [`action-verify`](#action-verify), [`action-authorize`](#action-authorize), [`approval-request`](#approval-request), [`approval-resolve`](#approval-resolve) |
 | **Policy & Auditing** | [`policy`](#policy), [`policy-discover`](#policy-discover), [`policy-status`](#policy-status), [`policy-diff`](#policy-diff), [`rule-verify`](#rule-verify), [`baseline`](#baseline), [`bundle`](#bundle) |
 
 <!-- END FORGELOOP GENERATED: cli-command-index -->
@@ -52,6 +53,163 @@ ForgeLoop uses a definition-driven command-line parser:
 
 ## 1. Setup & Maintenance
 
+## Durable Actions, Approvals, and Trajectory
+
+ForgeLoop is still a protocol/evidence layer, not an agent runtime. Use
+`COMMIT_UNKNOWN` as a hard stop: do not retry until an external observation is
+recorded with `action-reconcile`. `run-action` has no shell mode and executes
+only exact argv. Caller-reported and externally observed provenance are not host authority, and a project capability policy cannot mint host authority.
+
+### `run-action`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:run-action:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--action <id>`: stable durable action ID
+- `--capability <capability>`: canonical action capability
+- `--effect-class <class>`: durable action effect class
+- `--target <target>`: bounded external action target
+- `--idempotency-key <key>`: immutable logical action idempotency key
+- `--requirement <id>`: bound completion requirement
+- `--required-for-completion`: mark the action as required for completion
+- `--approval <id>`: current fingerprint-bound approval
+- `--timeout-ms <number>`: maximum command duration before termination
+- `-- <argv...>`: exact command argv; shell mode is never used
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:run-action:options -->
+
+### `action-propose`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-propose:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--id <id>`: stable action ID
+- `--capability <capability>`: canonical capability
+- `--effect-class <class>`: effect class
+- `--target <target>`: bounded action target
+- `--operation <text>`: bounded operation description
+- `--idempotency-key <key>`: logical action idempotency key
+- `--requirement <id>`: bound requirement
+- `--required-for-completion`: mark required for completion
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-propose:options -->
+
+### `action-record`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-record:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--action <id>`: durable action ID
+- `--state <state>`: next canonical action state
+- `--provenance <value>`: CALLER_REPORTED or EXTERNAL_OBSERVED
+- `--evidence-ref <ref>`: bounded external evidence reference
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-record:options -->
+
+### `action-show`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-show:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--action <id>`: durable action ID
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-show:options -->
+
+### `action-verify`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-verify:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--action <id>`: durable action ID
+- `--evidence <ref>`: canonical execution or check reference proving the postcondition
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-verify:options -->
+
+### `action-authorize`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-authorize:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--action <id>`: durable action ID
+- `--approval <id>`: current fingerprint-bound approval
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-authorize:options -->
+
+### `action-reconcile`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:action-reconcile:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--action <id>`: ambiguous durable action ID
+- `--outcome <outcome>`: externally observed reconciliation outcome
+- `--evidence-ref <ref>`: bounded external evidence reference (repeatable)
+- `--observed-at <timestamp>`: external observation timestamp
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:action-reconcile:options -->
+
+### `metrics`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:metrics:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit trajectory metrics as JSON
+
+<!-- END FORGELOOP GENERATED: cli:metrics:options -->
+
+### `eval`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:eval:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--scenario <path>`: project-local trajectory scenario JSON
+- `--json`: emit evaluation as JSON
+
+<!-- END FORGELOOP GENERATED: cli:eval:options -->
+
+### `approval-request`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:approval-request:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--approval <id>`: approval artifact ID
+- `--action <id>`: bound action ID
+- `--reason <text>`: bounded approval reason
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:approval-request:options -->
+
+### `approval-resolve`
+
+<!-- BEGIN FORGELOOP GENERATED: cli:approval-resolve:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--approval <id>`: approval artifact ID
+- `--decision <decision>`: approval decision
+- `--authority <kind>`: CALLER_ACKNOWLEDGED or HOST_ATTESTED
+- `--host-grant-ref <ref>`: host boundary grant reference
+- `--reason <text>`: bounded resolution reason
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:approval-resolve:options -->
+
 ### `protocol-info`
 
 Reports the public compatibility handshake required by external ForgeLoop harnesses.
@@ -496,6 +654,7 @@ Records an append-only diagnosis event in the lifecycle event ledger for the act
 
 - `--path <directory>`: target project directory (default: current directory)
 - `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--file <path>`: structured diagnostic case JSON file (mutually exclusive with legacy diagnosis fields)
 - `--hypothesis <text>`: specific root-cause hypothesis explaining the verification failure
 - `--failure-class <class>`: canonical failure class taxonomy
 - `--evidence-ref <check-id>`: reference to failed/blocked check from current cycle (repeatable)
@@ -516,6 +675,63 @@ Records an append-only diagnosis event in the lifecycle event ledger for the act
     --next-safe-action="Adjust offset +1 in slice.js"
   ```
 
+### `record-intervention`
+
+Records an append-only intervention bound to hypotheses; the described change is never executed by ForgeLoop.
+
+- **Purpose**: Records corrective or experimental changes (code, config, tests, instrumentation) associated with one or more hypotheses.
+- **When to use**: In `CORRECTING` phase after a structured diagnostic case has been recorded.
+- **Mutation**: Appends `INTERVENTION_RECORDED` to event ledger.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:record-intervention:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--file <path>`: intervention JSON file describing the recorded change (never executed)
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:record-intervention:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop record-intervention --task checkout --file intervention.json --json
+  ```
+
+### `record-hypothesis-disposition`
+
+Records an evidence-bound hypothesis disposition update in the lifecycle event ledger.
+
+- **Purpose**: Updates hypothesis status (SUPPORTED, WEAKENED, FALSIFIED, SUPERSEDED, UNRESOLVED) based on recorded evidence.
+- **When to use**: After new verification evidence resolves an open hypothesis.
+- **Mutation**: Appends `HYPOTHESIS_DISPOSITION_RECORDED` to event ledger.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:record-hypothesis-disposition:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--hypothesis <id>`: existing hypothesis ID to disposition
+- `--status <status>`: SUPPORTED, WEAKENED, FALSIFIED, SUPERSEDED, or UNRESOLVED
+- `--evidence-ref <check-id>`: check ID supporting this disposition (repeatable)
+- `--reason <text>`: evidence-bound reason for the disposition
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:record-hypothesis-disposition:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop record-hypothesis-disposition \
+    --task checkout \
+    --hypothesis h-timeout-latency \
+    --status SUPPORTED \
+    --evidence-ref checkout-tests \
+    --reason "Instrumented dependency time exceeded the timeout." \
+    --json
+  ```
+
 ### `validate-state`
 
 Validates `.forgeloop/task-state/<taskKey>/work-state.json` structure, hash chain, and repository binding.
@@ -821,7 +1037,7 @@ Displays human-readable or structured summary of current task state.
 
 ### `inspect`
 
-Inspects checkout changes and compares them against contract deliverables.
+Inspects checkout changes and compares them against contract deliverables. With `--task <id>`, human output renders a task inspection report (phase, cycle, ledger/snapshot health, progress, verification attempts, diagnostics, failure surface, signals, next command); `--json` keeps the full additive `taskInspection` section.
 
 - **Purpose**: Shows modified files, untracked files, and deliverable coverage.
 - **Mutation**: Read-only.
@@ -842,6 +1058,81 @@ Inspects checkout changes and compares them against contract deliverables.
   forgeloop inspect --json
   ```
 
+### `history`
+
+Shows chronological protocol history reconstructed from canonical ForgeLoop state.
+
+- **Purpose**: Answers "what happened during this task?" with deterministic, read-only reconstruction from the event ledger.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:history:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--type <list>`: comma-separated event types or categories to include
+- `--phase <list>`: comma-separated lifecycle phases to include
+- `--failures`: show only failed/blocked verification events
+- `--checks`: show only verification events
+- `--since <timestamp>`: include events at or after this timestamp
+- `--until <timestamp>`: include events at or before this timestamp
+- `--limit <number>`: show only the last N events after filtering
+- `--compact`: one line per event
+- `--verbose`: show full event data
+- `--json`: emit structured history output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:history:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop history --task auth-feature --json
+  ```
+
+### `trace`
+
+Emits detailed structured task trace with provenance and artifact relationships.
+
+- **Purpose**: Machine-readable protocol reconstruction consumed by history, reflect, task-level inspect, and external integrations.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:trace:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit structured trace output as JSON (default rendering is a summary)
+
+<!-- END FORGELOOP GENERATED: cli:trace:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop trace --task auth-feature --json
+  ```
+
+### `reflect`
+
+Analyzes diagnostic and correction history deterministically for information gain, repeated failures, ineffective interventions, and oscillation.
+
+- **Purpose**: Whole-task retrospective that reports whether the run actually learned anything, without calling an LLM.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:reflect:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--json`: emit structured reflection output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:reflect:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop reflect --task auth-feature --json
+  ```
+
 ### `policy`
 
 Evaluates compliance against a named policy pack.

package/docs/DIAGNOSTIC_MODEL.md

@@ -0,0 +1,181 @@
+# ForgeLoop Diagnostic Model
+
+Canonical reference for structured diagnostic cases, interventions, and hypothesis dispositions (ForgeLoop 1.6.0+, Protocol v1 additive).
+
+## Principles
+
+1. **Observation is not hypothesis.** Observations are bounded statements grounded in recorded evidence. Hypotheses are falsifiable claims that may explain observations.
+2. **Hypothesis is not proof.** Statuses are `OPEN`, `SUPPORTED`, `WEAKENED`, `FALSIFIED`, `SUPERSEDED`, `UNRESOLVED`. ForgeLoop never emits `ROOT_CAUSE_CONFIRMED` or similar.
+3. **Append-only truth.** Diagnostic revisions are never rewritten; the ledger records evolving understanding.
+4. **Diagnostic prose is metadata.** Statements, settlement predicates, and next-safe-action text are never executed by ForgeLoop.
+
+## Structured diagnostic case
+
+One diagnostic revision for one verification cycle, recorded with:
+
+```bash
+forgeloop record-diagnosis --task <id> --file diagnostic-case.json --json
+```
+
+Legacy flag-based `record-diagnosis` syntax remains valid; both forms cannot be combined.
+
+Schema: `schemas/diagnostic-case.schema.json`. Bounded limits: 64 observations, 64 contributors, 32 hypotheses per case; statements up to 4096 characters; IDs match `^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`.
+
+### Semantic fingerprint
+
+`diagnosticFingerprint` hashes the canonicalized semantic content (cycle, failure class, observations/contributors/hypotheses semantics, next-safe action). Whitespace, key ordering, unordered reference arrays, and object IDs are excluded. Re-recording a semantically identical case is idempotent.
+
+### Revisions
+
+`diagnosticRevision` starts at 1 and increases monotonically per cycle. Each revision binds `previousDiagnosticFingerprint` to the prior active revision.
+
+## Interventions
+
+Recorded in `CORRECTING` phase:
+
+```bash
+forgeloop record-intervention --task <id> --file intervention.json --json
+```
+
+Interventions bind to at least one recorded hypothesis and carry a semantic fingerprint used to detect repetition without information gain.
+
+## Hypothesis dispositions
+
+```bash
+forgeloop record-hypothesis-disposition --task <id> \
+  --hypothesis h-timeout-latency --status SUPPORTED \
+  --evidence-ref checkout-tests --reason "..." --json
+```
+
+Allowed transitions: `OPEN → {SUPPORTED, WEAKENED, FALSIFIED, SUPERSEDED, UNRESOLVED}`, `SUPPORTED → {WEAKENED, FALSIFIED, SUPERSEDED}`, `WEAKENED → {SUPPORTED, FALSIFIED, SUPERSEDED}`.
+
+## Diagnostic precedence
+
+One canonical resolver backs every lifecycle gate, `next`, `progress`, and reflection:
+
+1. latest valid structured diagnostic case (`DIAGNOSTIC_CASE_RECORDED`) for the active task/cycle;
+2. latest valid legacy diagnosis (`DIAGNOSIS_RECORDED`) for the active task/cycle;
+3. none.
+
+Structured diagnosis is therefore a first-class protocol-native diagnostic source: a task using only `record-diagnosis --file` can traverse `DIAGNOSING -> CORRECTING -> VERIFYING` without any legacy event, and no duplicate legacy event is synthesized. Legacy diagnosis remains fully valid as a compatibility input.
+
+## Hypothesis state projection
+
+Hypothesis status is projected forward from append-only chronology (case creation in `OPEN`, then each disposition validated against the last effective projected state) — never re-read from the source case. Terminal states (`FALSIFIED`, `SUPERSEDED`, `UNRESOLVED`) do not transition unless a future protocol revision explicitly allows reopening. Invalid transitions fail closed with `E_HYPOTHESIS_DISPOSITION_INVALID`. `trace`, `reflect`, and continuity `openHypotheses` all consume this same projection.
+
+## Evidence binding
+
+Structured cases require at least one hypothesis; `CHECK_RESULT` observations must resolve to a real check from the active verification cycle; a `VERIFICATION_FAILURE` case must bind at least one hypothesis or observation to failed/blocked evidence from the active cycle. Revision chains are revalidated at read time (`revision N.previousDiagnosticFingerprint == revision N-1.diagnosticFingerprint`).
+
+## Effective gain definition
+
+Effective Information Gain exists when a diagnostic cycle changes a meaningful
+semantic dimension of the verified engineering state:
+
+```text
+new observation        new contributor       new hypothesis
+new evidence           hypothesis disposition hypothesis elimination
+failure signature      failure surface        intervention semantics
+strategy
+```
+
+All of these participate in `effectiveGain`. Semantic noise — new IDs,
+timestamps, property order, whitespace-equivalent paraphrases — never does.
+
+## Classification vs effective gain
+
+The compatibility classification (`FIRST_DIAGNOSIS`, `NEW_HYPOTHESIS`,
+`NEW_EVIDENCE`, `NEW_HYPOTHESIS_AND_EVIDENCE`, `NONE`) intentionally does not
+encode every v2 dimension. A cycle can therefore report:
+
+```text
+classification = NONE
+failureSurfaceChanged = true
+effectiveGain = true
+```
+
+`effectiveGain` is computed once from the final dimensions by the authoritative
+cycle analysis projection; consumers (progress, reflect, next, inspect,
+continuity) must not recompute or post-mutate it.
+
+## Stall policy (fail-fast)
+
+A structured diagnostic state is **stalled** when its latest comparable
+diagnostic state has no effective information gain. There is no two-cycle
+threshold: one no-gain comparison blocks another blind correction retry with
+`E_DIAGNOSIS_NO_NEW_INFORMATION`, and progress/reflect/next/inspect expose the
+same condition. The first diagnosis is never stalled. High correction-cycle
+count alone remains advisory (`WATCH`), never `STALLED`.
+
+Stall is not terminal: recording a diagnostic with meaningful new information
+(a new observation, contributor, evidence, hypothesis change, and so on)
+clears it immediately. Strategy oscillation (`A -> B -> A`) keeps the more
+specific `INTRODUCE_NEW_OBSERVATION` guidance over generic no-gain guidance.
+Historical repetition metrics remain available as reflective explanation
+(`stallAnalysis`) but do not change the stall decision. Semantic noise — new IDs,
+timestamps, property order, whitespace-equivalent paraphrases — never counts as
+gain or as hypothesis elimination.
+
+## Failure surface evolution
+
+Every canonically verified cycle appears in failure surfaces, including
+successful ones:
+
+```text
+cycle 2 ["lint"]
+cycle 3 []        <- explicit empty successful cycle, direction REDUCED
+```
+
+A full reduction to `[]` classifies the preceding intervention as `IMPROVED`.
+
+## Intervention repetition
+
+```text
+repeatedSemanticIntervention
+  = the same intervention semantic fingerprint was recorded before
+
+NON_INFORMATIVE
+  = later verification produced no meaningful semantic change
+```
+
+Recording an intervention returns `repeatedSemanticIntervention` plus
+`effectiveness: "PENDING"`. Only a subsequent completed verification cycle can
+classify `IMPROVED | REGRESSED | INFORMATIVE | NON_INFORMATIVE`.
+
+## Continuity diagnostic context
+
+```json
+{
+  "activeFailureSignatures": ["<sha256-like canonical fingerprint>"],
+  "activeFailedRequirements": ["auth-tests"],
+  "openHypotheses": [],
+  "latestIntervention": null,
+  "nextExperiment": null,
+  "doNotRepeat": []
+}
+```
+
+`activeFailureSignatures` contains canonical `computeFailureSignature` hashes
+scoped to the active verification cycle; requirement names are exposed
+separately in `activeFailedRequirements`.
+
+## Structured case hypothesis invariant
+
+At least one hypothesis is mandatory: `hypotheses.minItems = 1` is enforced
+identically by the JSON schema, the runtime validator, ledger validation, and
+the record-diagnosis command path.
+
+## Information gain
+
+Compatibility values (`FIRST_DIAGNOSIS`, `NEW_HYPOTHESIS`, `NEW_EVIDENCE`, `NEW_HYPOTHESIS_AND_EVIDENCE`, `NONE`) remain valid. Structured dimensions add observation/contributor/hypothesis novelty, disposition changes, failure-signature change, failure-surface change, and intervention change. New IDs, timestamps, whitespace, paraphrases, and identical reruns never constitute gain.
+
+## Stall and oscillation
+
+- High correction-cycle count alone is advisory (`WATCH`), never `STALLED`.
+- Strong stall requires identical failure signature, strategy, contributors, hypotheses, surface, and no new evidence across consecutive cycles. Two consecutive correction cycles without effective gain under the same strategy reach `STALLED` (`REQUIRE_NEW_DIAGNOSTIC_INFORMATION`).
+- Repetition of an intervention is not automatically non-informative: effectiveness (`PENDING | IMPROVED | REGRESSED | INFORMATIVE | NON_INFORMATIVE`) is classified only after subsequent verification. Continuity `doNotRepeat` requires semantic repetition AND at least two completed post-intervention verification cycles AND unchanged failure surface.
+- Oscillation (`A→B→A`) surfaces as `OSCILLATING_STRATEGY`; `next` recommends `INTRODUCE_NEW_OBSERVATION`.
+
+## Capability discovery
+
+`forgeloop protocol-info --json` advertises `features.diagnostics`, `executionHistory`, `structuredTrace`, `taskInspection`, and `reflection`.

package/docs/DOCUMENTATION_GUIDE.md

@@ -14,7 +14,7 @@ ForgeLoop strictly separates normative protocol definitions from operational doc
 | **Operational & Reference** | `docs/` (`GETTING_STARTED.md`, `CROSS_HARNESS_CONTINUITY.md`, `CLI_REFERENCE.md`, `ARTIFACT_REFERENCE.md`, `TROUBLESHOOTING.md`, `RECIPES.md`) | Tutorials, command reference, handoff workflows, and troubleshooting | Explains how to operate the system. Links to normative sources for formal specifications. |
 | **Domain Engineering** | `ENG/` (`clean-code-eng.md`, `design-code-eng.md`, `test-code-eng.md`, etc.) | Domain-specific implementation and quality standards | Frontmatter must adhere to `validate_loop_system.py` standards. |
 | **Consumer Documentation Quality** | [`ENG/documentation-quality-eng.md`](../ENG/documentation-quality-eng.md) | Quality standards for documentation work in projects using ForgeLoop | Governs client/consumer project documentation tasks via guide routing. |
-| **Visual Architecture** | `docs/forgeloop-flow.mmd` | Canonical architecture diagram source | Rendered SVG committed at `docs/assets/forgeloop-flow.svg`. |
+| **Visual Architecture** | `docs/diagrams/manifest.json` + `docs/diagrams/forgeloop-engineering-flow.workflow.json` | Governance metadata and canonical typed Archify workflow source | Animated HTML explorer, animated SVG fallback, deterministic receipt, and source-bound human review are committed under `docs/assets/diagrams/` and `docs/diagrams/reviews/`. |
 | **Documentation Index** | `DOCS_INDEX.md` | Single repository index and ownership map | Updated whenever documentation structure changes. |
 
 ---
@@ -84,7 +84,7 @@ cross-platform CI (.github/workflows/docs-quality.yml)
 | **CLI Command Options** | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) | `docs/CLI_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: cli:<command>:options -->` |
 | **Work-State Transitions** | `WORK_PHASES` / `WORK_TRANSITIONS` (`src/core/protocol.js`) | `ORCHESTRATOR_INTEGRATION.md` | `<!-- BEGIN FORGELOOP GENERATED: work-transitions -->` |
 | **Public Error Codes** | `PUBLIC_ERROR_CODES` (`src/core/error-codes.js`) | `docs/TROUBLESHOOTING.md` | `<!-- BEGIN FORGELOOP GENERATED: public-error-codes -->` |
-| **Architecture Flow** | `docs/forgeloop-flow.mmd` | `docs/assets/forgeloop-flow.svg` | Verified via embedded SHA-256 fingerprint |
+| **Architecture Flow** | `docs/diagrams/manifest.json` + `docs/diagrams/forgeloop-engineering-flow.workflow.json` | `docs/assets/diagrams/forgeloop-engineering-flow.{html,svg,receipt.json}` + `docs/diagrams/reviews/forgeloop-engineering-flow.review.json` | Verified via pinned Archify renderer, trace-animation markers, source/SVG fingerprints, artifact hashes, persistent review, and composition checks |
 
 ### Maintenance Workflow
 
@@ -122,7 +122,7 @@ conformance checks detect omissions.
 | **Discovery resume rules** | `DISCOVERY_SURFACES` & `nativeShim` | `scripts/validate_documentation_conformance.mjs` |
 | **Task-layout path freshness** | `TASK_LAYOUT_DOCUMENTS` & `task-paths.js` | `scripts/validate_documentation_conformance.mjs` |
 | **Package-shipped docs** | `package.json` (`files`) | `tests/package.test.js` |
-| **Architecture diagram** | `docs/forgeloop-flow.mmd` | `scripts/check-generated-diagram.mjs` |
+| **Architecture diagram** | `docs/diagrams/forgeloop-engineering-flow.workflow.json` | `scripts/check-documentation-diagrams.mjs` and `scripts/documentation-diagram-inventory.mjs` |
 
 ---
 
@@ -177,21 +177,29 @@ migration, or security-sensitive require `npm run docs:check` before merge.
 
 ---
 
-## 7. Mermaid Diagrams and SVG Generation
+## 7. Archify Diagrams and Animated SVG Generation
 
-1. **Source is Canonical**: Diagram source files live in `.mmd` files (e.g. `docs/forgeloop-flow.mmd`). Never modify SVG files directly.
-2. **Local Committed SVGs**: Generated SVGs are committed locally in `docs/assets/`. Never hotlink externally rendered diagram images.
-3. **Self-Contained & GitHub-Safe**: Generated SVGs must not import external stylesheets (e.g. `@import url(...)`), must not embed `<script>` or `<foreignObject>`, and must be visible via standard Markdown image syntax (`![alt](./path.svg)`).
-4. **Fingerprint Verification**: Generated SVGs embed a `data-forgeloop-source-sha256` attribute verified by `npm run docs:check`.
+1. **Typed source is canonical**: The architecture flow is authored in Archify workflow IR at `docs/diagrams/forgeloop-engineering-flow.workflow.json`. Never modify generated HTML or SVG files directly.
+2. **Pinned local renderer**: Generation uses only the vendored Archify v2.15.0 source at the reviewed commit recorded in `docs/diagrams/manifest.json` and `vendor/archify/v2.15.0/PIN.json`.
+3. **Animated committed outputs**: The source uses `meta.animation: "trace"`. The interactive HTML is the primary animated explorer, and the self-contained SVG fallback carries trace-capable edge/node animation while remaining usable in repository previews. The deterministic receipt is committed under `docs/assets/diagrams/`.
+4. **GitHub-safe SVG**: The SVG must not embed `<script>` or `<foreignObject>`, must expose accessible title/description metadata, and must remain visible through standard Markdown image syntax.
+5. **Fingerprint and review verification**: The generated SVG embeds a `data-forgeloop-source-sha256` attribute, the outputs expose trace markers, and the receipt binds the source, HTML, and SVG hashes. The human-owned review at `docs/diagrams/reviews/` binds the current source and SVG hashes and is never generated or overwritten. Run `npm run docs:diagrams:check` before review.
+6. **Scoped wrapper**: The ForgeLoop Archify wrapper is intentionally documentation-scoped. It reads canonical inputs only from `docs/diagrams/` and permits deliver outputs only under `docs/assets/diagrams/`.
+
+ForgeLoop governs five documentation-diagram categories: workflow,
+architecture, sequence, dataflow, and lifecycle. The current repository has
+one canonical workflow diagram. Governance support does not imply renderer
+support: a type requires an explicit renderer mapping before it can be added as
+an active diagram.
 
 ---
 
 ## 8. README Hero and Package Boundary
 
 README hero assets are branding/conceptual illustrations. They are not the
-canonical protocol diagram. `docs/forgeloop-flow.mmd` remains the canonical
-architecture flow source and `docs/assets/forgeloop-flow.svg` remains its
-generated render.
+canonical protocol diagram. The typed Archify workflow under `docs/diagrams/`
+remains the canonical architecture flow source, with generated outputs under
+`docs/assets/diagrams/`.
 
 The README hero is intentionally GitHub-repository-only:
 
@@ -206,8 +214,9 @@ The README hero is intentionally GitHub-repository-only:
   packaged Markdown must be present in the package and covered by
   `tests/package.test.js`.
 
-Never delete `docs/assets/forgeloop-flow.svg`; it is generator-owned output of
-the diagram workflow.
+Never edit or delete a generated diagram output independently of its source;
+regenerate `docs/assets/diagrams/` from the typed workflow and keep the receipt
+in sync.
 
 ---