@cassiomc1/forgeloop 1.1.1 → 1.2.2

package/docs/CLI_REFERENCE.md

@@ -40,11 +40,11 @@ ForgeLoop uses a definition-driven command-line parser:
 | Category | Commands |
 | --- | --- |
 | **Setup & Maintenance** | [`init`](#init), [`update`](#update), [`task-migrate`](#task-migrate), [`task-unlock`](#task-unlock) |
-| **Inspection & Diagnostics** | [`doctor`](#doctor), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
-| **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`complete`](#complete), [`clear-state`](#clear-state), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-scope`](#task-scope) |
+| **Inspection & Diagnostics** | [`doctor`](#doctor), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
+| **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-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) |
-| **Policy & Auditing** | [`policy`](#policy), [`bundle`](#bundle) |
+| **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 -->
 
@@ -64,7 +64,7 @@ Initializes ForgeLoop in a target repository.
 <!-- BEGIN FORGELOOP GENERATED: cli:init:options -->
 
 - `--path <directory>`: target project directory (default: current directory)
-- `--dry-run`: show planned writes without changing files
+- `--dry-run`: perform deterministic init planning and conflict detection without writing
 
 <!-- END FORGELOOP GENERATED: cli:init:options -->
 
@@ -80,7 +80,7 @@ Inspects repository health, adapter synchronization, and template integrity.
 
 - **Purpose**: Diagnose missing files, unmanaged adapters, profile issues, and broken kit references.
 - **When to use**: After initialization, after git merges, or when troubleshooting.
-- **Mutation**: Read-only (unless `--fix` is passed).
+- **Mutation**: Writes `.forgeloop/.manifest.json` only when `--fix` is passed; otherwise performs no mutation.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:doctor:options -->
@@ -111,7 +111,7 @@ Updates the managed instruction kit to match the current ForgeLoop package versi
 <!-- BEGIN FORGELOOP GENERATED: cli:update:options -->
 
 - `--path <directory>`: target project directory (default: current directory)
-- `--dry-run`: show planned writes without changing files
+- `--dry-run`: perform deterministic update planning and conflict detection without writing
 
 <!-- END FORGELOOP GENERATED: cli:update:options -->
 
@@ -131,7 +131,7 @@ Calculates and persists deterministic engineering guide routing.
 
 - **Purpose**: Selects relevant technical guides (e.g. `clean`, `test`, `security`, `design`) based on declared work attributes.
 - **When to use**: During discovery before preflight.
-- **Mutation**: Writes `.forgeloop/routing-result.json`.
+- **Mutation**: Writes `.forgeloop/task-state/<taskKey>/routing-result.json`.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:route:options -->
@@ -160,7 +160,7 @@ Validates pre-implementation readiness and establishes protocol readiness state.
 
 - **Purpose**: Verifies that the contract, route, profile facts, and mandatory pre-implementation gates (e.g. `design`) are satisfied and consistent.
 - **When to use**: Before starting implementation.
-- **Mutation**: Persists `.forgeloop/preflight.json` and, when the protocol is ready, may create or synchronize resumable work state and lifecycle events.
+- **Mutation**: Persists `.forgeloop/task-state/<taskKey>/preflight.json` and, when the protocol is ready, may create or synchronize task-scoped resumable work state and lifecycle events.
 - **Return Status**: `READY` or `BLOCKED`.
 - **Options**:
 
@@ -185,7 +185,7 @@ Creates a protocol/session activation marker for the current harness session.
 
 - **Purpose**: Creates an activation marker containing `sessionId`, `activationMarker`, and `createdAt` for the current harness session. It does not create the canonical lifecycle work state.
 - **When to use**: When starting a session after `preflight` is established.
-- **Mutation**: Writes `.forgeloop/session.json`.
+- **Mutation**: Writes `.forgeloop/sessions/<sessionId>.json`.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:activate:options -->
@@ -201,13 +201,40 @@ Creates a protocol/session activation marker for the current harness session.
   forgeloop activate --json
   ```
 
+### `record-decision-criterion`
+
+Records an append-only decision settlement criterion bound to the active contract fingerprint.
+
+- **Purpose**: Records settlement guidance or criteria for open contract decisions without modifying contract schema.
+- **When to use**: To attach settlement guidance to unresolved decisions in `current-contract.unresolvedDecisions[]`.
+- **Mutation**: Appends `DECISION_CRITERION_RECORDED` to event ledger.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:record-decision-criterion: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)
+- `--decision <text>`: unresolved decision text matching current contract
+- `--settled-by <text>`: criteria or guidance that settles the decision
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:record-decision-criterion:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop record-decision-criterion \
+    --decision="Which authentication provider should be used?" \
+    --settled-by="Use provider supporting current session token middleware"
+  ```
+
 ### `advance`
 
 Advances the protocol lifecycle phase.
 
-- **Purpose**: Transitions between valid protocol phases (`PLANNED`, `EXECUTING`, `VERIFYING`, `REVIEWING`).
+- **Purpose**: Transitions the task along a valid edge of the canonical ForgeLoop work-state machine. The destination is validated against the current phase and the canonical lifecycle transition rules.
 - **When to use**: To declare transitions between workflow stages.
-- **Mutation**: Updates `.forgeloop/work-state.json` and appends transition event to ledger.
+- **Mutation**: Updates `.forgeloop/task-state/<taskKey>/work-state.json` and appends transition event to ledger.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:advance:options -->
@@ -242,10 +269,14 @@ Computes the deterministic next action required by the protocol.
 
 <!-- END FORGELOOP GENERATED: cli:next:options -->
 
-- **Example**:
+- **Examples**:
 
   ```bash
   forgeloop next --json
+
+  # Explicit task selection prevents another concurrent task from
+  # becoming the implicit source of lifecycle state
+  forgeloop next --task <id> --json
   ```
 
 ---
@@ -281,7 +312,7 @@ Records operational handoff context before pausing or switching tools.
 
 - **Purpose**: Stores immediate work-in-progress notes to help the next harness continue without confusion.
 - **When to use**: Before ending a session or transferring control.
-- **Mutation**: Writes `.forgeloop/continuity.json`.
+- **Mutation**: Writes `.forgeloop/task-state/<taskKey>/continuity.json`.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:record-continuity:options -->
@@ -339,7 +370,7 @@ Clears operational continuity context while preserving canonical work state.
 
 - **Purpose**: Removes stale or corrupt continuity handoff data when starting fresh from the last work-state checkpoint.
 - **When to use**: When continuity is unrecoverably stale or no longer relevant.
-- **Mutation**: Removes `.forgeloop/continuity.json`.
+- **Mutation**: Removes `.forgeloop/task-state/<taskKey>/continuity.json`.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:clear-continuity:options -->
@@ -364,9 +395,9 @@ Clears operational continuity context while preserving canonical work state.
 
 Executes a verification command with ForgeLoop-attested provenance.
 
-- **Purpose**: Runs an exact command, records the execution artifact in `.forgeloop/executions/`, and binds the resulting observed check evidence to that execution through `executionRef`.
+- **Purpose**: Runs an exact command, records the execution artifact in `.forgeloop/task-state/<taskKey>/executions/`, and binds the resulting observed check evidence to that execution through `executionRef`.
 - **When to use**: During `VERIFYING` phase to execute test suites, linters, or validators.
-- **Mutation**: Writes `.forgeloop/executions/exec-*.json`, updates `.forgeloop/execution-receipt.json`, appends to ledger.
+- **Mutation**: Writes `.forgeloop/task-state/<taskKey>/executions/exec-*.json`, updates `.forgeloop/task-state/<taskKey>/execution-receipt.json`, appends to task ledger.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:run-check:options -->
@@ -393,7 +424,7 @@ Records an observed or manual verification check result without executing comman
 
 - **Purpose**: Records manual review evidence or external observations.
 - **When to use**: For manual reviews, accessibility inspections, or external validations.
-- **Mutation**: Updates `.forgeloop/execution-receipt.json` and appends to ledger.
+- **Mutation**: Updates `.forgeloop/task-state/<taskKey>/execution-receipt.json` and appends to task ledger.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:record-check:options -->
@@ -427,9 +458,42 @@ Records an observed or manual verification check result without executing comman
     --result "Verified contrast ratios exceed 4.5:1 across all color schemes"
   ```
 
+### `record-diagnosis`
+
+Records an append-only diagnosis event in the lifecycle event ledger for the active cycle.
+
+- **Purpose**: Records root-cause hypotheses, failure classes, and settlement criteria for failed verification checks.
+- **When to use**: In `DIAGNOSING` phase before advancing to `CORRECTING`.
+- **Mutation**: Appends `DIAGNOSIS_RECORDED` to event ledger and updates work state projection.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:record-diagnosis: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 <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)
+- `--settled-by <text>`: falsification or settlement criteria for the hypothesis
+- `--next-safe-action <text>`: smallest safe action to address the hypothesis
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:record-diagnosis:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop record-diagnosis \
+    --hypothesis="Off-by-one index calculation in slice function" \
+    --failure-class="VERIFICATION_FAILURE" \
+    --evidence-ref="unit-tests" \
+    --settled-by="Test returns expected slice length" \
+    --next-safe-action="Adjust offset +1 in slice.js"
+  ```
+
 ### `validate-state`
 
-Validates `.forgeloop/work-state.json` structure, hash chain, and repository binding.
+Validates `.forgeloop/task-state/<taskKey>/work-state.json` structure, hash chain, and repository binding.
 
 - **Purpose**: Integrity check for work state.
 - **Mutation**: Read-only.
@@ -451,26 +515,42 @@ Validates `.forgeloop/work-state.json` structure, hash chain, and repository bin
 
 ### `validate-receipt`
 
-Validates `.forgeloop/execution-receipt.json` schema and check references.
+Validates `.forgeloop/task-state/<taskKey>/execution-receipt.json` schema and check references.
 
 - **Purpose**: Integrity check for completion receipt.
 - **Mutation**: Read-only.
+- **Receipt Resolution**: Without `--file`, the receipt is resolved from the task context: an explicit `--task` (or `FORGELOOP_TASK`) selects that task's namespaced receipt, otherwise a single active task is resolved automatically. `--file` overrides task-based receipt resolution and validates exactly the given relative file.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:validate-receipt:options -->
 
 - `--path <directory>`: target project directory (default: current directory)
-- `--file <path>`: receipt file relative to target
+- `--task <id>`: task ID to operate on (when omitted, resolved from context or single active task)
+- `--file <path>`: receipt file relative to target (overrides task-based receipt resolution)
 - `--json`: emit structured output as JSON
 
 <!-- END FORGELOOP GENERATED: cli:validate-receipt:options -->
 
-- **Example**:
+- **Examples**:
+
+  Validate the selected task's namespaced receipt:
+
+  ```bash
+  forgeloop validate-receipt --task task-001 --json
+  ```
+
+  Validate an explicit receipt file (`--file` overrides task-based receipt resolution):
 
   ```bash
-  forgeloop validate-receipt --json
+  forgeloop validate-receipt --file .forgeloop/task-state/<taskKey>/execution-receipt.json --json
   ```
 
+<!-- BEGIN FORGELOOP LEGACY LAYOUT EXAMPLE -->
+
+When no task is selected and no task descriptors exist, the legacy singleton `.forgeloop/execution-receipt.json` compatibility path is validated.
+
+<!-- END FORGELOOP LEGACY LAYOUT EXAMPLE -->
+
 ### `validate-protocol`
 
 Performs comprehensive protocol validation across all active artifacts.
@@ -500,17 +580,40 @@ Performs comprehensive protocol validation across all active artifacts.
   forgeloop validate-protocol --json
   ```
 
+### `progress`
+
+Evaluates task progress across verification cycles and detects stalls deterministically.
+
+- **Purpose**: Evaluates whether iterative correction cycles are advancing, on watch, or stalled.
+- **When to use**: Any time during execution, verification, or diagnosis to inspect progress signals and prevent repeated ineffective retries.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:progress: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 progress evaluation as JSON
+
+<!-- END FORGELOOP GENERATED: cli:progress:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop progress --json
+  ```
+
 ---
 
 ## 5. Completion & Reporting
 
 ### `prepare-completion`
 
-Initializes or refreshes `.forgeloop/execution-receipt.json`.
+Initializes or refreshes `.forgeloop/task-state/<taskKey>/execution-receipt.json`.
 
 - **Purpose**: Maps contract requirements to evidence coverage slots.
 - **When to use**: Upon entering the `VERIFYING` phase before recording checks.
-- **Mutation**: Writes `.forgeloop/execution-receipt.json`.
+- **Mutation**: Writes `.forgeloop/task-state/<taskKey>/execution-receipt.json`.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:prepare-completion:options -->
@@ -556,11 +659,19 @@ Records external publication or production-readiness observations.
   forgeloop record-terminal-result \
     --requirement release-publish \
     --type PUBLICATION \
-    --status passed \
+    --status published \
     --source "npm publish" \
     --result "v1.1.0 published to registry"
   ```
 
+- **Terminal Statuses**: The `--status` value must be one of the canonical
+  statuses for the declared `--type`:
+
+  | `--type` | Allowed `--status` values |
+  | --- | --- |
+  | `PUBLICATION` | `committed`, `pushed`, `published`, `deployed` |
+  | `PRODUCTION_READINESS` | `ready`, `blocked` |
+
 ### `audit`
 
 Performs a read-only dry-run evaluation of completion readiness.
@@ -591,8 +702,9 @@ Validates protocol completion and transitions the task to `COMPLETE`.
 
 - **Purpose**: Authoritative protocol validation of the entire task lifecycle.
 - **When to use**: In `REVIEWING` phase when all checks have passed.
-- **Mutation**: Updates `.forgeloop/work-state.json` to `COMPLETE` and records completion event.
-- **Return Status**: `VALID`, `INCOMPLETE`, `STALE`, `INCONSISTENT`, or `INVALID`.
+- **Mutation**: Updates `.forgeloop/task-state/<taskKey>/work-state.json` to `COMPLETE` and records completion event.
+- **Return Status**: `VALID` or `REJECTED`.
+- **Return Dimensions**: The evaluation result reports separate dimensions alongside the return status: `taskStatus` (`COMPLETE`/`INCOMPLETE`/`BLOCKED`), `verificationStatus` (`VALID`/`invalid`), `publicationStatus`, `productionReadiness`, and `errors[]` with the concrete rejection reasons.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:complete:options -->
@@ -728,13 +840,177 @@ Evaluates compliance against a named policy pack.
   forgeloop policy default --json
   ```
 
+### `policy-discover`
+
+Discovers architectural patterns, project conventions, and candidate verification rules deterministically.
+
+- **Purpose**: Runs non-interactive repository inspection to derive policy rules with confidence scores.
+- **Mutation**: Read-only by default; writes `.forgeloop/policy/discovery.json` and regenerates `.forgeloop/policy/policy.lock` only with `--write`. Without `--write`, discovery is observational and persists nothing.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:policy-discover:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--write`: persist discovered policy to .forgeloop/policy/discovery.json
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:policy-discover:options -->
+
+- **Examples**:
+
+  Read-only discovery (observational, persists nothing):
+
+  ```bash
+  forgeloop policy-discover --json
+  ```
+
+  Persist discovery and regenerate the policy lock:
+
+  ```bash
+  forgeloop policy-discover --write --json
+  ```
+
+### `policy-status`
+
+Reports effective executable policy verification status, baselines, lock integrity, and drift.
+
+- **Purpose**: Evaluates all rules, verifies `policy.lock` integrity, identifies inert checks, baselined debt, unbaselined violations, and drift against the task snapshot.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:policy-status: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 output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:policy-status:options -->
+
+- **Examples**:
+
+  ```bash
+  forgeloop policy-status --json
+
+  # Evaluate drift against a specific task snapshot
+  forgeloop policy-status --task <id> --json
+  ```
+
+### `policy-diff`
+
+Semantically diffs policy rules and classifies changes as tightening, neutral, or weakening.
+
+- **Purpose**: Compares proposed or current policy against a base or task snapshot.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:policy-diff: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)
+- `--before <path>`: path to before policy JSON
+- `--after <path>`: path to after policy JSON
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:policy-diff:options -->
+
+- **Examples**:
+
+  ```bash
+  # Diff the current effective policy against the task snapshot
+  forgeloop policy-diff --task <id> --json
+
+  # Diff two explicit policy JSON files
+  forgeloop policy-diff --before .forgeloop/policy/before.json --after .forgeloop/policy/after.json --json
+  ```
+
+### `rule-verify`
+
+Runs mutation verification on policy rules to prove checkers actively detect invalid states.
+
+- **Purpose**: Validates that rule checkers fail on mutant fixtures, generating proof digests.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:rule-verify:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--rule <id>`: verify a specific policy rule ID
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:rule-verify:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop rule-verify --rule SECURITY.NO_HARDCODED_SECRET --json
+  ```
+
+### `baseline`
+
+Manages the brownfield policy baseline and monotonic ratchet-down.
+
+- **Purpose**: Records current violations into baseline, or ratchets baseline downward as debt is fixed.
+- **Mutation**: Writes `.forgeloop/policy/baseline.json` and regenerates `.forgeloop/policy/policy.lock`.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:baseline:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--record`: record current violations as brownfield baseline
+- `--update`: ratchet baseline downward by removing resolved violations
+- `--policy-reset-authorized`: explicit operator authority to re-record baseline during active tasks
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:baseline:options -->
+
+- **Examples**:
+
+  ```bash
+  # Adopt pre-existing violations as brownfield debt
+  forgeloop baseline --record --json
+
+  # Remove resolved debt (monotonic; additions are rejected)
+  forgeloop baseline --update --json
+
+  # Explicit operator authority to re-record during an active task
+  forgeloop baseline --record --policy-reset-authorized --json
+  ```
+
+During an active task bound to a policy snapshot, `--record` without
+`--policy-reset-authorized` fails with `E_BASELINE_RECORD_DURING_ACTIVE_TASK`;
+`--update` is monotonic and fails with `E_BASELINE_EXPANSION` if it would add
+debt.
+
+### `profile-interview`
+
+Optional operator-facing interview guidance (never invoked autonomously by agent).
+
+- **Purpose**: Returns optional discovery/interview guidance to help an operator inspect or refine project assumptions. It does not write `PROJECT_PROFILE.md` automatically.
+- **When to use**: Optional; never required for normal autonomous execution.
+- **Mutation**: Read-only.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:profile-interview:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--dry-run`: show planned interview questions without changing files
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:profile-interview:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop profile-interview
+  ```
+
 ### `clear-state`
 
 Clears canonical work-state checkpoint for the current task.
 
 - **Purpose**: Emergency reset of local work-state checkpoint.
 - **When to use**: Only when abandoning a task or resetting state after an unrecoverable corruption.
-- **Mutation**: Removes `.forgeloop/work-state.json` only. Sibling ForgeLoop artifacts (such as contracts, routes, gates, and ledger history) are preserved.
+- **Mutation**: Removes `.forgeloop/task-state/<taskKey>/work-state.json` only. Sibling ForgeLoop artifacts (such as contracts, routes, gates, and ledger history) are preserved.
 - **Safety Note**: This is not a full `.forgeloop/` reset command.
 - **Options**:
 
@@ -754,6 +1030,38 @@ Clears canonical work-state checkpoint for the current task.
 
 ---
 
+### `reconcile-closure`
+
+Reconciles the checkpoint of an EXECUTING task whose objective is already satisfied in the current repository.
+
+- **Purpose**: Refresh the work-state repository fingerprint of a stale EXECUTING task after repository movement, using executed contract-bound evidence that the objective is present, so the canonical completion pipeline can close it.
+- **When to use**: When a task is stuck in EXECUTING with `E_REPOSITORY_CHANGED` / `E_STATE_REVALIDATION_REQUIRED` and its objective was already satisfied by other changes in the current repository.
+- **Mutation**: Appends a `CHECKPOINT_RECONCILED` ledger event (previous/current repository fingerprints plus evidence) and refreshes the work-state repository fingerprint. Phase stays EXECUTING; claims release only through canonical `COMPLETE`.
+- **Safety Note**: Refuses non-EXECUTING tasks, fresh checkpoints, contract or artifact drift, invalid ledgers, unknown requirements, and failing evidence.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:reconcile-closure: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>`: contract verification item id used as evidence
+- `--requirement <id>`: exact contract verification item requirement text
+- `--details <json>`: additional structured execution details
+- `-- <argv...>`: exact command argv to execute as objective-satisfaction evidence
+- `--json`: emit structured output as JSON
+
+<!-- END FORGELOOP GENERATED: cli:reconcile-closure:options -->
+
+- **Example**:
+
+  ```bash
+  forgeloop reconcile-closure --task <id> --id regression-tests \
+    --requirement "pack tarball test asserts the README image is excluded from the npm package" \
+    -- node --test tests/package.test.js
+  ```
+
+---
+
 ## 7. Multi-Task Management
 
 ### `task-create`
@@ -777,9 +1085,17 @@ Initializes a new isolated task namespace with write claims and contract.
 - **Example**:
 
   ```bash
-  forgeloop task-create --id task-001 --claim src/auth --prompt "Add auth module" --json
+  forgeloop task-create --task task-001 --claim src/auth --json
   ```
 
+  With an explicit initial contract file:
+
+  ```bash
+  forgeloop task-create --task task-001 --claim src/auth --claim tests/auth --contract-file task-contract.json --json
+  ```
+
+  `--contract-file` points to a contract JSON that is validated and copied into the task namespace.
+
 ### `task-list`
 
 Lists all tasks discovered in `.forgeloop/task-state/`.
@@ -843,7 +1159,7 @@ Updates or inspects write claims for a task.
 - **Example**:
 
   ```bash
-  forgeloop task-scope --task task-001 --claim src/auth tests/auth --json
+  forgeloop task-scope --task task-001 --claim src/auth --claim tests/auth --json
   ```
 
 ### `task-migrate`

package/docs/CROSS_HARNESS_CONTINUITY.md

@@ -48,6 +48,7 @@ Key continuity invariants:
 | **Operational Continuity** | `.forgeloop/task-state/<taskKey>/continuity.json` | Active focus, remaining items, known issues, inspect-first paths | Operational context only (non-evidence) |
 | **Implementation Truth** | Git checkout / filesystem | Actual source code and files | Ground truth for changes |
 | **Task Intent** | `.forgeloop/task-state/<taskKey>/contract.json` | Objectives, constraints, deliverables, verification requirements | Contract authority |
+| **Task Policy Snapshot** | `.forgeloop/task-state/<taskKey>/policy-snapshot.json` | Effective policy rules and baseline authorized at preflight | Policy integrity binding; a replacement harness must resume against this snapshot, not re-discover policy |
 | **Execution Guidance** | `.forgeloop/task-state/<taskKey>/routing-result.json` | Deterministically selected engineering guides | Guidance |
 | **Verification Provenance** | `.forgeloop/task-state/<taskKey>/executions/*.json` | Attested process execution records | Verification truth |
 | **Next Action** | `forgeloop next` | Deterministic computation of the valid next command | Control authority |

package/docs/DOCUMENTATION_GUIDE.md

@@ -35,6 +35,10 @@ Documentation routing   -> DOCS_INDEX.md
 
 Operational documentation must explain canonical behavior, not redefine it.
 
+Canonical phase and transition inventories must be derived from `WORK_PHASES`
+and `WORK_TRANSITIONS`; do not maintain independent hand-written transition
+enums when a generated or mechanically validated representation is available.
+
 ---
 
 ## 3. Generated Documentation Provenance & Pipeline
@@ -60,10 +64,11 @@ cross-platform CI (.github/workflows/docs-quality.yml)
 | Fact Category | Canonical Machine Source | Generated Target File | Generated Region Marker |
 | --- | --- | --- | --- |
 | **Artifact Inventory** | `ARTIFACT_REGISTRY` (`src/core/artifact-registry.js`) | `docs/ARTIFACT_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: artifact-registry -->` |
-| **Artifact Fields** (12 schemas) | `schemas/*.schema.json` | `docs/ARTIFACT_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: schema:<name> -->` |
+| **Artifact Fields** | `schemas/*.schema.json` | `docs/ARTIFACT_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: schema:<name> -->` |
 | **CLI Command Index** | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) | `docs/CLI_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: cli-command-index -->` |
 | **CLI Common Options** | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) | `docs/CLI_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: cli-common-options -->` |
-| **CLI Command Options** (27 commands) | `CLI_COMMAND_DEFINITIONS` (`src/core/cli-command-definitions.js`) | `docs/CLI_REFERENCE.md` | `<!-- BEGIN FORGELOOP GENERATED: cli:<command>:options -->` |
+| **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 |
 
@@ -82,6 +87,11 @@ npm test
 npm run docs:check
 ```
 
+Do not hard-code inventory totals in prose or headings. Counts of commands,
+schemas, fields, and public codes are derived from the registries and schemas;
+when those sources change, regenerate the reference documents and let the
+conformance checks detect omissions.
+
 ---
 
 ## 4. Documentation Conformance Matrix
@@ -93,9 +103,10 @@ npm run docs:check
 | **Artifact fields & types** | `schemas/*.schema.json` | `scripts/validate_documentation_conformance.mjs` |
 | **Enums & consts** | `schemas/*.schema.json` | `scripts/validate_documentation_conformance.mjs` |
 | **Lifecycle phases** | `WORK_PHASES` (`src/core/protocol.js`) | `scripts/validate_documentation_conformance.mjs` |
+| **Lifecycle transitions** | `WORK_TRANSITIONS` (`src/core/protocol.js`) + the special `BLOCKED` rule | `scripts/generate_documentation_reference.mjs` and `scripts/validate_documentation_conformance.mjs` |
 | **Stable error codes** | `PUBLIC_ERROR_CODES` (`src/core/error-codes.js`) | `scripts/validate_documentation_conformance.mjs` |
 | **Discovery resume rules** | `DISCOVERY_SURFACES` & `nativeShim` | `scripts/validate_documentation_conformance.mjs` |
-| **Operational path freshness** | `OPERATIONAL_DOCUMENTS` & `task-paths.js` | `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` |
 
@@ -116,6 +127,7 @@ Avoid ambiguous phrases like *"should generally"* or *"usually"* for behaviors t
 
 - Canonical task-scoped paths are defined in `src/core/task-paths.js` under `.forgeloop/task-state/<taskKey>/`.
 - Operational guides (`README.md`, `GETTING_STARTED.md`, `RECIPES.md`, `CROSS_HARNESS_CONTINUITY.md`, `TROUBLESHOOTING.md`) must document namespaced paths by default.
+- Architecture/integration documents (`LOOP_SYSTEM_DESIGN.md`, `ORCHESTRATOR_INTEGRATION.md`) are covered by the same task-layout conformance scope (`TASK_LAYOUT_DOCUMENTS`).
 - Legacy ForgeLoop 1.0 singleton paths (e.g. `.forgeloop/current-contract.json`) are permitted **only** inside explicit legacy migration regions:
 
   ```markdown
@@ -145,7 +157,32 @@ Avoid ambiguous phrases like *"should generally"* or *"usually"* for behaviors t
 
 ---
 
-## 8. Documentation Change Checklist for Pull Requests
+## 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.
+
+The README hero is intentionally GitHub-repository-only:
+
+- `README.md` may reference `docs/assets/eng_readme_forgeloop.png`; GitHub
+  renders it from the repository.
+- The hero PNG is excluded from the npm package (`package.json` `files`), and
+  `tests/package.test.js` asserts that exclusion so it cannot be silently
+  re-included.
+- The packaged README is therefore not self-contained for that relative hero
+  path; do not claim otherwise.
+- If a portable hero is ever shipped, any relative README asset referenced by
+  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.
+
+---
+
+## 9. Documentation Change Checklist for Pull Requests
 
 For documentation-impacting changes, verify each item before merging: