@cassiomc1/forgeloop 1.14.0 → 2.0.0-rc.2

package/docs/AGENT_PROTOCOL_SUMMARY.md

@@ -7,7 +7,7 @@
 ForgeLoop is a portable protocol and support CLI for verifiable engineering workflows. It records and validates task state, contracts, routing, checks, evidence, continuity, and optional code attestations. It does not become an agent scheduler, delegation service, source-control authority, or secret manager.
 
 Protocol version: 1
-Package version: 1.14.0
+Package version: 2.0.0-rc.2
 
 ## Canonical loop
 
@@ -116,6 +116,7 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | executionProfileContext | 1 | yes |
 | integrationApi | 1 | yes |
 | observabilityStability | n/a | yes |
+| operationalStorage | 1 | yes |
 | providerExtensions | 1 | yes |
 | reflection | 1 | yes |
 | repositoryIndex | 1 | yes |
@@ -174,45 +175,46 @@ capability-family versions.
 | typescript | ENG/typescript-development-eng.md | yes |
 | php | ENG/php-development-eng.md | yes |
 | swift | ENG/swift-development-eng.md | yes |
+| python | ENG/python-development-eng.md | yes |
 
 ## Public artifact registry
 
-| Key | Scope | Path | Schema | Trust role |
-| --- | --- | --- | --- | --- |
-| actions | TASK | .forgeloop/task-state/<task-key>/actions/action-<id>.json | action | EXTERNAL_ACTION_PROVENANCE |
-| approvals | TASK | .forgeloop/task-state/<task-key>/approvals/approval-<id>.json | approval | ACTION_APPROVAL_ATTESTATION |
-| attestationBundle | TASK | .forgeloop/task-state/<task-key>/attestations/statement.sigstore.json | n/a | EXTERNAL_SIGNATURE_BUNDLE |
-| attestationStatement | TASK | .forgeloop/task-state/<task-key>/attestations/statement.json | in-toto-statement | CODE_ATTESTATION_STATEMENT |
-| capabilityPolicy | PROJECT | .forgeloop/policy/capabilities.json | capability-policy | CAPABILITY_POLICY_SPECIFICATION |
-| codeManifest | TASK | .forgeloop/task-state/<task-key>/attestations/code-manifest.json | code-manifest | CONTENT_INTEGRITY_SNAPSHOT |
-| config | PROJECT | .forgeloop/config.json | config | PROJECT_CONFIGURATION |
-| continuity | TASK | .forgeloop/task-state/<task-key>/continuity.json | continuity | NON_EVIDENCE_HANDOFF |
-| contract | TASK | .forgeloop/task-state/<task-key>/contract.json | current-contract | OPERATIONAL_SPECIFICATION |
-| descriptor | TASK | .forgeloop/task-state/<task-key>/task.json | task-descriptor | TASK_DESCRIPTOR |
-| evaluations | TASK | .forgeloop/task-state/<task-key>/evaluations/eval-<id>.json | trajectory-evaluation | TRAJECTORY_EVALUATION |
-| events | TASK | .forgeloop/task-state/<task-key>/events.ndjson | event | AUDIT_LEDGER |
-| executions | TASK | .forgeloop/task-state/<task-key>/executions/exec-<id>.json | execution | EXECUTION_PROVENANCE |
-| gates | TASK | .forgeloop/task-state/<task-key>/gates/<gate>.json | gate | GATE_APPROVAL_ATTESTATION |
-| handoffs | TASK | .forgeloop/task-state/<task-key>/handoffs/handoff-<id>.json | handoff-envelope | CANONICAL_HANDOFF_SNAPSHOT |
-| policyBaseline | PROJECT | .forgeloop/policy/baseline.json | policy-baseline | BROWNFIELD_BASELINE |
-| policyDiscovery | PROJECT | .forgeloop/policy/discovery.json | policy-discovery | DISCOVERED_POLICY_SPECIFICATION |
-| policyLock | PROJECT | .forgeloop/policy/policy.lock | policy-lock | POLICY_INTEGRITY_LOCK |
-| policyRules | PROJECT | .forgeloop/policy/rules.json | policy-rules | POLICY_SPECIFICATION |
-| policySnapshot | TASK | .forgeloop/task-state/<task-key>/policy-snapshot.json | policy-snapshot | TASK_POLICY_ATTESTATION |
-| preflight | TASK | .forgeloop/task-state/<task-key>/preflight.json | preflight | READINESS_ATTESTATION |
-| receipt | TASK | .forgeloop/task-state/<task-key>/execution-receipt.json | execution-receipt | EVIDENCE_COMPILATION |
-| recovery | TASK | .forgeloop/task-state/<task-key>/recovery.json | task-recovery | TASK_RECOVERY_STATE |
-| responsibility | TASK | .forgeloop/task-state/<task-key>/responsibility.json | responsibility | RESPONSIBILITY_CONSTRAINT |
-| route | TASK | .forgeloop/task-state/<task-key>/routing-result.json | routing-result | GUIDE_ROUTING_SPECIFICATION |
-| semanticDecisions | TASK | .forgeloop/task-state/<task-key>/decisions/<decision-id>.json | semantic-decision | SEMANTIC_DECISION |
-| session | SESSION | .forgeloop/sessions/<session-id>.json | activation | SESSION_MARKER |
-| sources | PROJECT | .forgeloop/sources.json | source-registry | SOURCE_ATTESTATION |
-| state | TASK | .forgeloop/task-state/<task-key>/work-state.json | work-state | CANONICAL_LIFECYCLE_STATE |
-| structuralQuality | TASK | .forgeloop/task-state/<task-key>/structural-quality/baseline.json | structural-quality | STRUCTURAL_QUALITY_EVIDENCE |
-| testUtility | TASK | .forgeloop/task-state/<task-key>/test-utility.json | test-utility | NON_EVIDENCE_TEST_ANALYSIS |
-| usage | TASK | .forgeloop/task-state/<task-key>/usage.json | usage | INFORMATIONAL_USAGE_TELEMETRY |
-| verificationScope | TASK | .forgeloop/task-state/<task-key>/verification-scope.json | verification-scope | VERIFICATION_SCOPE_PLAN |
-| workspaceBinding | TASK | .forgeloop/task-state/<task-key>/workspace-binding.json | workspace-binding | WORKSPACE_IDENTITY_BINDING |
+| Key | Scope | Logical identity | Canonical storage | Export path | Schema | Trust role |
+| --- | --- | --- | --- | --- | --- | --- |
+| actions | TASK | .forgeloop/task-state/<task-key>/actions/action-<id>.json | .forgeloop/state.sqlite :: actions | .forgeloop/task-state/<task-key>/actions/action-<id>.json | action | EXTERNAL_ACTION_PROVENANCE |
+| approvals | TASK | .forgeloop/task-state/<task-key>/approvals/approval-<id>.json | .forgeloop/state.sqlite :: approvals | .forgeloop/task-state/<task-key>/approvals/approval-<id>.json | approval | ACTION_APPROVAL_ATTESTATION |
+| attestationBundle | TASK | .forgeloop/task-state/<task-key>/attestations/statement.sigstore.json | .forgeloop/state.sqlite :: attachment_references | .forgeloop/attachments/objects/<sha256> | n/a | EXTERNAL_SIGNATURE_BUNDLE |
+| attestationStatement | TASK | .forgeloop/task-state/<task-key>/attestations/statement.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/attestations/statement.json | in-toto-statement | CODE_ATTESTATION_STATEMENT |
+| capabilityPolicy | PROJECT | .forgeloop/policy/capabilities.json | .forgeloop/policy/capabilities.json | Copied separately | capability-policy | CAPABILITY_POLICY_SPECIFICATION |
+| codeManifest | TASK | .forgeloop/task-state/<task-key>/attestations/code-manifest.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/attestations/code-manifest.json | code-manifest | CONTENT_INTEGRITY_SNAPSHOT |
+| config | PROJECT | .forgeloop/config.json | .forgeloop/config.json | Copied separately | config | PROJECT_CONFIGURATION |
+| continuity | TASK | .forgeloop/task-state/<task-key>/continuity.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/continuity.json | continuity | NON_EVIDENCE_HANDOFF |
+| contract | TASK | .forgeloop/task-state/<task-key>/contract.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/contract.json | current-contract | OPERATIONAL_SPECIFICATION |
+| descriptor | TASK | .forgeloop/task-state/<task-key>/task.json | .forgeloop/state.sqlite :: tasks | .forgeloop/task-state/<task-key>/task.json | task-descriptor | TASK_DESCRIPTOR |
+| evaluations | TASK | .forgeloop/task-state/<task-key>/evaluations/eval-<id>.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/evaluations/eval-<id>.json | trajectory-evaluation | TRAJECTORY_EVALUATION |
+| events | TASK | .forgeloop/task-state/<task-key>/events.ndjson | .forgeloop/state.sqlite :: events | .forgeloop/task-state/<task-key>/events.ndjson | event | AUDIT_LEDGER |
+| executions | TASK | .forgeloop/task-state/<task-key>/executions/exec-<id>.json | .forgeloop/state.sqlite :: executions | .forgeloop/task-state/<task-key>/executions/exec-<id>.json | execution | EXECUTION_PROVENANCE |
+| gates | TASK | .forgeloop/task-state/<task-key>/gates/<gate>.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/gates/<gate>.json | gate | GATE_APPROVAL_ATTESTATION |
+| handoffs | TASK | .forgeloop/task-state/<task-key>/handoffs/handoff-<id>.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/handoffs/handoff-<id>.json | handoff-envelope | CANONICAL_HANDOFF_SNAPSHOT |
+| policyBaseline | PROJECT | .forgeloop/policy/baseline.json | .forgeloop/policy/baseline.json | Copied separately | policy-baseline | BROWNFIELD_BASELINE |
+| policyDiscovery | PROJECT | .forgeloop/policy/discovery.json | .forgeloop/policy/discovery.json | Copied separately | policy-discovery | DISCOVERED_POLICY_SPECIFICATION |
+| policyLock | PROJECT | .forgeloop/policy/policy.lock | .forgeloop/policy/policy.lock | Copied separately | policy-lock | POLICY_INTEGRITY_LOCK |
+| policyRules | PROJECT | .forgeloop/policy/rules.json | .forgeloop/policy/rules.json | Copied separately | policy-rules | POLICY_SPECIFICATION |
+| policySnapshot | TASK | .forgeloop/task-state/<task-key>/policy-snapshot.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/policy-snapshot.json | policy-snapshot | TASK_POLICY_ATTESTATION |
+| preflight | TASK | .forgeloop/task-state/<task-key>/preflight.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/preflight.json | preflight | READINESS_ATTESTATION |
+| receipt | TASK | .forgeloop/task-state/<task-key>/execution-receipt.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/execution-receipt.json | execution-receipt | EVIDENCE_COMPILATION |
+| recovery | TASK | .forgeloop/task-state/<task-key>/recovery.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/recovery.json | task-recovery | TASK_RECOVERY_STATE |
+| responsibility | TASK | .forgeloop/task-state/<task-key>/responsibility.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/responsibility.json | responsibility | RESPONSIBILITY_CONSTRAINT |
+| route | TASK | .forgeloop/task-state/<task-key>/routing-result.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/routing-result.json | routing-result | GUIDE_ROUTING_SPECIFICATION |
+| semanticDecisions | TASK | .forgeloop/task-state/<task-key>/decisions/<decision-id>.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/decisions/<decision-id>.json | semantic-decision | SEMANTIC_DECISION |
+| session | SESSION | .forgeloop/sessions/<session-id>.json | .forgeloop/state.sqlite :: sessions | .forgeloop/sessions/<session-id>.json | activation | SESSION_MARKER |
+| sources | PROJECT | .forgeloop/sources.json | .forgeloop/sources.json | Copied separately | source-registry | SOURCE_ATTESTATION |
+| state | TASK | .forgeloop/task-state/<task-key>/work-state.json | .forgeloop/state.sqlite :: tasks | .forgeloop/task-state/<task-key>/work-state.json | work-state | CANONICAL_LIFECYCLE_STATE |
+| structuralQuality | TASK | .forgeloop/task-state/<task-key>/structural-quality/baseline.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/structural-quality/baseline.json | structural-quality | STRUCTURAL_QUALITY_EVIDENCE |
+| testUtility | TASK | .forgeloop/task-state/<task-key>/test-utility.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/test-utility.json | test-utility | NON_EVIDENCE_TEST_ANALYSIS |
+| usage | TASK | .forgeloop/task-state/<task-key>/usage.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/usage.json | usage | INFORMATIONAL_USAGE_TELEMETRY |
+| verificationScope | TASK | .forgeloop/task-state/<task-key>/verification-scope.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/verification-scope.json | verification-scope | VERIFICATION_SCOPE_PLAN |
+| workspaceBinding | TASK | .forgeloop/task-state/<task-key>/workspace-binding.json | .forgeloop/state.sqlite :: task_artifacts | .forgeloop/task-state/<task-key>/workspace-binding.json | workspace-binding | WORKSPACE_IDENTITY_BINDING |
 
 ## Command catalog
 
