@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/docs/PROVIDERS.md

@@ -0,0 +1,126 @@
+# Provider Extension Reference
+
+## Status
+
+`providerExtensions` v1 is provider-neutral and experimental. This reference
+describes the architecture vocabulary and maintainer expectations. It does
+not document a supported import from `@cassiomc1/forgeloop/providers`.
+
+## Capability Discovery
+
+Run `node src/cli.js protocol-info --json` and inspect
+`features.providerExtensions`. The advertised capability includes the version,
+provider kinds, strict result boundary, cooperative cancellation, and explicit
+authority restrictions.
+
+## Provider Kinds
+
+- `ADVISORY_CONTEXT`: optional context, never executable or canonical.
+- `VERIFICATION_EXECUTION`: bounded execution observations, never completion truth.
+- `BROWSER_VERIFICATION`: browser observations with no canonical vendor.
+- `SECURITY_REVIEW`: bounded security observations pending any future explicit gate.
+- `PRESENTATION`: read-only rendering that cannot mutate protocol state.
+
+The canonical list is exported internally as `PROVIDER_KINDS`; public metadata
+is synchronized from that source and must not duplicate its strings.
+
+Concrete `ADVISORY_CONTEXT` adapters (Ripwire, OpenSrc) plug into the
+dedicated advisory-context Integration API (`createForgeLoopContext` with
+`advisoryContextProviders`, plus `recallAdvisoryContext`); they are not part
+of the generic internal provider registry described here.
+
+Browser verification is registered only through the runtime context option
+`browserVerificationProviders` and is invoked explicitly with
+`runBrowserVerification`. Registration is lazy and inert: it does not launch a
+browser, perform network I/O, or mutate protocol state. Its provider-neutral
+input includes task/target/requirement binding, a shared abort signal, and the
+remaining timeout. ForgeLoop validates redirects and derives overall status;
+provider output is observation only and cannot satisfy evidence or completion.
+
+The optional `agent-browser` adapter is registered through the same boundary
+with `createAgentBrowserVerificationProvider({ executablePath, expectedVersion })`.
+The executable is host-owned and absolute; no package dependency or automatic
+installation is added. The adapter returns browser observations only.
+
+The optional `vercel-labs/emulate` adapter is host-injected through
+`createEmulatedServicesProvider({ executablePath, expectedVersion })`. The
+host must provide an absolute regular executable and explicitly choose the
+services and loopback port range. ForgeLoop does not install the tool, search
+`PATH`, invoke a shell, persist service state in the target project, or treat
+service output as lifecycle, evidence, installation, or completion authority.
+The supported host tool is pinned to `0.11.2`; invocation is lazy and inert
+until `provider.start(...)` is called. Each bounded operation verifies the
+qualified version, starts with argv-only execution, observes loopback
+readiness, returns a detached observation, and cleans up its temporary state
+and child process.
+
+Security review is registered through `securityReviewProviders` and invoked
+explicitly with `runSecurityReview`. Registration is lazy and inert. The
+request accepts bounded scope, relative paths, categories, requirements, and a
+revision binding; factory resolution and review share one deadline and abort
+signal. Results are strict immutable observations with bounded findings and
+summary counts. They cannot establish evidence, lifecycle, completion,
+ownership, claims, commands, installation, or transaction authority. See
+[`SECURITY_REVIEW.md`](./SECURITY_REVIEW.md) for the complete contract.
+
+## Common Contract
+
+Providers are identified by an ID and kind, may resolve lazily, and receive a
+bounded invocation context. Results are detached, deeply frozen strict JSON
+snapshots. A provider may return an observation, never lifecycle state,
+completion truth, canonical evidence, executable instructions, or installation
+authority.
+
+## Invocation Context
+
+The context includes a shared `AbortSignal`, the provider ID, and the remaining
+timeout budget. Factories and operations consume the same deadline. Providers
+must observe abort and clean up owned resources.
+
+## Limits
+
+Invocation uses one shared timeout budget. Input and output are bounded by byte,
+depth, and node limits. Synchronous JavaScript cannot be preempted; resource
+owners remain responsible for cooperative cleanup after abort.
+
+## Error Codes
+
+Malformed providers, unavailable providers, timeouts, invalid snapshots,
+payload limits, authority escalation, and execution failures use the internal
+provider error vocabulary. Provider exceptions are normalized so a provider
+cannot spoof a ForgeLoop error code.
+
+## Trust Rules
+
+Treat provider output as untrusted input. Pass it through ForgeLoop-owned
+validation before any evidence or consumer use. Do not execute provider text,
+interpret it as a next action, or treat provider identity as a trust grant.
+
+## Maturity
+
+The public capability vocabulary is versioned at v1 but remains experimental.
+The generic registry implementation is internal and experimental. No provider
+is auto-installed or discovered by the lifecycle, and no provider CLI exists.
+
+## Internal vs Public Surfaces
+
+The public surfaces are the protocol-info capability and these documentation
+pages. The JavaScript registry under `src/providers/` ships as implementation
+source but is not a supported package subpath or public registration contract.
+
+## Future Adapter Structure
+
+An adapter proposal must specify its provider kind, bounded input/output,
+timeout and cancellation behavior, error mapping, authority restrictions,
+ForgeLoop validation boundary, tests, and documentation owner. Dedicated
+Integration API capabilities remain separate from this generic vocabulary.
+
+## Testing Checklist
+
+- Capability metadata is synchronized with `PROVIDER_KINDS`.
+- Every provider kind denies lifecycle, completion, and evidence authority.
+- Strict JSON rejects accessors, proxies, custom objects, cycles, and oversized payloads.
+- Shared timeout and cooperative cancellation are tested.
+- Provider exceptions cannot spoof ForgeLoop error codes.
+- `protocol-info --json` advertises v1 without claiming a public registry API.
+- The package does not export `./providers`.

