@cassiomc1/forgeloop 1.2.1 → 1.2.3

package/docs/ARTIFACT_REFERENCE.md

@@ -25,6 +25,11 @@ All artifact schemas are defined in `schemas/*.schema.json`. Persisted artifact
 | `task-state/<task-key>/continuity.json` | `continuity` | Agent Or Harness | Mutable Handoff Notes | Non Evidence Handoff |
 | `task-state/<task-key>/execution-receipt.json` | `execution-receipt` | Protocol Compiled | Atomic Compilation | Evidence Compilation |
 | `task-state/<task-key>/executions/exec-<id>.json` | `execution` | Protocol Executed | Immutable Once Written | Execution Provenance |
+| `policy/rules.json` | `policy-rules` | Operator Or Agent | Mutable Configuration | Policy Specification |
+| `policy/discovery.json` | `policy-discovery` | Protocol Generated | Mutable On Discovery | Discovered Policy Specification |
+| `policy/baseline.json` | `policy-baseline` | Protocol Generated Or Operator | Monotonic Ratchet Down | Brownfield Baseline |
+| `policy/policy.lock` | `policy-lock` | Protocol Generated | Atomic Digest Compilation | Policy Integrity Lock |
+| `task-state/<task-key>/policy-snapshot.json` | `policy-snapshot` | Protocol Generated | Mutable Before Execution | Task Policy Attestation |
 
 <!-- END FORGELOOP GENERATED: artifact-registry -->
 
@@ -440,3 +445,148 @@ Canonical task descriptor declaring task identity, key, timestamps, and write cl
 - `writeClaims` *(array<string>, required)*
 
 <!-- END FORGELOOP GENERATED: schema:task-descriptor -->