@@ -295,7 +297,7 @@ capability-family versions.
 | gate-revalidate | MUTATING | Refreshes a stale satisfied gate after execution only when current identity and active claims prove the change is safe. |
 | next | READ_ONLY | Returns deterministic next-action guidance and command recommendations based on active state. |
 | preflight | MUTATING | Evaluates pre-implementation contract, routing, and gates; synchronizes work state when READY. |
-| reconcile-closure | MUTATING | Refreshes the work-state checkpoint of an EXECUTING, VERIFYING, or REVIEWING task whose objective is already satisfied in the current repository, after contract-bound executed evidence, so canonical completion can proceed. |
+| reconcile-closure | MUTATING | Refreshes the work-state checkpoint of an EXECUTING, VERIFYING, CORRECTING, or REVIEWING task whose objective is already satisfied in the current repository, after contract-bound executed evidence, so canonical completion can proceed. |
 | record-decision-criterion | MUTATING | Records an append-only decision settlement criterion bound to the active contract fingerprint. |
 | record-diagnosis | MUTATING | Records an append-only diagnosis event or structured diagnostic case in the lifecycle event ledger. |
 | record-hypothesis-disposition | MUTATING | Records an evidence-bound hypothesis disposition update in the lifecycle event ledger. |
@@ -331,14 +333,22 @@ capability-family versions.
 | index-stop | MUTATING | Stops only a tgrep server whose process identity is provably owned by ForgeLoop. |
 | init | MUTATING | Initializes a target project directory with ForgeLoop discovery adapters, schemas, and templates. |
 | migrate-protocol | MUTATING | Safely migrates explicitly supported protocol state; unknown target versions fail without rewriting artifacts. |