package/docs/PROVIDER_ARCHITECTURE.md

@@ -0,0 +1,199 @@
+# Provider Extension Architecture
+
+## Status
+
+Provider extensions are a provider-neutral, experimental capability family in
+Protocol v1. The capability vocabulary is public and versioned; the generic
+provider registry is internal and is not a supported package API.
+
+## Scope
+
+This document explains the common boundary around provider observations. It
+does not add generic provider registration to `createForgeLoopContext()`; the
+dedicated runtime-only `browserVerificationProviders` and
+`securityReviewProviders` registrations are the exceptions documented by
+their dedicated contracts. They do not add CLI
+provider commands, automatic installation, lifecycle authority, or completion
+authority.
+
+## Why ForgeLoop Uses Providers
+
+Providers allow a host to connect bounded observations or execution services to
+ForgeLoop without making a vendor, model, browser, scanner, or presentation
+tool canonical. A provider result is an input to ForgeLoop-owned validation,
+not a replacement for it.
+
+## Provider-Neutral Design
+
+The public `providerExtensions` capability advertises architecture and
+compatibility semantics only. It is provider-neutral, experimental, lazy at
+the host boundary, and deliberately separate from the existing dedicated
+`advisoryContextProviders` Integration API capability.
+
+The generic registry is currently an internal implementation module. It is
+not exported as `@cassiomc1/forgeloop/providers`, and capability advertising
+does not imply a public registration or installation API.
+
+## Provider Kinds
+
+The five kinds are derived from the canonical `PROVIDER_KINDS` source:
+
+| Kind | Contract |
+| --- | --- |
+| `ADVISORY_CONTEXT` | Optional, non-authoritative context. It is never canonical state, evidence, completion authority, or executable instruction. |
+| `VERIFICATION_EXECUTION` | A bounded execution boundary that may produce observations, but never completion truth. |
+| `BROWSER_VERIFICATION` | Browser-driven observation and assertion collection. No vendor is canonical. |
+| `SECURITY_REVIEW` | Bounded security findings, observation-oriented unless a future explicit gate contract exists. |
+| `PRESENTATION` | Read-only presentation or rendering. It must never mutate protocol state. |
+
+Every kind denies lifecycle, completion, and evidence authority. Providers do
+not acquire installation authority.
+
+### Presentation vocabulary and Audit UX
+
+`PRESENTATION` remains a provider-kind vocabulary slot for future bounded
+renderers; it does not require a concrete provider in the completed roadmap.
+The current Audit UX need is already served by `task/audit-view`, a canonical
+read-only Integration API projection composed from ForgeLoop-owned resolvers.
+Audit UX is not a provider, does not register through the provider boundary,
+and cannot mutate protocol state, establish evidence, release claims, or
+authorize completion.
+
+## Invocation Lifecycle
+
+```text
+HOST
+ │
+ ▼
+provider selection
+ │
+ ▼
+registry lookup
+ │
+ ▼
+lazy factory resolution
+ │
+ ▼
+provider validation
+ │
+ ▼
+bounded invocation
+ │
+ ▼
+strict JSON normalization
+ │
+ ▼
+authority validation
+ │
+ ▼
+immutable observation
+  │
+  ▼
+  ForgeLoop consumer
+```
+
+The result boundary is:
+
+```text
+provider result
+      ↓
+normalized observation
+      ↓
+ForgeLoop-owned validation
+      ↓
+optional canonical evidence/use
+```
+
+A provider must never bypass ForgeLoop-owned validation.
+
+Browser verification is an explicit Integration API operation, not a generic
+provider command. Its registry is inert during context construction, its
+factory and verify call share one deadline and cooperative `AbortSignal`, and
+its final status is derived by ForgeLoop from the requested assertion results.
+The origin allowlist validates observations but is not a network sandbox.
+
+Security review is likewise an explicit Integration API operation through
+`runSecurityReview`. Its host-injected registry is inert during context
+construction. Requests and results are bounded strict snapshots, and provider
+findings remain observation-only, non-evidence, and non-executable.
+
+## Trust Boundary
+
+Provider output is untrusted input. It cannot establish lifecycle state,
+completion truth, canonical evidence, next-action authority, or installation
+authority. Provider identity and availability are descriptive and must not be
+treated as proof of executable identity or trust.
+
+## Strict JSON Snapshot Boundary
+
+Provider input and output use detached, deeply frozen snapshots. Allowed values
+are `null`, booleans, finite numbers, strings, arrays, and plain objects.
+
+The boundary rejects `undefined`, functions, symbols, bigints, non-finite
+numbers, dates, maps, sets, promises, proxies, custom classes, accessors,
+cycles, sparse or extended arrays, and hidden non-enumerable payload data.
+Provider payloads are bounded by byte, depth, and node limits.
+
+## Timeout and Cancellation
+
+Factory resolution and operation execution share one timeout budget and one
+invocation context. The `AbortSignal` is propagated and cancellation is
+cooperative. A late factory resolution cannot start an operation after the
+deadline. Synchronous JavaScript cannot be preempted by a timer, so providers
+that own subprocesses, browsers, requests, or sockets must clean them up when
+the signal is aborted.
+
+## Error Normalization
+
+Provider exceptions are normalized to ForgeLoop provider execution failures;
+provider-supplied ForgeLoop-shaped error codes are not trusted. Validation and
+timeout failures are generated outside the provider call boundary.
+
+## Authority Restrictions
+
+The following public capability fields remain false: `autoInstall`,
+`lifecycleAuthority`, `completionAuthority`, and `evidenceAuthority`.
+Providers observe. ForgeLoop validates, owns lifecycle transitions, and decides
+whether an observation can contribute to canonical evidence.
+
+## Evidence Conversion Boundary
+
+An observation can become usable evidence only through the relevant
+ForgeLoop-owned validation and evidence contract. Provider output is never
+itself a completion claim or canonical evidence record.
+
+## Internal vs Public Surfaces
+
+Public and versioned:
+
+- `protocol-info --json` and `features.providerExtensions`.
+- This architecture document and [`PROVIDERS.md`](./PROVIDERS.md).
+
+Internal and experimental:
+
+- `src/providers/index.js` and the generic registry implementation.
+- Provider capability implementation details not included in the public
+  Integration API contract.
+
+`@cassiomc1/forgeloop/providers` remains unexported.
+
+## Compatibility
+
+Protocol version, Schema version, and Integration API version remain `1`.
+`providerExtensions` is capability version `1`; consumers must feature-detect
+it and may continue using the core protocol when they do not understand it.
+
+## Future Provider Adapters
+
+Future adapters may implement a provider kind only after a provider-neutral
+contract defines its input, output, resource bounds, trust treatment, and
+ForgeLoop-owned validation boundary. Vendor-specific adapters remain optional
+and must not become a competing source of protocol truth.
+
+## Security Considerations
+
+Provider output can be malicious, oversized, mutable, delayed, or misleading.
+Strict JSON snapshots, bounded invocation, cooperative cancellation, error
+normalization, recursive authority checks, and no automatic installation keep
+the boundary fail-closed. See [`THREAT_MODEL.md`](../THREAT_MODEL.md) for the
+security ownership table.

