@cassiomc1/forgeloop 1.12.0 → 1.14.0

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.12.0
+Package version: 1.14.0
 
 ## Canonical loop
 
@@ -19,6 +19,32 @@ Package version: 1.12.0
 6. Run forgeloop complete; accept completion only when the validator returns VALID.
 7. Run forgeloop next again and follow the returned lifecycle action to a terminal state or an explicit blocker.
 
+## Project evidence and guide routing
+
+- The canonical guide registry is `src/config/guides.json`; the .NET
+  specialist has guide ID `dotnet` and resolves to
+  `ENG/dotnet-aspnetcore-development-eng.md`.
+- Project evidence schema v1 recognizes
+  structurally parsed Flutter, SDK-style .NET, Node.js, Rust, C, C++, Java,
+  SQL, Go, TypeScript, PHP, and Swift project evidence. SQL remains a bounded
+  owned-file overlay, while same-root language identities compose. ASP.NET Core
+  and ABP are conditional overlays recorded as reasons on `dotnet`; they
+  are not standalone guide IDs, and route validation requires each overlay to
+  include `dotnet`.
+- Project detection is bounded by 256
+  manifests, 64 solution files,
+  1048576 bytes per manifest,
+  256 supporting source files,
+  524288 bytes per source file,
+  4096 visited directories, and
+  20000 visited entries. It skips
+  symlinks and configured generated/vendor directories; exhausted budgets fail
+  closed rather than producing unbounded discovery.
+- Task ownership discovery is a separate exhaustive operation. Task-list
+  filters and pagination project the validated discovery result and do not
+  remove ledger or recovery evidence. See `GUIDE_ROUTER.md` and
+  `docs/CLI_REFERENCE.md` for the operator-facing contracts.
+
 ## Adaptive execution profiles
 
 `complianceMode` controls how strongly project policy is enforced. The
@@ -63,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
 
@@ -75,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 |
@@ -89,9 +116,11 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | executionProfileContext | 1 | yes |
 | integrationApi | 1 | yes |
 | observabilityStability | n/a | 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 |
@@ -113,10 +142,39 @@ 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.
 
+## Guide registry
+
+| Guide | Path | Installable |
+| --- | --- | --- |
+| premium | ENG/premium-sites-studio-eng.md | yes |
+| clean | ENG/clean-code-eng.md | yes |
+| test | ENG/test-code-eng.md | yes |
+| security | ENG/sec-code-eng.md | yes |
+| design | ENG/design-code-eng.md | yes |
+| taste | ENG/taste-frontend-eng.md | yes |
+| performance | ENG/perf-code-eng.md | yes |
+| accessibility | ENG/accessibility-eng.md | yes |
+| games | ENG/games-code-design-web-eng.md | yes |
+| documentation | ENG/documentation-quality-eng.md | yes |
+| flutter | ENG/flutter-development-eng.md | yes |
+| dotnet | ENG/dotnet-aspnetcore-development-eng.md | yes |
+| nodejs | ENG/nodejs-backend-development-eng.md | yes |
+| rust | ENG/rust-development-eng.md | yes |
+| c | ENG/c-development-eng.md | yes |
+| cpp | ENG/cpp-development-eng.md | yes |
+| java | ENG/java-development-eng.md | yes |
+| sql | ENG/sql-development-eng.md | yes |
+| go | ENG/go-development-eng.md | yes |
+| typescript | ENG/typescript-development-eng.md | yes |
+| php | ENG/php-development-eng.md | yes |
+| swift | ENG/swift-development-eng.md | yes |
+
 ## Public artifact registry
 
 | Key | Scope | Path | Schema | Trust role |
@@ -146,10 +204,12 @@ capability-family versions.
 | 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 |
@@ -195,6 +255,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. |
@@ -202,12 +265,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. |
@@ -221,9 +289,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 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, 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. |
@@ -251,14 +323,19 @@ 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-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-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. |
@@ -290,6 +367,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.

package/docs/ARTIFACT_REFERENCE.md