+| storage-backup | MUTATING | Creates an exclusive native SQLite backup, optionally including canonically referenced attachments in a retained directory. |
+| storage-migrate | MUTATING | Validates, retains and archives legacy state before activating SQLite. Failed attempts retain maintenance exclusion; resume requires the exact retained owner and a verified candidate. |
+| storage-migration-resume | MUTATING | Adopts an exact dead local owner and continues verified publication stages. Unrecorded capture and unbound candidate files remain refused; an unbound legacy handoff is archived opaquely only with explicit --reconcile-unbound-handoff acknowledgement. |
+| storage-migration-status | READ_ONLY | Inspects storage layout and maintenance exclusion without opening or repairing a database. |
+| storage-restore | MUTATING | Verifies and retains a backup before activating it in an operationally fresh project. Existing operational state requires explicit --replace-active, which independently retains and archives outgoing authority before activation; failed restore evidence and maintenance exclusion are retained. |
+| storage-restore-resume | MUTATING | Adopts an exact dead local maintenance owner and resumes restore. Incomplete snapshots and prior rebuild intents are retained before rebuilding from bound source; completed preparation requires source parity/domain validation. Use --replace-active for preparation or publication replacement recovery. Conflicting intents and retained handoff locks remain refused. |
+| storage-rollback | MUTATING | Conditionally restores preserved source before native writes, retaining original native bytes and validating every task with the supported pinned legacy target before release. Failures retain exclusion; post-write restoration is refused. |
+| storage-rollback-resume | MUTATING | Resumes recorded rollback preparation, staging or publication under exact dead-owner adoption, revalidates native/source locations, and validates every task with the pinned target before release. Unbound attempts remain refused. |
 | task-abandon | MUTATING | Explicitly abandons an active non-terminal task; records append-only evidence and releases claims without completion authority. |
-| task-migrate | MUTATING | Migrates a legacy 1.0 singleton task state layout into a task-namespaced layout. |
+| task-migrate | MUTATING | Migrates legacy singleton task state into SQLite with retained source and verified publication evidence. |
 | task-migrate-contract-bootstrap-repair | MUTATING | Migrates the exact legacy contract bootstrap repair marker by appending a bound migration event; the original marker and artifacts remain unchanged. |
 | task-recover | MUTATING | Caller-acknowledged recovery of a STALE or ABANDONED task; records durable state and releases effective write claims. |
 | task-repair-contract-bootstrap | MUTATING | Repairs the exact duplicate contract bootstrap defect without rewriting history; idempotent and append-only. |
 | task-repair-legacy-recovery | MUTATING | Migrates one recognized legacy OPERATOR_RECOVERY_RECORDED boundary event into the modern durable recovery representation (append-only; original event unchanged). |
 | task-resume | MUTATING | Reacquires a recovered task's write claims under project serialization and restores ordinary mutation authority. |
-| task-unlock | MUTATING | Removes an orphaned task lock file to recover an interrupted task. |
+| task-unlock | MUTATING | Releases a canonical SQLite operation lease to recover an interrupted task. |
 | update | MUTATING | Updates installed templates, discovery adapters, and canonical engineering guides to the latest version. |
 
 ### scope

package/docs/ARTIFACT_REFERENCE.md

@@ -1,6 +1,6 @@
 # ForgeLoop Artifact Reference
 
-This reference documents the canonical artifacts persisted in the `.forgeloop/` directory.
+This reference distinguishes each artifact's logical identity, canonical storage and portable export path. Operational task and session records are stored in `.forgeloop/state.sqlite`; project configuration, policy inputs and immutable attachment bytes remain files.
 
 All artifact schemas are defined in `schemas/*.schema.json`. Persisted artifact shapes are strictly bound to these schemas and validated during protocol transitions.
 
@@ -8,44 +8,57 @@ All artifact schemas are defined in `schemas/*.schema.json`. Persisted artifact
 
 ## 1. Artifact Registry Summary
 
+Historical path strings remain logical identities so existing hashed evidence
+can be resolved without rewriting its history. A logical task path does not
+promise that a live JSON or NDJSON file exists. Read operational payloads through
+the canonical CLI, integration API or MCP resources; portable files are produced
+by explicit exports.
+
+The registry retains `path` as the logical alias and adds `logicalPath`,
+`canonicalStorage` and `exportPath`. Project files have no database export path
+and are copied separately. Signature bundles use immutable content-addressed
+files bound by SQLite references; their portable bindings are in
+`export-index.json#attachments`. A historical signature path is emitted only
+when its verified legacy alias is bound to the exported statement.
+
 <!-- BEGIN FORGELOOP GENERATED: artifact-registry -->
 