package/docs/RECIPES.md

@@ -35,6 +35,18 @@ Concise, copy-paste friendly recipes for common ForgeLoop tasks.
 
 ### Recipe 1 — Start a New Task
 
+When the task shape is known but the final contract has not been written, first
+request a read-only preset proposal:
+
+```bash
+forgeloop task-create --task task-001 --claim src --claim tests \
+  --preset feature --preview --json
+```
+
+Review the bounded proposal, then repeat without `--preview` before continuing
+with the task workflow below. Preview creates no task namespace and acquires no
+project claim lock.
+
 <!-- FORGELOOP EXAMPLE: recipes:create-task | exit=0 | json.taskId=task-001 -->
 ```bash
 forgeloop task-create --task task-001 --claim src --claim tests --json
@@ -243,6 +255,12 @@ forgeloop task-create --task billing-feature --claim src/billing --claim tests/b
 # 3. List active tasks
 forgeloop task-list --json
 
+# 3a. Filter and page the read-only ownership-aware projection
+forgeloop task-list --active --limit 20 --offset 0 --json
+
+# 3b. Ask for a bounded blocker/recovery explanation when needed
+forgeloop next --task auth-feature --explain --json
+
 # 4. Work on task-1
 forgeloop route --task auth-feature --work clean-code --surface backend
 forgeloop preflight --task auth-feature --json
@@ -256,6 +274,11 @@ forgeloop complete --task auth-feature --json
 forgeloop task-unlock --task auth-feature --force --json
 ```
 
