@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/docs/ADVISORY_CONTEXT.md

@@ -196,3 +196,28 @@ opt-in real-binary smoke test, and the retrieval benchmark. A real binary and
 its exact version must be qualified by the host; ForgeLoop does not install or
 discover Ripwire and does not treat an unavailable smoke test as proof of
 interoperability.
+
+## OpenSrc adapter
+
+ForgeLoop includes an optional host-injected adapter for
+[OpenSrc](https://github.com/vercel-labs/opensrc) external package and
+repository source context. The adapter is deliberately outside the default
+runtime: the host must provide an absolute executable path, an exact expected
+version, a dedicated absolute cache root outside the project, and an explicit
+source allowlist, then register the returned provider under the `opensrc` key
+and invoke `recallAdvisoryContext` explicitly. Creating the provider performs
+no discovery, network access, process start, cache write, or lifecycle write.
+
+The adapter qualifies `<absolute-opensrc> --version` before every recall,
+resolves each configured source once through `opensrc path <source> --cwd
+<projectRoot>` with `shell: false` and `OPENSRC_HOME` set to the dedicated
+cache root, canonicalizes every returned path inside that cache, and searches
+resolved sources locally with bounded deterministic Node.js traversal (no
+`rg`, embeddings, or network search). It never exposes absolute cache paths,
+raw stderr, environment, or credentials, and source text stays inert bounded
+context under the standard advisory trust projection.
+
+See [OPENSRC_ADAPTER.md](OPENSRC_ADAPTER.md) for registration, limits, cache
+and network behavior, tests, and troubleshooting. `opensrc path` may contact
+registries or remotes and populate its own cache on miss; ForgeLoop persists
+nothing and never auto-recalls.

package/docs/AGENT_BROWSER_ADAPTER.md

@@ -0,0 +1,81 @@
+# Agent Browser Adapter
+
+ForgeLoop ships an optional, host-injected adapter for Vercel Labs
+`agent-browser`. It implements the existing provider-neutral Browser
+Verification contract; it is not canonical browser infrastructure and it does
+not create lifecycle evidence.
+
+## Installation ownership
+
+The host must provide an already-installed `agent-browser` executable and pass
+its absolute path to `createAgentBrowserVerificationProvider`. ForgeLoop never
+discovers a binary through `PATH`, installs or upgrades Agent Browser, installs
+Chrome, or runs `doctor --fix`.
+
+```js
+import {
+  createAgentBrowserVerificationProvider,
+  createForgeLoopContext,
+  runBrowserVerification,
+} from "@cassiomc1/forgeloop/integration";
+
+const provider = createAgentBrowserVerificationProvider({
+  executablePath: "/opt/agent-browser/bin/agent-browser",
+  expectedVersion: "0.38.1",
+});
+const runtimeContext = createForgeLoopContext({
+  browserVerificationProviders: { "agent-browser": provider },
+});
+```
+
+## Supported mapping
+
+The adapter maps `NAVIGATE`, `CLICK`, `FILL`, `PRESS`, and bounded polling for
+`WAIT_FOR` to Agent Browser commands. CSS locators are passed directly;
+TEXT, LABEL, and ROLE locators are resolved from one accessibility snapshot and
+ambiguity is `BLOCKED`. Assertions cover visibility, hidden state, text,
+value, attribute, URL, URL prefix, and title. Requested assertion order is
+preserved.
+
+## Security and lifecycle
+
+Each invocation probes the explicitly supplied executable version lazily, uses
+a fresh random session, runs in an adapter-owned temporary cwd, and closes the
+session in `finally`. Profiles, restore/state replay, CDP, auto-connect,
+plugins, init scripts, and ambient cloud/authentication variables are filtered.
+The target repository is never used as the Agent Browser cwd.
+
+ForgeLoop validates exact `http`/`https` origins. Agent Browser receives the
+corresponding hostname allowlist as defense in depth, while ForgeLoop remains
+authoritative for scheme, host, and port. Redirects outside the allowlist are
+rejected. Subprocess argv uses `shell: false`; stdout, stderr, time, and
+diagnostics are bounded, and abort/timeout sends bounded termination signals.
+
+## Screenshots and trust model
+
+`NEVER`, `ON_FAILURE`, and `ALWAYS` screenshot policies are supported. Screenshot
+bytes remain temporary; results expose only bounded PNG metadata, a SHA-256
+digest, and a portable `agent-browser/<verification>/<digest>.png` reference.
+
+The result is observation-only: `persisted: false`, `evidenceAuthority: NONE`,
+and no lifecycle, claim, completion, evidence, or next-action fields. Calling
+`runBrowserVerification` does not mutate ForgeLoop artifacts and a PASS is never
+auto-promoted to a check or completion.
+
+Command responses must use the complete `{success: true, data}` envelope and
+scalar observations are type-checked before assertions run. Missing or extra
+envelope fields, malformed observations, non-zero exits, unsupported versions,
+cancellation, timeout, and output overflow fail closed; process success alone
+never produces a PASS. Any internal test-only temporary-root override must stay
+outside the verification target; the public TypeScript API exposes only the
+host-selected executables.
+
+## Troubleshooting and limitations
+
+Use an absolute regular executable path and, when desired, set
+`expectedVersion` to the host-qualified version. A missing executable, version
+mismatch, timeout, malformed response, output overflow, locator ambiguity, or
+origin escape fails closed. The default test suite does not require Agent
+Browser, Chrome, network access, or a Node 24 runtime. An optional localhost
+smoke test is available only when explicitly enabled with
+`FORGELOOP_AGENT_BROWSER_E2E=1` and `FORGELOOP_AGENT_BROWSER_EXECUTABLE`.

package/docs/AGENT_BROWSER_VERIFICATION.md

@@ -0,0 +1,6 @@
+# Agent Browser Verification
+
+This page is a short navigation entry for the concrete optional adapter. See
+[`AGENT_BROWSER_ADAPTER.md`](./AGENT_BROWSER_ADAPTER.md) for host installation
+ownership, the public factory, command mapping, isolation, exact-origin policy,
+screenshots, troubleshooting, and the non-authoritative trust boundary.

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.13.0
+Package version: 2.0.0-rc.2
 
 ## Canonical loop
 
@@ -89,7 +89,7 @@ or `NOT_COMPARABLE` when evidence is absent or incompatible. See
 - Responsibility contracts constrain paths, checks, and frozen inputs; they do not prove identity or authorship.
 - Verification scope describes planned verification breadth. Attestation coverage proves content for a concrete revision. These are separate claims.
 - Attestation manifests exclude ForgeLoop protocol metadata and bind to the completion receipt and append-only ledger without circular references.
-- Verification commands are read-only. Signing is external; private keys and credentials are never persisted by ForgeLoop.
+- Verification command execution is external and provenance-bearing; ForgeLoop records the exact argv and result, while the authorized command may perform its declared effects. Signing is external; private keys and credentials are never persisted by ForgeLoop.
 
 ## Lifecycle
 
@@ -101,6 +101,7 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | --- | --- | --- |
 | adaptiveExecutionProfiles | 1 | yes |
 | advisoryContextProviders | 1 | yes |
+| auditUx | 1 | yes |
 | canonicalHandoffs | 2 | yes |
 | capabilityPolicy | 1 | yes |
 | codeAttestation | 1 | yes |
@@ -115,9 +116,12 @@ 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 |
 | responsibilityConstraints | 1 | yes |
+| semanticDecisionPlane | 1 | yes |
 | structuralQuality | 1 | yes |
 | structuredTrace | 1 | yes |
 | taskClaimRecovery | 1 | yes |
@@ -139,6 +143,8 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
   Integration-API-only, lazy, and opt-in. Provider results are not persisted by
   ForgeLoop and are never lifecycle state, evidence, authority, or executable
   instructions.
+- `providerExtensions` v1 is provider-neutral and
+  experimental. The generic provider registry remains internal and unexported.
 
 Protocol v1, schema v1, and Integration API v1 remain independent of these
 capability-family versions.
@@ -169,43 +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 |
-| 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 |
-| 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
 
@@ -248,6 +257,9 @@ capability-family versions.
 
 | Command | Mutation | Purpose |
 | --- | --- | --- |
+| context-plan | READ_ONLY | Compiles a bounded non-authoritative context plan from deterministic candidates. |
+| decision-show | READ_ONLY | Shows one persisted semantic decision artifact without performing a live request. |
+| decision-status | READ_ONLY | Reports the pinned semantic decision-plane configuration without exposing credentials. |
 | doctor | MUTATING | Diagnoses project health, discovers adapters, and optionally repairs missing template files. |
 | efficiency | READ_ONLY | Projects usage and timing efficiency, comparing only against a metadata-compatible local baseline. |
 | eval | MUTATING | Evaluates the current trajectory against a validated project-local reference scenario. |
@@ -255,12 +267,17 @@ capability-family versions.
 | index-status | READ_ONLY | Reports provider-neutral repository-index health, metadata, and owned-server status. |
 | inspect | READ_ONLY | Inspects target repository health, dirty files, active branch, and artifact freshness. |
 | metrics | READ_ONLY | Projects trajectory, action, execution, timing, and known usage metrics without mutating state. |
+| model-route | READ_ONLY | Projects a deterministic model-routing floor with advisory Jev escalation only. |
 | profile-interview | READ_ONLY | Optional interactive or dry-run interview to refine project profile facts. |
 | progress | READ_ONLY | Evaluates task progress across verification cycles and detects stalls deterministically. |
 | protocol-info | READ_ONLY | Reports versioning, lifecycle, command, guide, and public error compatibility metadata for external harnesses. |
 | reflect | READ_ONLY | Analyzes diagnostic and correction history deterministically for information gain, repeated failures, ineffective interventions, and oscillation. |
 | search | READ_ONLY | Searches the ForgeLoop repository index through the provider-neutral search contract. |
+| semantic-plan | READ_ONLY | Projects fail-closed failure triage, diagnosis priority, or review planning without authority. |
 | status | READ_ONLY | Displays current lifecycle phase, active checks, blockers, and artifact freshness bindings. |
+| test-inventory | READ_ONLY | Discovers tests deterministically and assigns stable semantic test IDs without pruning authority. |
+| test-prune-plan | READ_ONLY | Projects KEEP, PROBE_REMOVAL, or BLOCKED without deleting tests. |
+| test-utility | MUTATING | Persists non-evidence test utility analysis; never deletes tests or authorizes pruning. |
 | trace | READ_ONLY | Emits detailed structured task trace with provenance and artifact relationships. |
 | usage-record | MUTATING | Records actor-reported usage telemetry without treating it as verification evidence. |
 | validate-protocol | READ_ONLY | Validates end-to-end cryptographic freshness, fingerprint bindings, and ledger integrity. |
@@ -274,9 +291,13 @@ capability-family versions.
 | advance | MUTATING | Transitions the canonical lifecycle work state to an allowed target phase. |
 | clear-state | MUTATING | Removes work-state.json for the active task only, preserving sibling contract, routing, and ledger files. |
 | complete | MUTATING | Evaluates verification receipt coverage, gates, and ledger integrity to authorize task completion. |
+| contract-create | MUTATING | Persists a validated contract and materializes the first real lifecycle checkpoint. |
+| discover | MUTATING | Records the canonical initial discovery milestone for a newly created task. |
+| gate-record | MUTATING | Records a required pre-execution gate with ForgeLoop-owned artifact hashes. |
+| 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. |
@@ -304,17 +325,30 @@ capability-family versions.
 
 | Command | Mutation | Purpose |
 | --- | --- | --- |
+| checkpoint-revalidate | MUTATING | Revalidates a safe ROUTED checkpoint after repository-only drift without changing contract or route identity. |
+| contract-revise | MUTATING | Replaces an existing contract canonically before execution while preserving task identity and invalidating derived evidence. |
 | index-rebuild | MUTATING | Atomically rebuilds the repository index and restarts its owned watcher. |
 | index-setup | MUTATING | Provisions the pinned tgrep engine, builds the repository index, and starts its owned watcher. |
 | index-start | MUTATING | Starts the owned tgrep repository-index watcher after an index has been built. |
 | 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. |
-| task-migrate | MUTATING | Migrates a legacy 1.0 singleton task state layout into a task-namespaced layout. |
+| 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 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
@@ -343,6 +377,7 @@ capability-family versions.
 | record-terminal-result | MUTATING | Records external terminal result evidence (PUBLICATION or PRODUCTION_READINESS) into receipt. |
 | report | READ_ONLY | Emits a human-readable or structured JSON summary report of protocol state. |
 | run-check | EXTERNAL_EXECUTION | Runs an exact command, records the execution provenance artifact, and binds observed check evidence. |
+| test-prune-probe | EXTERNAL_EXECUTION | Runs only an isolated, fail-closed removal probe; never modifies the live worktree. |
 | validate-receipt | READ_ONLY | Validates schema conformance and cryptographic bounds of an execution receipt file. |
 | verify-scope | MUTATING | Resolves a provable changed, claimed, full, or unresolved verification boundary without launching checks. |
 

package/docs/AGENT_SKILL.md

@@ -0,0 +1,66 @@
+# ForgeLoop Agent Skill
+
+## Status
+
+ForgeLoop ships a generated, portable Agent Skill at
+[`skills/forgeloop/SKILL.md`](../skills/forgeloop/SKILL.md). It is operational
+guidance, not protocol authority, and it does not certify any particular agent
+harness.
+
+## Purpose and Architecture
+
+The documented precedence direction is:
+
+```text
+runtime protocol registries and validators
+        -> canonical protocol documentation
+        -> docs/AGENT_PROTOCOL_SUMMARY.md
+        -> generated Skill
+```
+
+The Skill generator itself reads the generated summary and runtime protocol
+metadata. It does not parse the canonical Markdown protocol documents.
+
+The Skill never becomes lifecycle, completion, evidence, claim, scheduler,
+provider, or installation authority.
+
+## Generation and Freshness
+
+Generation is deterministic, offline, and has no external Agent Skills
+dependency:
+
+```bash
+npm run summary:generate
+npm run skill:generate
+npm run summary:check
+npm run skill:check
+```
+
+The writer is bounded to the five known files under `skills/forgeloop/` and
+does not delete unknown files. Documentation checks run Skill freshness after
+Agent Protocol Summary freshness.
+
+## Compatibility
+
+The Skill follows the portable `skills/forgeloop/SKILL.md` convention with only
+`name` and `description` frontmatter. This is format compatibility, not
+behavioral certification for every external harness. Existing native
+`AGENTS.md`, `CLAUDE.md`, Cursor, and Copilot integration surfaces remain
+intact.
+
+## Safety Boundaries
+
+Agents must discover tasks first, follow `next`, respect claims, require
+preflight `READY`, preserve command provenance, distinguish `run-check` from
+`record-check`, use supported recovery, require `complete -> VALID`, and query
+`next` again for a terminal result. Tokens, credentials, private keys, and
+authorization headers must never be persisted in ForgeLoop artifacts.
+
+External Agent Skills tooling is not a ForgeLoop dependency and is not used in
+CI. ForgeLoop adds no runtime Skill installation or synchronization command.
+
+## Packaging
+
+The generated Skill, this document, and the bounded generator ship in the npm
+package as instruction/documentation content. They add no runtime dependency.
+Harness-specific installed copies and caches are not shipped.