-| Artifact File | Schema | Ownership | Mutability | Trust Role |
-| --- | --- | --- | --- | --- |
-| `task-state/<task-key>/task.json` | `task-descriptor` | Protocol Managed | Mutable Before Execution | Task Descriptor |
-| `task-state/<task-key>/contract.json` | `current-contract` | Agent Authored | Mutable Before Execution | Operational Specification |
-| `task-state/<task-key>/routing-result.json` | `routing-result` | Protocol Generated | Mutable On Reroute | Guide Routing Specification |
-| `task-state/<task-key>/preflight.json` | `preflight` | Protocol Generated | Overwritten On Preflight | Readiness Attestation |
-| `sources.json` | `source-registry` | Operator Or Agent | Mutable On Discovery | Source Attestation |
-| `task-state/<task-key>/events.ndjson` | `event` | Protocol Appended | Append Only | Audit Ledger |
-| `sessions/<session-id>.json` | `activation` | Protocol Generated | Overwritten On Activate | Session Marker |
-| `config.json` | `config` | Operator Or Agent | Mutable Configuration | Project Configuration |
-| `task-state/<task-key>/gates/<gate>.json` | `gate` | Agent Authored Or Reviewer | Overwritten On Gate Satisfaction | Gate Approval Attestation |
-| `task-state/<task-key>/work-state.json` | `work-state` | Protocol Managed | Atomic State Transitions | Canonical Lifecycle State |
-| `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 |
-| `task-state/<task-key>/recovery.json` | `task-recovery` | Protocol Generated | Recovery State Transitions | Task Recovery State |
-| `task-state/<task-key>/actions/action-<id>.json` | `action` | Protocol Managed | State Machine Transitions | External Action Provenance |
-| `task-state/<task-key>/approvals/approval-<id>.json` | `approval` | Protocol Managed | Append Decision Once | Action Approval Attestation |
-| `policy/capabilities.json` | `capability-policy` | Operator Or Agent | Mutable Configuration | Capability Policy Specification |
-| `task-state/<task-key>/evaluations/eval-<id>.json` | `trajectory-evaluation` | Protocol Compiled | Immutable Once Written | Trajectory Evaluation |
-| `task-state/<task-key>/structural-quality/baseline.json` | `structural-quality` | Protocol Compiled | Baseline Immutable After Execution | Structural Quality Evidence |
-| `task-state/<task-key>/usage.json` | `usage` | Actor Or Trusted Host | Overwritten On Usage Record | Informational Usage Telemetry |
-| `task-state/<task-key>/workspace-binding.json` | `workspace-binding` | Protocol Generated | Immutable After Bind | Workspace Identity Binding |
-| `task-state/<task-key>/handoffs/handoff-<id>.json` | `handoff-envelope` | Protocol Compiled | Immutable Once Written | Canonical Handoff Snapshot |
-| `task-state/<task-key>/responsibility.json` | `responsibility` | Agent Or Harness Constrained | Immutable During Pass | Responsibility Constraint |
-| `task-state/<task-key>/verification-scope.json` | `verification-scope` | Protocol Compiled | Recomputed On Scope Change | Verification Scope Plan |
-| `task-state/<task-key>/attestations/code-manifest.json` | `code-manifest` | Protocol Generated | Immutable Once Written | Content Integrity Snapshot |
-| `task-state/<task-key>/attestations/statement.json` | `in-toto-statement` | Protocol Compiled | Immutable Once Written | Code Attestation Statement |
-| `task-state/<task-key>/attestations/statement.sigstore.json` | `null` | External Signing Provider | External Immutable | External Signature Bundle |
-| `task-state/<task-key>/decisions/<decision-id>.json` | `semantic-decision` | Protocol Compiled | Immutable Once Written | Semantic Decision |
-| `task-state/<task-key>/test-utility.json` | `test-utility` | Protocol Compiled | Overwritten On Analysis | Non Evidence Test Analysis |
+| Logical Identity | Canonical Storage | Export Path | Schema | Ownership | Mutability | Trust Role |
+| --- | --- | --- | --- | --- | --- | --- |
+| `.forgeloop/task-state/<task-key>/task.json` | `.forgeloop/state.sqlite :: tasks.descriptor_json` | `.forgeloop/task-state/<task-key>/task.json` | `task-descriptor` | Protocol Managed | Mutable Before Execution | Task Descriptor |
+| `.forgeloop/task-state/<task-key>/contract.json` | `.forgeloop/state.sqlite :: task_artifacts (contract)` | `.forgeloop/task-state/<task-key>/contract.json` | `current-contract` | Agent Authored | Mutable Before Execution | Operational Specification |
+| `.forgeloop/task-state/<task-key>/routing-result.json` | `.forgeloop/state.sqlite :: task_artifacts (route)` | `.forgeloop/task-state/<task-key>/routing-result.json` | `routing-result` | Protocol Generated | Mutable On Reroute | Guide Routing Specification |
+| `.forgeloop/task-state/<task-key>/preflight.json` | `.forgeloop/state.sqlite :: task_artifacts (preflight)` | `.forgeloop/task-state/<task-key>/preflight.json` | `preflight` | Protocol Generated | Overwritten On Preflight | Readiness Attestation |
+| `.forgeloop/sources.json` | `.forgeloop/sources.json` | `Copied separately` | `source-registry` | Operator Or Agent | Mutable On Discovery | Source Attestation |
+| `.forgeloop/task-state/<task-key>/events.ndjson` | `.forgeloop/state.sqlite :: events` | `.forgeloop/task-state/<task-key>/events.ndjson` | `event` | Protocol Appended | Append Only | Audit Ledger |
+| `.forgeloop/sessions/<session-id>.json` | `.forgeloop/state.sqlite :: sessions` | `.forgeloop/sessions/<session-id>.json` | `activation` | Protocol Generated | Overwritten On Activate | Session Marker |
+| `.forgeloop/config.json` | `.forgeloop/config.json` | `Copied separately` | `config` | Operator Or Agent | Mutable Configuration | Project Configuration |
+| `.forgeloop/task-state/<task-key>/gates/<gate>.json` | `.forgeloop/state.sqlite :: task_artifacts (gate)` | `.forgeloop/task-state/<task-key>/gates/<gate>.json` | `gate` | Agent Authored Or Reviewer | Overwritten On Gate Satisfaction | Gate Approval Attestation |
+| `.forgeloop/task-state/<task-key>/work-state.json` | `.forgeloop/state.sqlite :: tasks.state_json` | `.forgeloop/task-state/<task-key>/work-state.json` | `work-state` | Protocol Managed | Atomic State Transitions | Canonical Lifecycle State |
+| `.forgeloop/task-state/<task-key>/continuity.json` | `.forgeloop/state.sqlite :: task_artifacts (continuity)` | `.forgeloop/task-state/<task-key>/continuity.json` | `continuity` | Agent Or Harness | Mutable Handoff Notes | Non Evidence Handoff |
+| `.forgeloop/task-state/<task-key>/execution-receipt.json` | `.forgeloop/state.sqlite :: task_artifacts (receipt)` | `.forgeloop/task-state/<task-key>/execution-receipt.json` | `execution-receipt` | Protocol Compiled | Atomic Compilation | Evidence Compilation |
+| `.forgeloop/task-state/<task-key>/executions/exec-<id>.json` | `.forgeloop/state.sqlite :: executions` | `.forgeloop/task-state/<task-key>/executions/exec-<id>.json` | `execution` | Protocol Executed | Immutable Once Written | Execution Provenance |
+| `.forgeloop/policy/rules.json` | `.forgeloop/policy/rules.json` | `Copied separately` | `policy-rules` | Operator Or Agent | Mutable Configuration | Policy Specification |
+| `.forgeloop/policy/discovery.json` | `.forgeloop/policy/discovery.json` | `Copied separately` | `policy-discovery` | Protocol Generated | Mutable On Discovery | Discovered Policy Specification |
+| `.forgeloop/policy/baseline.json` | `.forgeloop/policy/baseline.json` | `Copied separately` | `policy-baseline` | Protocol Generated Or Operator | Monotonic Ratchet Down | Brownfield Baseline |
+| `.forgeloop/policy/policy.lock` | `.forgeloop/policy/policy.lock` | `Copied separately` | `policy-lock` | Protocol Generated | Atomic Digest Compilation | Policy Integrity Lock |
+| `.forgeloop/task-state/<task-key>/policy-snapshot.json` | `.forgeloop/state.sqlite :: task_artifacts (policySnapshot)` | `.forgeloop/task-state/<task-key>/policy-snapshot.json` | `policy-snapshot` | Protocol Generated | Mutable Before Execution | Task Policy Attestation |
+| `.forgeloop/task-state/<task-key>/recovery.json` | `.forgeloop/state.sqlite :: task_artifacts (recovery)` | `.forgeloop/task-state/<task-key>/recovery.json` | `task-recovery` | Protocol Generated | Recovery State Transitions | Task Recovery State |
+| `.forgeloop/task-state/<task-key>/actions/action-<id>.json` | `.forgeloop/state.sqlite :: actions` | `.forgeloop/task-state/<task-key>/actions/action-<id>.json` | `action` | Protocol Managed | State Machine Transitions | External Action Provenance |
+| `.forgeloop/task-state/<task-key>/approvals/approval-<id>.json` | `.forgeloop/state.sqlite :: approvals` | `.forgeloop/task-state/<task-key>/approvals/approval-<id>.json` | `approval` | Protocol Managed | Append Decision Once | Action Approval Attestation |
+| `.forgeloop/policy/capabilities.json` | `.forgeloop/policy/capabilities.json` | `Copied separately` | `capability-policy` | Operator Or Agent | Mutable Configuration | Capability Policy Specification |
+| `.forgeloop/task-state/<task-key>/evaluations/eval-<id>.json` | `.forgeloop/state.sqlite :: task_artifacts (evaluation)` | `.forgeloop/task-state/<task-key>/evaluations/eval-<id>.json` | `trajectory-evaluation` | Protocol Compiled | Immutable Once Written | Trajectory Evaluation |
+| `.forgeloop/task-state/<task-key>/structural-quality/baseline.json` | `.forgeloop/state.sqlite :: task_artifacts (structuralQuality)` | `.forgeloop/task-state/<task-key>/structural-quality/baseline.json` | `structural-quality` | Protocol Compiled | Baseline Immutable After Execution | Structural Quality Evidence |
+| `.forgeloop/task-state/<task-key>/usage.json` | `.forgeloop/state.sqlite :: task_artifacts (usage)` | `.forgeloop/task-state/<task-key>/usage.json` | `usage` | Actor Or Trusted Host | Overwritten On Usage Record | Informational Usage Telemetry |
+| `.forgeloop/task-state/<task-key>/workspace-binding.json` | `.forgeloop/state.sqlite :: task_artifacts (workspaceBinding)` | `.forgeloop/task-state/<task-key>/workspace-binding.json` | `workspace-binding` | Protocol Generated | Immutable After Bind | Workspace Identity Binding |
+| `.forgeloop/task-state/<task-key>/handoffs/handoff-<id>.json` | `.forgeloop/state.sqlite :: task_artifacts (handoff)` | `.forgeloop/task-state/<task-key>/handoffs/handoff-<id>.json` | `handoff-envelope` | Protocol Compiled | Immutable Once Written | Canonical Handoff Snapshot |
+| `.forgeloop/task-state/<task-key>/responsibility.json` | `.forgeloop/state.sqlite :: task_artifacts (responsibility)` | `.forgeloop/task-state/<task-key>/responsibility.json` | `responsibility` | Agent Or Harness Constrained | Immutable During Pass | Responsibility Constraint |
+| `.forgeloop/task-state/<task-key>/verification-scope.json` | `.forgeloop/state.sqlite :: task_artifacts (verificationScope)` | `.forgeloop/task-state/<task-key>/verification-scope.json` | `verification-scope` | Protocol Compiled | Recomputed On Scope Change | Verification Scope Plan |
+| `.forgeloop/task-state/<task-key>/attestations/code-manifest.json` | `.forgeloop/state.sqlite :: task_artifacts (attestation)` | `.forgeloop/task-state/<task-key>/attestations/code-manifest.json` | `code-manifest` | Protocol Generated | Immutable Once Written | Content Integrity Snapshot |
+| `.forgeloop/task-state/<task-key>/attestations/statement.json` | `.forgeloop/state.sqlite :: task_artifacts (attestation)` | `.forgeloop/task-state/<task-key>/attestations/statement.json` | `in-toto-statement` | Protocol Compiled | Immutable Once Written | Code Attestation Statement |
+| `.forgeloop/task-state/<task-key>/attestations/statement.sigstore.json` | `.forgeloop/state.sqlite :: attachment_references` | `.forgeloop/attachments/objects/<sha256>` | `null` | External Signing Provider | External Immutable | External Signature Bundle |
+| `.forgeloop/task-state/<task-key>/decisions/<decision-id>.json` | `.forgeloop/state.sqlite :: task_artifacts (decision)` | `.forgeloop/task-state/<task-key>/decisions/<decision-id>.json` | `semantic-decision` | Protocol Compiled | Immutable Once Written | Semantic Decision |
+| `.forgeloop/task-state/<task-key>/test-utility.json` | `.forgeloop/state.sqlite :: task_artifacts (testUtility)` | `.forgeloop/task-state/<task-key>/test-utility.json` | `test-utility` | Protocol Compiled | Overwritten On Analysis | Non Evidence Test Analysis |
 
 <!-- END FORGELOOP GENERATED: artifact-registry -->
 

package/docs/CLI_REFERENCE.md

@@ -18,6 +18,146 @@ Commands that support structured machine-readable output document `--json` in th
 
 <!-- END FORGELOOP GENERATED: cli-common-options -->
 
+## Storage maintenance
+
+### `storage-migration-status`
+
+Inspects the bootstrap storage layout and retained maintenance ownership even
+when ordinary commands are excluded. It neither opens nor validates the
+database, removes an exclusion, nor proves that its owner is alive or dead.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-migration-status:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--json`: emit bootstrap storage layout and retained maintenance ownership
+
+<!-- END FORGELOOP GENERATED: cli:storage-migration-status:options -->
+
+### `storage-migration-resume`
+
+Requires externally excluded writers and the exact retained dead local owner UUID reported by `storage-migration-status`. Continues verified STAGED, ARCHIVING or ARCHIVED publication, or verifies PUBLISHED current state without restoration. Verified unpublished staging can be retained and rebuilt. Unrecorded capture, unbound candidate files and interrupted owner handoffs remain refused.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-migration-resume:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--destination <path>`: retained migration directory relative to the project
+- `--expected-owner <uuid>`: exact retained maintenance owner reported by storage-migration-status
+- `--writers-quiesced`: assert that all writers, including older clients, have been externally stopped
+- `--reconcile-unbound-handoff`: preserve an unbound legacy handoff by atomic archival before resuming the exact dead owner
+- `--json`: emit recovery verification metadata
+
+<!-- END FORGELOOP GENERATED: cli:storage-migration-resume:options -->
+
+### `storage-rollback-resume`
+
+Resume a recorded source rollback publication under an exact dead local maintenance owner. Stop and exclude all writers; keep native writes excluded. The clean supported legacy target is validated before owner adoption. Actual source/native locations, captured bytes, independent backup and owner history are revalidated before operation journals change. Target validation must pass for every task before maintenance release.
+
+```bash
+forgeloop storage-rollback-resume --path <project> --destination <retained-migration> --expected-owner <uuid> --legacy-root <clean-supported-checkout> --writers-quiesced --native-writes-excluded --json
+```
+
+Recorded `PREPARING`/`READY` preparation and staging journals, and `SWITCHING`, `NATIVE_RETAINED` and `RESTORED` publication journals are supported. Incomplete staging copies are retained before rebuilding from verified captured source. Unrecorded directories, remote/live owners and ambiguous bytes are refused and retained for reconciliation. No deletion or replacement of retained source/native backups is authorized by failure.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-rollback-resume:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--expected-owner <uuid>`: exact retained dead local owner reported by storage-migration-status
+- `--destination <path>`: retained migration with recorded rollback preparation, staging or publication
+- `--legacy-root <path>`: clean supported pinned legacy checkout used for actual target validation
+- `--writers-quiesced`: assert that all writers, including older clients, have been externally stopped and excluded
+- `--native-writes-excluded`: assert that native writes have been excluded since migration; snapshot equality alone does not prove this
+- `--json`: emit restoration and target-validation metadata
+
+<!-- END FORGELOOP GENERATED: cli:storage-rollback-resume:options -->
+
+### `storage-rollback`
+
+Conditionally restore the preserved legacy source before any native writes have been accepted. Stop and exclude every writer, including old clients and background integrations. Inventory the clients and retain their exclusion throughout validation. Snapshot equality does not prove that no native writes occurred: `--native-writes-excluded` is an explicit operator assertion about the entire interval since migration. If native writes occurred, use a verified reverse export for the exact target version or forward repair instead.
+
+```bash
+forgeloop storage-rollback --path <project> --destination <retained-migration> --legacy-root <clean-supported-checkout> --writers-quiesced --native-writes-excluded --json
+```
+
+The supported validator checkout is the clean tracked Git commit `ee9ce11123d4e728d3dbc92f5d62d4bf41bb79c5`. Other target commits are refused. The command validates that target before acquiring maintenance, revalidates retained source and unchanged native authority, backs up native database and referenced attachment bytes, stages captured source, retains original native files by rename, and publishes exact source roots. It runs the pinned legacy CLI against every retained task and checks the task catalog before allowing maintenance release. The command executes Git and the explicitly supplied target CLI locally.
+
+Original native files, independent backups, captured source, inventories and validation receipts are retained. No automatic disposal occurs. On failure, keep all writers excluded and inspect maintenance owner and retained operation state. A failed attempt is not authorization to delete exclusion or retry over retained paths. Use `storage-rollback-resume` only for recorded preparation, staging or publication states. Unbound attempts remain refused; the original migration resume command must not be used to recover rollback operations.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-rollback:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--destination <path>`: retained published migration directory relative to the project
+- `--legacy-root <path>`: clean supported pinned legacy checkout used for actual target validation
+- `--writers-quiesced`: assert that all writers, including older clients, have been externally stopped and excluded
+- `--native-writes-excluded`: assert that native writes have been excluded since migration; snapshot equality alone does not prove this
+- `--json`: emit restoration and target-validation metadata
+
+<!-- END FORGELOOP GENERATED: cli:storage-rollback:options -->
+
+### `storage-migrate`
+
+Initial migration requires a new retained destination and externally stopped writers, including older clients. It validates and retains legacy sources, archives operational files, activates SQLite, and verifies current state. Failed attempts retain maintenance exclusion and evidence. Resume supports verified publication stages and identified unpublished staging; unrecorded capture and unbound candidate files remain refused.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-migrate:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--destination <path>`: new retained migration directory relative to the project; missing parent directories are created
+- `--writers-quiesced`: assert that all writers, including older clients, have been externally stopped
+- `--json`: emit migration publication and verification metadata
+
+<!-- END FORGELOOP GENERATED: cli:storage-migrate:options -->
+
+### `storage-restore-resume`
+
+Resumes restore after confirming that its exact retained local owner is dead. Requires externally excluded writers. Partial snapshots and prior rebuild intents are retained before rebuilding from verified source; completed preparation must pass source parity and domain validation. Conflicting intent records, unbound objects and changed preterminal databases remain refused. Terminal verification preserves accepted later work.
+
+```bash
+forgeloop storage-restore-resume --path /path/to/project --operation <restore-uuid> --expected-owner <owner-uuid> --writers-quiesced --json
+```
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-restore-resume:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--operation <uuid>`: exact retained restore journal operation UUID
+- `--expected-owner <uuid>`: exact retained maintenance owner UUID
+- `--replace-active`: explicitly select active replacement with retained outgoing authority
+- `--writers-quiesced`: assert that all writers have been externally stopped
+- `--json`: emit restore recovery metadata
+
+<!-- END FORGELOOP GENERATED: cli:storage-restore-resume:options -->
+
+### `storage-restore`
+
+Restores an attachment-inclusive backup into a project with no existing operational state. Requires explicit exclusion of all writers. Retains an independent snapshot and restore journal; failed operations keep maintenance exclusion. Active-project replacement is not supported yet.
+
+```bash
+forgeloop storage-restore --path /path/to/fresh-project --source /path/to/verified-backup --writers-quiesced --json
+```
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-restore:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--source <path>`: verified attachment-inclusive backup directory; absolute or relative to the target project
+- `--replace-active`: explicitly select active replacement with retained outgoing authority
+- `--writers-quiesced`: assert that all writers have been externally stopped
+- `--json`: emit restore activation metadata
+
+<!-- END FORGELOOP GENERATED: cli:storage-restore:options -->
+
+### `storage-backup`
+
+Creates a database-only backup of an existing canonical SQLite project. The
+destination is relative to the project, its parent must exist, and an existing
+destination is never replaced. External attachments are not included.
+
+<!-- BEGIN FORGELOOP GENERATED: cli:storage-backup:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--destination <path>`: new backup file or attachment-inclusive directory relative to the project; parent directory must exist
+- `--include-attachments`: create a new backup directory including all canonically referenced attachment bytes
+- `--json`: emit backup metadata
+
+<!-- END FORGELOOP GENERATED: cli:storage-backup:options -->
+
 ## Semantic decision projections
 
 ### `decision-status`
@@ -187,10 +327,10 @@ error codes. Default output and default JSON remain unchanged.
 
 | Category | Commands |
 | --- | --- |
+| **Setup & Maintenance** | [`storage-restore-resume`](#storage-restore-resume), [`storage-restore`](#storage-restore), [`storage-migration-status`](#storage-migration-status), [`storage-migration-resume`](#storage-migration-resume), [`storage-rollback`](#storage-rollback), [`storage-rollback-resume`](#storage-rollback-resume), [`storage-migrate`](#storage-migrate), [`storage-backup`](#storage-backup), [`contract-revise`](#contract-revise), [`init`](#init), [`index-setup`](#index-setup), [`index-start`](#index-start), [`index-stop`](#index-stop), [`index-rebuild`](#index-rebuild), [`update`](#update), [`checkpoint-revalidate`](#checkpoint-revalidate), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock), [`task-recover`](#task-recover), [`task-abandon`](#task-abandon), [`task-repair-contract-bootstrap`](#task-repair-contract-bootstrap), [`task-migrate-contract-bootstrap-repair`](#task-migrate-contract-bootstrap-repair), [`task-repair-legacy-recovery`](#task-repair-legacy-recovery), [`task-resume`](#task-resume) |
 | **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`decision-status`](#decision-status), [`decision-show`](#decision-show), [`context-plan`](#context-plan), [`model-route`](#model-route), [`semantic-plan`](#semantic-plan), [`test-inventory`](#test-inventory), [`test-utility`](#test-utility), [`test-prune-plan`](#test-prune-plan), [`doctor`](#doctor), [`index-status`](#index-status), [`search`](#search), [`metrics`](#metrics), [`usage-record`](#usage-record), [`efficiency`](#efficiency), [`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) |
 | **Verification & Completion** | [`test-prune-probe`](#test-prune-probe), [`quality-baseline`](#quality-baseline), [`quality-verify`](#quality-verify), [`quality-status`](#quality-status), [`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), [`verify-scope`](#verify-scope) |
 | **Lifecycle & State** | [`discover`](#discover), [`contract-create`](#contract-create), [`gate-record`](#gate-record), [`gate-revalidate`](#gate-revalidate), [`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) |
-| **Setup & Maintenance** | [`contract-revise`](#contract-revise), [`init`](#init), [`index-setup`](#index-setup), [`index-start`](#index-start), [`index-stop`](#index-stop), [`index-rebuild`](#index-rebuild), [`update`](#update), [`checkpoint-revalidate`](#checkpoint-revalidate), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock), [`task-recover`](#task-recover), [`task-abandon`](#task-abandon), [`task-repair-contract-bootstrap`](#task-repair-contract-bootstrap), [`task-migrate-contract-bootstrap-repair`](#task-migrate-contract-bootstrap-repair), [`task-repair-legacy-recovery`](#task-repair-legacy-recovery), [`task-resume`](#task-resume) |
 | **Cross-Harness Continuity** | [`continuity`](#continuity), [`record-continuity`](#record-continuity), [`reconcile-continuity`](#reconcile-continuity), [`clear-continuity`](#clear-continuity), [`handoff-create`](#handoff-create), [`handoff-list`](#handoff-list), [`handoff-show`](#handoff-show) |
 | **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) |
@@ -884,7 +1024,7 @@ Reports the public compatibility handshake required by external ForgeLoop harnes
 
 - **Example**:
 
-  <!-- FORGELOOP EXAMPLE: cli-reference:protocol-info | exit=0 | json.commands.0.name=protocol-info -->
+  <!-- FORGELOOP EXAMPLE: cli-reference:protocol-info | exit=0 | json.protocolVersion=1 | json.features.operationalStorage.sqlite.format=sqlite -->
   ```bash
   forgeloop protocol-info --json
   ```
@@ -896,7 +1036,7 @@ Initializes ForgeLoop in a target repository.
 
 - **Purpose**: Installs canonical instruction templates under `.forgeloop/kit/`, creates discovery shims at root, and prepares `.forgeloop/`.
 - **When to use**: Once when onboarding a new repository to ForgeLoop.
-- **Mutation**: Writes `.forgeloop/kit/`, `.forgeloop/forgeloop.gitignore`, `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/project-loop.mdc`, `.github/copilot-instructions.md`.
+- **Mutation**: Writes `.forgeloop/kit/`, `.forgeloop/.gitignore`, `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/project-loop.mdc`, `.github/copilot-instructions.md`.
 - **Options**:
 
 <!-- BEGIN FORGELOOP GENERATED: cli:init:options -->
@@ -2410,6 +2550,8 @@ Migrates a legacy 1.0 single-task `.forgeloop/` layout into a namespaced task di
 <!-- BEGIN FORGELOOP GENERATED: cli:task-migrate:options -->
 
 - `--path <directory>`: target project directory (default: current directory)
+- `--destination <path>`: retained source and publication evidence destination
+- `--writers-quiesced`: confirm all legacy writers are stopped and excluded
 - `--dry-run`: show planned migration actions without moving files
 - `--json`: emit structured output as JSON
 
@@ -2440,6 +2582,8 @@ protocol version.
 <!-- BEGIN FORGELOOP GENERATED: cli:migrate-protocol:options -->
 
 - `--path <directory>`: target project directory (default: current directory)
+- `--destination <path>`: retained source and publication evidence destination
+- `--writers-quiesced`: confirm all legacy writers are stopped and excluded
 - `--to <protocolVersion>`: target supported protocol version
 - `--dry-run`: show migration actions without writing or deleting artifacts
 - `--json`: emit structured migration result as JSON

package/docs/DOCUMENTATION_GUIDE.md

@@ -233,14 +233,16 @@ not the canonical protocol diagram. The typed Archify workflow under
 `docs/diagrams/` remains the canonical lifecycle architecture source, with
 generated outputs under `docs/assets/diagrams/`; the CLI-only persistent search
 transport is explained by `docs/PERSISTENT_SEARCH_TRANSPORT.md`. The current
-repository-only assets are `docs/assets/forgeloop-architecture.svg` and
-`docs/assets/forgeloop-lifecycle-animated.svg`; neither is a package file.
+repository-only assets are `docs/assets/forgeloop-architecture.png`, the
+alternate [architecture SVG](./assets/forgeloop-architecture.svg), and
+`docs/assets/forgeloop-lifecycle-animated.svg`; none is a package file.
 
 The README hero is intentionally GitHub-repository-only:
 
-- `README.md` references `docs/assets/forgeloop-architecture.svg` for the hero
+- `README.md` references `docs/assets/forgeloop-architecture.png` for the hero
   and `docs/assets/forgeloop-lifecycle-animated.svg` for the looping overview;
-  both are repository-only and excluded from the npm package.
+  both are repository-only and excluded from the npm package. The architecture
+  SVG remains available as a repository-only alternate.
 - `tests/package.test.js` asserts those exclusions so they cannot be silently
   re-included.
 - The packaged README is therefore not self-contained for that relative hero

package/docs/GETTING_STARTED.md

@@ -6,7 +6,7 @@ This guide walks through your first complete task with ForgeLoop from initializa
 
 ## 1. What is ForgeLoop?
 
-ForgeLoop is a portable, vendor-neutral engineering protocol for AI-assisted coding and automated workflows. It turns a task outcome into:
+ForgeLoop is a vendor-neutral engineering protocol for AI-assisted coding and automated workflows. It turns a task outcome into:
 
 - **A structured contract** (`.forgeloop/task-state/<taskKey>/contract.json`);
 - **Deterministic guide routing** based on declared work type, surfaces, and risks;
@@ -108,7 +108,7 @@ and numeric limits.
 
 ## 2. Prerequisites
 
-- **Node.js**: version 20 or higher (`node -v`)
+- **Node.js**: version 24.19.0 or higher (`node -v`), with built-in `node:sqlite`
 - **npm**: standard npm toolchain
 
 ---
@@ -281,7 +281,7 @@ forgeloop route \
   --json
 ```
 
-This writes `.forgeloop/task-state/<taskKey>/routing-result.json` referencing selected guides (e.g. `clean`, `test`, `security`, `design`, `accessibility`).
+This records selected guides (e.g. `clean`, `test`, `security`, `design`, `accessibility`) in SQLite. `.forgeloop/task-state/<taskKey>/routing-result.json` is the logical artifact identity and explicit export path. Native mutations require a selected task; create one first or select an existing task.
 
 ---
 

package/docs/PACKAGE_CONTENTS.md

@@ -1,6 +1,6 @@
 # Core npm package contents
 
-This page describes the intentional boundary of the published
+This page describes the intentional boundary of the privately delivered
 `@cassiomc1/forgeloop` package. The [`files`](../package.json) list in
 `package.json` is the packaging source of truth, while the repository's
 `tests/package.test.js` and clean-room `scripts/package_smoke.mjs` checks keep
@@ -55,7 +55,7 @@ The published tarball includes the following consumer-facing groups:
   not additional package guides. The package does not install or invoke
   framework, compiler, build, package-manager, or database tooling.
 - **Initialization material:** the root protocol and integration documents,
-  legal notices, the target profile template, and every path listed by
+  the PolyForm Noncommercial license, third-party notices, the target profile template, and every path listed by
   `src/core/templates.js`. These files are read by `init` and `update`, so
   they are part of the executable consumer contract even when a document is
   marked deprecated in the documentation manifest.
@@ -94,8 +94,8 @@ The tarball intentionally omits repository-only material:
   Harness-specific Agent Skill installation directories and Skill caches are
   not packaged.
 - local `.forgeloop` state, task ledgers, locks, transactions, and execution
-  receipts (the `.forgeloop/forgeloop.gitignore` template is the sole
-  exception);
+  receipts; the target `.forgeloop/.gitignore` is generated from an inline
+  runtime template and no `.forgeloop/*` files are packaged;
 - raw or aggregate benchmark results, package archives, and release train
   contracts;
 - the Ripwire retrieval benchmark runner, cases, and fixture corpus; those
@@ -104,9 +104,11 @@ The tarball intentionally omits repository-only material:
 - historical release plans and retired MCP adapter sources; the MCP adapter
   is published as its own package;
 - the repository-only README hero assets
-  `docs/assets/forgeloop-architecture.svg` and
-  `docs/assets/forgeloop-lifecycle-animated.svg`. They are referenced by the
-  repository README and are intentionally outside the core tarball.
+  `docs/assets/forgeloop-architecture.png`,
+  `docs/assets/forgeloop-architecture.svg`, and
+  `docs/assets/forgeloop-lifecycle-animated.svg`. The PNG and animated SVG are
+  referenced by the repository README; all three are intentionally outside
+  the core tarball.
 - the execution PoC, its audit, and its evidence package. Packaged README and
   index links to this repository-only material use GitHub URLs so they remain
   truthful for npm consumers.
@@ -134,9 +136,8 @@ exercises the CLI, public Integration API, initialization, schemas, and the
 Structural Quality documentation's packaged diagram references. The
 package-boundary tests also assert
 that every registered guide path, including all language specialists, is
-present in the candidate. The tag-triggered publication
-workflow
-runs the same smoke gate before `npm publish --provenance --access public`.
-Publication therefore remains owned by the trusted GitHub Actions OIDC
-workflow; local package inspection proves the candidate boundary but does not
-publish it.
+present in the candidate. The manual, explicitly authorized publication workflow runs the same smoke
+gate before `npm publish --provenance --access public`.
+Publication therefore remains owned by the authorized manual GitHub Actions
+workflow and uses public npm access for the core package; local package inspection proves the
+candidate boundary but does not publish it.