+`task-list` discovers all valid task namespaces before applying filters and
+pagination. Its JSON response reports `total` and `hasMore`; filtering does not
+skip ownership or corruption checks, and listing never deletes ledger or
+recovery evidence.
+
 ---
 
 ### Recipe 12 — Migrate Legacy 1.0 Single-Task Layout
@@ -330,6 +353,10 @@ forgeloop baseline --record --policy-reset-authorized --json
 # 1. Inspect deterministic classification and structured next action
 forgeloop next --task task-001 --json
 
+# 1a. If the active task is intentionally no longer valid, explicitly abandon
+#     it; do not use clear-state or task-recover to bypass ownership
+forgeloop task-abandon --task task-001 --acknowledge-abandonment --json
+
 # 2. RECOVERABLE must use reconcile-closure; do not use task-recover
 forgeloop reconcile-closure --task task-001 --id <verification-id> \
   --requirement "<exact verification text>" -- <verification-command>
@@ -355,6 +382,11 @@ artifact against the complete ledger history. If `next` returns
 `RESOLVE_RECOVERY_INCONSISTENCY`, run `validate-protocol`; do not create, edit,
 or delete `recovery.json` manually.
 
+`task-abandon` is only for an explicit active non-terminal abandonment. It
+records `TASK_ABANDONED`, leaves the phase unchanged, and releases claims as
+`RELEASED_BY_RECOVERY`; it never proves completion. `clear-state` removes only
+the checkpoint and is not a claim-release mechanism.
+
 ---
 
 ### Recipe 16 — Execute a Durable External Action Safely