@@ -44,6 +44,8 @@ All artifact schemas are defined in `schemas/*.schema.json`. Persisted artifact
 | `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 |
 
 <!-- END FORGELOOP GENERATED: artifact-registry -->
 
@@ -51,6 +53,99 @@ All artifact schemas are defined in `schemas/*.schema.json`. Persisted artifact
 
 ## 2. Canonical Artifact Specifications
 
+### 2.0 `semantic-decision`
+
+<!-- forgeloop-doc: schema=semantic-decision artifact=.forgeloop/task-state/<task-key>/decisions/<decision-id>.json -->
+
+Semantic decisions are advisory, fingerprint-bound projections. They do not
+authorize lifecycle transitions, evidence, ownership, installation, or
+completion.
+
+<!-- BEGIN FORGELOOP GENERATED: schema:semantic-decision -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `protocolVersion` *(number, required, const: 1)*
+- `taskId` *(string, required, minLength: 1)*
+- `decisionId` *(string, required, pattern: `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$`)*
+- `decisionKind` *(string, required, minLength: 1)*
+- `engine` *(string, required, const: `typesafe-jev`)*
+- `model` *(string, required, const: `jev-1.13.0`)*
+- `questionSetId` *(string, required, minLength: 1)*
+- `questionSetVersion` *(integer, required, minimum: 1)*
+- `questionSetFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+- `questionSet` *(object, optional)*
+  - `id` *(string, required, minLength: 1)*
+  - `version` *(integer, required, minimum: 1)*
+  - `decisionKind` *(string, required, minLength: 1)*
+  - `questions` *(object, required)*
+  - `fingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+  - `candidateIds` *(array<string>, optional)*
+  - `metadata` *(object, optional)*
+- `policyVersion` *(number, required, const: 1)*
+- `stateFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+- `taskStateFingerprint` *(string or null, optional)*
+- `semanticStateFingerprint` *(string or null, optional)*
+- `policyFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+- `repositoryFingerprint` *(string or object or null, optional)*
+- `contractFingerprint` *(string or null, optional)*
+- `routeFingerprint` *(string or null, optional)*
+- `verificationCycle` *(integer or null, optional)*
+- `candidateSetFingerprint` *(string or null, optional)*
+- `answers` *(object, required)*
+- `confidence` *(object, required)*
+- `decision` *(object, required)*
+- `usage` *(object, required)*
+  - `inputTokens` *(integer or null, required)*
+  - `outputTokens` *(integer or null, required)*
+  - `reportedBy` *(string, required, enum: `PROVIDER`, `HOST`, `UNKNOWN`)*
+- `latencyMs` *(integer or null, optional)*
+- `authority` *(string, required, const: `SEMANTIC_DECISION`)*
+- `evidenceAuthority` *(string, required, const: `NONE`)*
+- `lifecycleAuthority` *(boolean, required, const: false)*
+- `completionAuthority` *(boolean, required, const: false)*
+- `ownershipAuthority` *(boolean, required, const: false)*
+- `installationAuthority` *(boolean, required, const: false)*
+- `recordedAt` *(string, required, minLength: 1)*
+
+<!-- END FORGELOOP GENERATED: schema:semantic-decision -->
+
+### 2.0.1 `test-utility`
+
+<!-- forgeloop-doc: schema=test-utility artifact=.forgeloop/task-state/<task-key>/test-utility.json -->
+
+Non-evidence test inventory and utility analysis. It never authorizes deletion
+or completion.
+
+<!-- BEGIN FORGELOOP GENERATED: schema:test-utility -->
+
+- `schemaVersion` *(number, required, const: 1)*
+- `protocolVersion` *(number, required, const: 1)*
+- `taskId` *(string, required, minLength: 1)*
+- `generatedAt` *(string, required, minLength: 1)*
+- `inventoryFingerprint` *(string, required, pattern: `^[a-f0-9]{64}$`)*
+- `semanticStatus` *(string, required, enum: `PROVIDER_REPORTED`, `UNAVAILABLE`, `NOT_REQUESTED`)*
+- `decisionId` *(string, optional, pattern: `^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$`)*
+- `semanticDecisionFingerprint` *(string, optional, pattern: `^[a-f0-9]{64}$`)*
+- `decisionIds` *(array<string>, optional)*
+- `semanticDecisionFingerprints` *(array<string>, optional)*
+- `tests` *(array<object>, required)*
+  - `testId` *(string, required, pattern: `^test-[a-f0-9]{24}$`)*
+  - `file` *(string, required, minLength: 1)*
+  - `framework` *(string, required, minLength: 1)*
+  - `suite` *(string, optional)*
+  - `name` *(string, required, minLength: 1)*
+  - `line` *(integer, optional, minimum: 1)*
+  - `sourceSummary` *(string, optional)*
+  - `targets` *(array<string>, optional)*
+  - `runtimeMs` *(number,null, optional, minimum: 0)*
+  - `uniqueBranches` *(integer,null, optional, minimum: 0)*
+  - `classification` *(string, required, enum: `KEEP_REQUIRED`, `KEEP_UNIQUE`, `KEEP_RISK_GUARD`, `KEEP_AUTHORITY_BOUNDARY`, `KEEP_RECOVERY_INVARIANT`, `KEEP_RELEASE_SMOKE`, `KEEP_MIGRATION_COMPATIBILITY`, `KEEP_PLATFORM_BEHAVIOR`, `KEEP_DOCUMENTATION_VALUE`, `KEEP_INTEGRATION_GUARD`, `OBSOLETE_CANDIDATE`, `FLAKY_LOW_SIGNAL`, `EXPENSIVE_LOW_SIGNAL`, `UNKNOWN`, `REDUNDANT_CANDIDATE`)*
+  - `recommendation` *(string, required, enum: `KEEP`, `REWRITE`, `PROBE_REMOVAL`, `BLOCKED`, `REVIEW`)*
+  - `protected` *(boolean, required)*
+  - `signals` *(object, optional)*
+
+<!-- END FORGELOOP GENERATED: schema:test-utility -->
+
 ### 2.1 `task-state/<taskKey>/contract.json`
 
 <!-- forgeloop-doc: schema=current-contract artifact=.forgeloop/task-state/<task-key>/contract.json -->
@@ -178,6 +273,11 @@ Readiness attestation evaluated prior to implementation.
 
 Discovered repository facts, platforms, runtimes, and dependencies.
 
+Built-in `contract-preset:documentation`, `contract-preset:bug`,
+`contract-preset:feature`, and `contract-preset:release` references are
+ForgeLoop-owned provenance and do not require an entry in this registry. Every
+other contract source reference still requires a valid registry entry.
+
 #### Canonical Fields
 
 <!-- BEGIN FORGELOOP GENERATED: schema:source-registry -->
@@ -252,6 +352,14 @@ Local ForgeLoop configuration settings and policy bindings.
 - `policy` *(string, optional, minLength: 1)*
 - `requiredGates` *(array<string>, optional)*
 - `requiredEvidence` *(array<string>, optional)*
+- `decisionEngine` *(object, optional)*
+  - `required` *(boolean, required, const: true)*
+  - `provider` *(string, required, const: `typesafe-jev`)*
+  - `model` *(string, required, const: `jev-1.13.0`)*
+  - `policyVersion` *(number, required, const: 1)*
+  - `requestTimeoutMs` *(integer, required, minimum: 500, maximum: 60000)*
+  - `maxRetries` *(integer, required, minimum: 0, maximum: 3)*
+  - `cache` *(boolean, required)*
 - `structuralQuality` *(object, optional)*
   - `mode` *(string, optional, enum: `off`, `observe`, `gate`)*
   - `provider` *(string, optional, pattern: `^[a-z][a-z0-9-]{0,63}$`)*
@@ -304,6 +412,21 @@ Local ForgeLoop configuration settings and policy bindings.
 
 Pre-implementation gate approval artifact recording decisions, bound artifact hashes, and evidence.
 
+Use `node src/cli.js gate-record` to create or replace this artifact. The
+command computes SHA-256 values from project-relative regular files; callers
+must not provide digests or edit gate JSON manually. Preflight checks these
+hashes for staleness, and gate mutation is available only before execution.
+Caller-recorded evidence is descriptive local input, not host attestation,
+ForgeLoop execution evidence, or remote authority.
+
+`requiredBy` records only the provenance that actually requires the gate:
+guides whose metadata declares it, plus the stable `config.requiredGates`
+marker when `config.requiredGates` requires it. Programmatic gate-record
+inputs are bounded (32 repeatable entries, 2000-character strings, 4 MiB
+per bound artifact, 64 KiB per evidence file) and refuse stale routes when
+the persisted route, work state, or current contract fingerprints no longer
+agree, before any gate is written.
+
 #### Canonical Fields
 
 <!-- BEGIN FORGELOOP GENERATED: schema:gate -->

package/docs/AUDIT_UX.md

@@ -0,0 +1,46 @@
+# Audit UX read model
+
+`task/audit-view` is a bounded, read-only Integration API resource for audit
+and operator interfaces. It composes canonical ForgeLoop projections; it does
+not become a second lifecycle, evidence, ownership, or completion authority.
+
+```js
+import { readForgeLoopIntegrationResource } from "@cassiomc1/forgeloop/integration";
+
+const view = await readForgeLoopIntegrationResource("task/audit-view", {
+  taskId: "task-1",
+  limit: 50,
+  categories: ["LIFECYCLE", "CHECK", "DIAGNOSTIC"],
+});
+```
+
+The projection includes lifecycle and health; a deterministic sequence-backed
+timeline with explicit `null` timestamps when the ledger has no authoritative
+timestamp; bounded checks, attempts, diagnostics, approvals, durable-action
+summaries, recovery history, completion status, and canonical ownership; and
+integrity and reason-code summaries that remain fail-closed when source
+projections are inconsistent.
+
+Timeline pagination accepts `limit`, `beforeSequence`, `afterSequence`, and a
+bounded category allowlist. Without a cursor, the latest bounded page is
+returned. `beforeSequence` performs backward pagination and returns the
+nearest earlier matching events; its `nextBeforeSequence` cursor is the first
+returned sequence when another page exists. `afterSequence` performs forward
+pagination and returns the earliest later matching events; its
+`nextAfterSequence` cursor is the last returned sequence when another page
+exists. Pages never skip matching sequence numbers within the filtered event
+stream, and combining the two cursors is rejected.
+
+The projection redacts general POSIX (including single-segment), Windows, UNC,
+and local `file://` absolute paths; environment assignments; common credential
+assignments; authorization headers; complete `Cookie` and `Set-Cookie` header
+values; and URL userinfo credentials. It does not return raw event payloads,
+commands, or provider output. These are presentation-boundary redactions, not a
+replacement for secret-handling controls at the source. The resource never
+invokes a provider, executes a command, writes an artifact, changes lifecycle
+state, or releases claims.
+
+`auditUx` is advertised during capability discovery with version `1` and
+`readOnly: true`. Hosts must use the canonical CLI/API lifecycle commands for
+all mutations and must treat this view as presentation and diagnostic context
+only.