+
+---
+
+### 2.14 `policy/rules.json`
+
+<!-- forgeloop-doc: schema=policy-rules artifact=.forgeloop/policy/rules.json -->
+
+Repository-level executable policy rules declaring verification constraints.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:policy-rules -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `rules` *(array<object>, required)*
+  - `id` *(string, required, minLength: 1)*
+  - `severity` *(string, required, enum: `HIGH`, `MEDIUM`, `LOW`, `INFO`)*
+  - `source` *(string, required, enum: `builtin`, `discovered`, `project`)*
+  - `blocking` *(boolean, required)*
+  - `why` *(string, required, minLength: 1)*
+  - `fix` *(string, required, minLength: 1)*
+  - `confidence` *(string, optional, enum: `HIGH`, `MEDIUM`, `LOW`, `UNKNOWN`)*
+  - `scope` *(object, optional)*
+    - `includes` *(array<string>, optional)*
+    - `excludes` *(array<string>, optional)*
+  - `check` *(object, required)*
+    - `type` *(string, required, minLength: 1)*
+    - `adapter` *(string, optional)*
+    - `command` *(array<string>, optional)*
+    - `threshold` *(number, optional)*
+    - `parameters` *(object, optional)*
+
+<!-- END FORGELOOP GENERATED: schema:policy-rules -->
+
+---
+
+### 2.15 `policy/discovery.json`
+
+<!-- forgeloop-doc: schema=policy-discovery artifact=.forgeloop/policy/discovery.json -->
+
+Automated non-interactive discovery report recording inferred architecture, conventions, and confidence scores.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:policy-discovery -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `languages` *(array<string>, required)*
+- `testing` *(object, required)*
+  - `detected` *(boolean, required)*
+  - `command` *(array<string>, optional)*
+  - `framework` *(string, optional)*
+  - `confidence` *(string, required, enum: `HIGH`, `MEDIUM`, `LOW`, `UNKNOWN`)*
+- `linting` *(object, required)*
+  - `detected` *(boolean, required)*
+  - `command` *(array<string>, optional)*
+  - `tool` *(string, optional)*
+  - `confidence` *(string, required, enum: `HIGH`, `MEDIUM`, `LOW`, `UNKNOWN`)*
+- `architecture` *(object, required)*
+  - `value` *(string,null, optional)*
+  - `confidence` *(string, required, enum: `HIGH`, `MEDIUM`, `LOW`, `UNKNOWN`)*
+  - `enforcement` *(string, required, enum: `BLOCKING`, `ADVISORY`, `NONE`)*
+- `discoveredRules` *(array<object>, required)*
+
+<!-- END FORGELOOP GENERATED: schema:policy-discovery -->
+
+---
+
+### 2.16 `policy/baseline.json`
+
+<!-- forgeloop-doc: schema=policy-baseline artifact=.forgeloop/policy/baseline.json -->
+
+Brownfield policy baseline recording tolerated legacy violations by cryptographic fingerprint.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:policy-baseline -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `createdAt` *(string, required, minLength: 1)*
+- `entries` *(array<object>, required)*
+  - `ruleId` *(string, required, minLength: 1)*
+  - `fingerprints` *(array<string>, required)*
+  - `reviewBy` *(string, optional)*
+  - `details` *(array<object>, optional)*
+
+<!-- END FORGELOOP GENERATED: schema:policy-baseline -->
+
+---
+
+### 2.17 `policy/policy.lock`
+
+<!-- forgeloop-doc: schema=policy-lock artifact=.forgeloop/policy/policy.lock -->
+
+Cryptographic policy digest lock securing effective rules and baseline state.
+
+The lock protects the **effective policy** — built-in rules plus discovered
+rules plus project rules/overrides, combined with the baseline. `algorithm`,
+`digest`, `rulesDigest`, and `baselineDigest` all participate in lock integrity
+validation; a disagreement with the current effective policy produces
+`E_POLICY_LOCK_MISMATCH`. `capturedAt` is informational metadata only — it is
+not part of semantic policy identity, and changing it alone does not represent
+a policy change. A missing or malformed lock fails closed rather than being
+silently ignored.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:policy-lock -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `algorithm` *(string, required, const: `sha256`)*
+- `digest` *(string, required, minLength: 1)*
+- `rulesDigest` *(string, required)*
+- `baselineDigest` *(string, required)*
+- `capturedAt` *(string, optional)*
+
+<!-- END FORGELOOP GENERATED: schema:policy-lock -->
+
+---
+
+### 2.18 `task-state/<taskKey>/policy-snapshot.json`
+
+<!-- forgeloop-doc: schema=policy-snapshot artifact=.forgeloop/task-state/<task-key>/policy-snapshot.json -->
+
+Task-scoped immutable snapshot of effective policy captured during preflight to detect policy drift.
+
+A snapshot binds the task to the policy that was authorized at activation:
+`policyDigest`, the effective `rules`, semantic `baseline` entries, and
+`baselineDigest`. Later policy changes are classified by semantic diff as
+`TIGHTEN`, `NEUTRAL`, `WEAKEN`, or `UNKNOWN`. Modern snapshots carry the full
+semantic baseline; legacy snapshots without baseline state leave baseline
+comparison explicitly `UNKNOWN` rather than assuming an empty baseline.
+
+#### Canonical Fields
+
+<!-- BEGIN FORGELOOP GENERATED: schema:policy-snapshot -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `policyDigest` *(string, required, minLength: 1)*
+- `rules` *(array<string,object>, required)*
+- `baseline` *(object, optional)*
+- `baselineDigest` *(string, optional)*
+- `capturedAt` *(string, optional)*
+
+<!-- END FORGELOOP GENERATED: schema:policy-snapshot -->

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), [`progress`](#progress), [`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), [`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 -->
@@ -232,9 +232,9 @@ Records an append-only decision settlement criterion bound to the active contrac
 
 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 -->
@@ -269,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
   ```
 
 ---
@@ -308,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 -->
@@ -366,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 -->
@@ -391,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 -->
@@ -420,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 -->
@@ -489,7 +493,7 @@ Records an append-only diagnosis event in the lifecycle event ledger for the act
 
 ### `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.
@@ -511,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.
@@ -589,11 +609,11 @@ Evaluates task progress across verification cycles and detects stalls determinis
 
 ### `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 -->
@@ -639,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.
@@ -674,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 -->
@@ -811,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**:
 
@@ -837,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`
@@ -860,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/`.
@@ -926,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 |