package/docs/RELEASE_CHECKLIST.md

@@ -3,16 +3,27 @@
 This is the current release checklist for `@cassiomc1/forgeloop`. It is a
 preparation and verification checklist; it does not authorize publication.
 
-## ForgeLoop 1.12.0 candidate scope
+## ForgeLoop 1.14.0 candidate scope
 
-The 1.12.0 candidate carries the first-class Flutter guide and deterministic,
-scope-aware project routing added by PR #165. The candidate must keep these
+The 1.14.0 candidate carries the protocol, routing, provider, documentation,
+and package changes present in current `main`. The candidate must keep these
 boundaries explicit:
 
 - [ ] README catalog and architecture fallback identify
       `ENG/flutter-development-eng.md` and explain that the specialist is
       selected only from a structurally parsed
       `dependencies.flutter.sdk: flutter` entry in affected scope.
+- [ ] README catalog and architecture fallback identify
+      `ENG/rust-development-eng.md` and explain that the specialist is
+      selected only from a structurally parsed `[package]` or `[workspace]`
+      table in an affected `Cargo.toml`.
+- [ ] README catalog and architecture fallback identify
+      `ENG/nodejs-backend-development-eng.md` and explain that Node.js
+      backend/runtime evidence is distinct from build, test, and configuration
+      tooling executed under Node.js.
+- [ ] README catalog and architecture fallback identify the C, C++, Java, SQL,
+      Go, TypeScript, PHP, and Swift specialists and explain their bounded
+      structural evidence and same-root composition rules.
 - [ ] The canonical engineering-flow source and regenerated HTML/SVG diagram
       explain project detection as routing context, not verification or
       completion evidence.
@@ -34,6 +45,34 @@ This branch prepares the candidate and its pull request. npm publication,
 tagging, GitHub Release, deployment, and merge remain separately authorized
 actions.
 
+## CI minimization validation
+
+- [ ] `npm run skill:check` passes and generated Skill frontmatter, protocol
+      synchronization, safety boundaries, and package coverage remain valid.
+
+- [ ] `npm run verify:fast` passes for edit-time feedback.
+- [ ] `npm run repository:hygiene` passes: no tracked mutable ForgeLoop state,
+      unexpected root reports, orphan visual assets, unapproved benchmark run
+      sets, or scratch outputs.
+- [ ] The documentation manifest and review matrix cover every maintained and
+      packaged document with origin, currency, package, action, and canonical
+      source metadata.
+- [ ] Diagram source, generated output, receipts, and review bindings are
+      current; a changed source is not approved until its visual review is
+      renewed.
+- [ ] `npm run verify:prepush` passes before the release pull request; MCP
+      setup, when needed, was run explicitly with `npm run mcp:setup`.
+- [ ] Ordinary PR validation uses `.github/workflows/pr-core.yml` with the
+      unchanged required contexts `audit`, `CodeQL`, `Verify generated Archify
+      diagram`, `validate (22)`, `tarball smoke (ubuntu-latest)`, and
+      `dependency-review`.
+- [ ] `validate (22)` is always present and fails closed on an applicable
+      prerequisite failure, cancellation, or unexpected skip.
+- [ ] Path classification scenarios cover README-only, ordinary source,
+      Repository Index, package-export, and forced release validation.
+- [ ] Main-branch documentation, Node compatibility, package smoke, audit,
+      and Windows full-suite workflows remain available for broader validation.
+
 ## Contract and package identity
 
 - [ ] `package.json` and `package-lock.json` contain the same package version.
@@ -47,7 +86,7 @@ actions.
 - [ ] [`docs/PACKAGE_CONTENTS.md`](./PACKAGE_CONTENTS.md) matches the current
       `package.json` file list and documents intentional inclusions and
       exclusions.
-- [ ] The candidate tarball includes the registered Flutter guide and every
+- [ ] The candidate tarball includes every registered specialist guide and every
       other `src/config/guides.json` path; no repository-only guide state is
       packaged.
 - [ ] Every maintained `src/**/*.js` module is present in the candidate
@@ -59,7 +98,27 @@ actions.
 - [ ] `protocol-info` and the Integration API capability contracts agree.
 - [ ] `canonicalHandoffs` v2 is advertised consistently.
 - [ ] `advisoryContextProviders` v1 is advertised consistently.
+- [ ] `providerExtensions` v1 is consistent, provider-neutral, experimental,
+      and retains false lifecycle/completion/evidence authority.
+- [ ] Generic provider registry export remains absent and auto-install remains
+      false.
 - [ ] Advisory context remains Integration-API-only.
+- [ ] OpenSrc requires an explicit absolute executable path and lazily qualified expected version.
+- [ ] OpenSrc cache remains outside the target project and returned source paths are containment-validated.
+- [ ] OpenSrc recall remains advisory, non-evidence, and non-persisted by ForgeLoop.
+- [ ] No OpenSrc binary or cache ships in npm.
+- [ ] Optional Agent Browser uses a host-supplied absolute executable, has no
+      runtime dependency, and keeps browser observations non-authoritative.
+- [ ] Optional Emulated Services uses a host-supplied absolute `0.11.2`
+      executable, has no runtime dependency or PATH discovery, bounds argv
+      execution/readiness/output/cleanup, keeps state outside the target, and
+      returns observation-only loopback results.
+- [ ] Optional Security Review is host-injected through `securityReviewProviders`,
+      has no auto-install or scanner discovery, and keeps findings
+      observation-only, non-evidence, non-lifecycle, and non-completion.
+- [ ] Security Review request/result bounds, strict snapshot validation,
+      shared timeout, and cooperative cancellation are covered by focused tests
+      and the public TypeScript declarations.
 - [ ] `next`, `status`, and `task/context` invoke zero advisory providers.
 - [ ] Advisory request budgets are normalized before provider invocation.
 - [ ] Advisory results are never persisted by ForgeLoop.
@@ -70,7 +129,9 @@ actions.
 - [ ] Stale contract/route identity rejects handoff creation or acceptance.
 - [ ] An invalid event ledger projects `INCONSISTENT`.
 - [ ] Continuity lint remains non-authoritative and non-evidence.
-- [ ] `npm run dependency:policy` passes without adding runtime dependencies.
+- [ ] `npm run dependency:policy` passes with only the approved exact
+      `@typesafe-ai/sdk` and `smol-toml` runtime dependencies and approved
+      development dependencies.
 - [ ] `npm run lint` passes.
 - [ ] `npm test` passes.
 - [ ] `npm run benchmark:profiles:check` passes; absent provider/host history

package/docs/SECURITY_REVIEW.md

@@ -0,0 +1,71 @@
+# Security Review Provider
+
+The Security Review provider is an optional, host-injected Integration API
+capability for bounded, observation-only security findings. It is deliberately
+separate from ForgeLoop lifecycle, evidence, completion, claim, ownership,
+installation, command, and transaction authority.
+
+## Registration
+
+Register providers on `createForgeLoopContext({ securityReviewProviders })`.
+The registry accepts an object or `Map`, and each value is either a provider
+or a lazy factory. Registration validates provider identity but does not invoke
+factories, scan the project, start a process, access the network, install a
+tool, or mutate `.forgeloop` state.
+
+Provider IDs are lower-case portable identifiers. A provider must expose the
+same `id` as its registry key and a `review(request)` function. The host owns
+the provider implementation and any scanner or executable it uses; ForgeLoop
+does not discover tools or search `PATH`.
+
+## Invocation
+
+Call `runSecurityReview({ projectPath, taskId, providerName, reviewId, ... })`
+through `@cassiomc1/forgeloop/integration`. Requests are detached and deeply
+frozen before invocation. The request supports `FULL`, `CHANGED`, or
+`SELECTED` scope, bounded relative paths, categories, requirements, an
+optional revision binding, and a timeout capped by ForgeLoop.
+
+Factory resolution and `review()` share one deadline and one cooperative
+`AbortSignal`. A caller may provide its own signal. Timeout, cancellation,
+provider absence, invalid providers, malformed results, output limits, and
+provider failures have stable `E_SECURITY_REVIEW_*` error codes. Provider
+exceptions are normalized so provider code cannot spoof ForgeLoop errors.
+
+## Result contract
+
+Results are detached, deeply frozen JSON observations with bounded findings,
+diagnostics, and summary counts. The raw provider snapshot is also bounded
+before schema projection: nesting is limited to 32 levels, traversal to 4096
+nodes, and snapshot strings/keys to 524288 characters. Exceeding any bound
+fails closed with `E_SECURITY_REVIEW_OUTPUT_LIMIT`.
+
+Each finding has a portable relative path, bounded title/summary/rule/category/
+severity/confidence fields, and no secret-like content. For `SELECTED` scope,
+each finding path must equal or be a descendant of one of the requested paths;
+`CHANGED` applies the same rule when an explicit changed-path set is supplied.
+Containment uses normalized `/` separators and path-component boundaries, so
+`src/auth.js` does not authorize `src/authentication.js`. `FULL` scope has no
+requested-path restriction beyond normal safe-path validation. Results carry
+trust metadata stating that they are observation-only and non-evidence.
+
+Provider output is not a pass/fail lifecycle decision. It cannot create or
+modify contracts, routes, gates, events, transactions, receipts, claims,
+ownership, completion, executable commands, shell operations, credentials, or
+installation state. Any future use as canonical evidence requires a separate
+ForgeLoop-owned validation and evidence contract.
+
+## Operational rules
+
+- Keep registration lazy and explicit.
+- Use a host-owned provider and a bounded request.
+- Treat findings as advisory observations, not proof of `VALID`, `COMPLETE`,
+  or any lifecycle phase.
+- Handle timeout and cancellation cooperatively and clean up resources owned by
+  the provider.
+- Do not persist provider output as ForgeLoop task state unless a future
+  canonical evidence contract explicitly defines that boundary.
+
+See [`PROVIDER_ARCHITECTURE.md`](./PROVIDER_ARCHITECTURE.md),
+[`PROVIDERS.md`](./PROVIDERS.md), and [`THREAT_MODEL.md`](../THREAT_MODEL.md)
+for shared provider and security-boundary rules.

package/docs/SEMANTIC_DECISION_PLANE.md

@@ -0,0 +1,71 @@
+# Semantic Decision Plane
+
+ForgeLoop uses the pinned TypeSafe Jev model `jev-1.13.0` for bounded semantic decisions. The SDK version is exact-pinned in `package.json` and credentials are read only from `TYPESAFE_API_KEY`; credentials are never persisted in ForgeLoop artifacts, event details, diagnostics, or logs.
+
+Jev output has `SEMANTIC_DECISION` authority and `NONE` evidence authority. It cannot advance lifecycle, change ownership, satisfy gates, record verification, mark completion, install dependencies, execute commands, or delete tests. ForgeLoop remains the deterministic authority for state, claims, locks, schemas, event chronology, evidence, recovery, and completion.
+
+The decision registry contains versioned question sets for intake, contract
+applicability, route, execution profile, context, model routing, failure triage,
+diagnosis, review, task overlap, test utility, and test pruning. Current route,
+context, and test-utility mutations also use bounded dynamic candidate question
+sets: `route-candidates-v1`, `context-candidates-v1`, and
+`test-utility-candidates-v1`. Failure triage, diagnosis prioritization, and review planning
+remain advisory projections: deterministic mandatory review signals are always
+unioned into the plan, unknown semantic output escalates, and no projection can
+record evidence or authorize an action.
+
+Decision freshness separates canonical lifecycle state from semantic request
+state. Persisted artifacts retain both fingerprints and their combined request
+fingerprint, so lifecycle mutations cannot be mistaken for semantic changes
+and semantic changes cannot be hidden by a stable lifecycle revision. The
+lifecycle, event ledger, claims, and artifact validators remain authoritative.
+
+Test utility analysis uses the bounded `test-utility-candidates-v1` question set
+for the current command path; `test-utility-v1` remains a registered base
+question set. The analysis is persisted separately from
+completion evidence. Protected, contract-linked, public-API, security, and
+protocol tests remain keep-required or keep-risk-guard candidates; unknown
+utility is blocked and no command performs deletion.
+
+Context plans send bounded, sanitized actual candidates to Jev. The candidate-set
+fingerprint is bound to the persisted decision, and Jev returns candidate ranking
+and exclusion judgments consumed by the context compiler. Deterministic required
+and mandatory candidates remain selected; prompt-injection candidates are never
+given semantic authority. Token values are `UNKNOWN` unless the provider or host
+reports them.
+
+Route execution records intake, route relevance, and execution-profile decisions
+before persisting the route. The deterministic router remains the eligibility
+and safety floor; Jev may rank or exclude only eligible non-mandatory guides and
+may raise the execution profile, never lower a deterministic safety floor.
+Mandatory safety protection is derived from the canonical deterministic route
+reasons already produced by the router (`isMandatorySafetyGuide` reads the
+`MANDATORY_SAFETY_REASONS` set — `SURFACE_AUTH` plus the trust-boundary risk
+reasons `RISK_UNTRUSTED_INPUT`, `RISK_PERSONAL_DATA`, `RISK_SECRETS`,
+`RISK_EXTERNAL_SERVICE`, `RISK_PUBLICATION`), so a security guide selected for an
+external-service boundary cannot be removed by Jev and retains an explicit
+`MANDATORY_SAFETY_GUIDE` reason. Mandatory safety guides and low-confidence
+exclusions remain selected. A missing live decision fails closed.
+
+The semantic provider is injected into repository tests through an internal
+loader only. There is no production environment switch that turns semantic
+decisions into fixture results; packaged commands without the pinned provider
+fail closed.
+
+`npm run jev:smoke` performs only a tiny health request when credentials are configured. A missing credential reports `NOT_RUN`; an unavailable or rate-limited service is a failed live check, never a fabricated success. Provider failures are classified into stable error codes (authentication, unsupported model, rate limit, timeout, result normalization) and, for live maintainer diagnostics, the smoke result additionally reports only safe metadata (HTTP status, provider error type, request id, network class) — never credentials, headers, or raw request bodies. Inspection, recovery, and completion validation do not require a live Jev call, but a semantic-required mutation fails closed when its canonical decision is missing or stale.
+
+The `INTAKE` and `CONTRACT_APPLICABILITY` checkpoints are observation-only in
+this version. Their immutable decisions are recorded, fingerprinted, and
+available for review and follow-up consumption, but their result does not
+currently alter the route or create, skip, or weaken the contract: Jev never
+removes user or deterministic signals, and a semantic `applicable: false` can
+never suppress a deterministic contract requirement. A narrow additive consumer
+was evaluated and deferred because it changes behavior across every provider
+mode without a validated benefit; semantic consumption is tracked as a
+follow-up task, not claimed as current routing quality.
+
+Semantic-required operations use fail-closed cutover semantics: an unavailable,
+stale, malformed, or unsupported decision cannot silently authorize a mutation.
+Offline inspection, recovery, and deterministic completion validation remain
+usable without a live Jev request. Cached decisions may be used only when their
+existing fingerprint/freshness validators accept them.