@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

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

@@ -353,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>
@@ -378,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

@@ -1,13 +1,81 @@
 # ForgeLoop Release Checklist
 
-This is the current release checklist for `@cassiomc1/forgeloop`. It is a
-preparation and verification checklist; it does not authorize publication.
+This is the current release checklist for the PolyForm Noncommercial-licensed
+`@cassiomc1/forgeloop` package. It is a preparation and verification checklist;
+it does not authorize publication.
 
-## ForgeLoop 1.12.0 candidate scope
+## Bounded 2.0.0-rc.2 publication
 
-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
-boundaries explicit:
+The owner approved short verification and an RC fallback on 2026-10-13. This
+candidate is published only to npm `next`; stable `latest` remains blocked while
+`soleSQLiteWriter` is false. A release candidate does not assert completed
+migration acceptance or production readiness.
+
+After npm rejected restricted RC1 publication with `E402`, the owner authorized
+public core-package access. RC2 preserves the immutable RC1 tag; the MCP
+companion is not published and retains restricted access.
+
+`npm run release:quick` is the RC PR and publishing check. Each check group has
+an enforced three-minute timeout; timeout or failure refuses release. It runs
+source equivalence, writer inventory drift detection, essential SQLite boundary
+and package-policy tests, lint, dependency policy, documentation conformance,
+packed CLI/API/MCP smoke checks, hygiene, and secret scanning. This approved RC
+path replaces a new local `verify:prepush` run. It does not replace the ordinary
+or stable-release validation policy.
+
+`scripts/check-rc-release.mjs` requires all 593 runtime/schema/integration files
+to match baseline `14008f58f8ad255692997ce3fff359591fb695d1`. Root package
+metadata may change only its RC version, the three approved RC scripts, and owner-authorized public access.
+Resolved dependency locks must be unchanged apart from local package versions;
+MCP metadata may only admit the explicit RC peer and bind the local core version.
+Changed runtime or dependency bytes refuse this fast path.
+
+The baseline Windows full-suite receipt is GitHub run `38483385848`, successful
+on that exact source. Publishing verifies its repository, workflow, source SHA,
+and completed success status through the authenticated GitHub API. Current
+Linux/packaged smoke and local macOS short checks are separate evidence. No new
+full-coverage, full-platform, physical power-loss, or statistically qualified
+p95 result is claimed by the short path. The existing 1,000-task parity run
+`38483369676` is retained for review; no fresh 200-repeat benchmark is dispatched.
+
+The writer inventory covers every current `src` JavaScript module and records
+imports plus potential write sites. Alias, computed-path, external-caller, and
+transitive-authority review remain incomplete. The inventory explicitly keeps
+`wholeConsumerClosure: false`; it prevents drift and does not authorize setting
+`soleSQLiteWriter` to true.
+
+RC release sequence: reviewed PR checks pass, merge preserving baseline
+ancestry, tag `v2.0.0-rc.2`, dispatch `npm-publish.yml` with channel `next` and
+confirmation `PUBLISH PUBLIC PACKAGE`, then verify npm version, Git commit,
+tarball integrity, and provenance. Stable publishing retains full checks and
+additionally refuses incomplete sole-writer acceptance.
+
+## ForgeLoop 2.0.0 candidate scope
+
+The 2.0.0 candidate is not release-ready while SQLite migration plan §10 has
+open consumer-closure, current-source performance, or platform evidence. Keep
+all acceptance boxes open until their evidence is bound to the exact candidate
+revision.
+
+The 2.0.0 candidate carries the SQLite storage transition alongside the
+existing protocol, routing, provider, documentation, and package surfaces. The
+existing checklist remains applicable to those surfaces; SQLite release
+acceptance additionally requires every item below:
+
+- [ ] All plan §9 acceptance rows are current for the exact candidate SHA,
+      including an accepted 1,000-task hosted parity run with exact output,
+      validated workers, clean observer admission, cleanup, and lower native
+      p95 for both operations.
+- [ ] Plan §10 consumer closure is complete and `soleSQLiteWriter` is true
+      based on source audit and tests; fail-closed migration boundaries remain
+      in place until that evidence exists.
+- [ ] Migration, crash recovery, legacy-unbound handoff, attachment recovery,
+      backup, restore, rollback, and SQLite integrity checks pass on the exact
+      candidate.
+- [ ] Required Linux, macOS, Windows, supported Node runtime, MCP, API, and
+      package workflows pass at the exact candidate SHA.
+- [ ] Release identity and npm version availability are verified, and the
+      matching tag workflow completes its verification job before publishing.
 
 - [ ] README catalog and architecture fallback identify
       `ENG/flutter-development-eng.md` and explain that the specialist is
@@ -41,13 +109,26 @@ boundaries explicit:
 - [ ] Lifecycle, evidence, completion, and publication remain independent of
       Repository Index and persistent-host health.
 
-This branch prepares the candidate and its pull request. npm publication,
-tagging, GitHub Release, deployment, and merge remain separately authorized
-actions.
+This checklist does not authorize publication by itself. The owner authorized
+conditional npm publication through the GitHub workflow; the action remains
+prohibited until every release gate passes. Tagging, GitHub Release,
+deployment, and live data migration remain separate 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
@@ -64,7 +145,9 @@ actions.
 ## Contract and package identity
 
 - [ ] `package.json` and `package-lock.json` contain the same package version.
-- [ ] The package metadata declares the intended SPDX license (`MIT`).
+- [ ] The package metadata declares the intended license
+      (`PolyForm-Noncommercial-1.0.0`), includes the official license text,
+      and retains public core-package publication access.
 - [ ] `PROTOCOL_VERSION` and the integration API version remain compatible.
 - [ ] `npm run release:identity` passes for the candidate version.
 - [ ] No release tag or registry version collision exists.
@@ -86,7 +169,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.
@@ -97,8 +200,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 with only the approved exact runtime
-      parser dependency and approved development 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/SELF_HOSTED_TESTS.md

@@ -0,0 +1,121 @@
+# Self-hosted Node validation
+
+Node validation uses the following repository-specific runners. Platform and
+Node-version matrix rows remain explicit; moving a job does not remove a check.
+
+| Platform | Runner label | Execution location |
+| --- | --- | --- |
+| macOS arm64 | `forgeloop-macos-local` | Local macOS LaunchAgent |
+| Windows x64 | `forgeloop-windows-remote` | Windows service on the requested remote host |
+| Linux x64 | `forgeloop-linux-remote` | Docker Linux container on that Windows host |
+
+Publishing jobs retain their existing hosted execution and manual confirmation.
+Their Node tests run in a preceding remote `verify` job. Classification and the
+final PR result aggregation remain hosted; they do not run the product test
+suite. CodeQL, dependency review and release-note publication retain their
+existing execution locations.
+
+`PR Core` also supports manual dispatch on a pushed candidate branch. Dispatch
+selects every validation category, so validation does not require a PR event
+or revision-range payload. PR invocations keep their existing path routing.
+The native Repository Index matrix waits for the preceding Linux checks to
+finish and runs one platform row at a time. Expanded Node compatibility waits
+for its minimum-runtime check and also runs one row at a time. Native rows still
+run after an earlier test failure to retain diagnostic coverage; final required
+validation reports preceding failures.
+
+Dispatch Windows full suite, expanded Node compatibility, and PR Core
+sequentially when validating the shared Windows/Linux host. The Windows job
+checks that the requested host IP is present and logs only the Docker runner's
+container ID, image ID, running state and hostname. Core Linux jobs record their
+platform, architecture, hostname and checked-out revision. Match the Linux
+hostname to the Windows Docker inspection before claiming the requested
+execution location. These identity checks remain unverified until the candidate
+workflows actually execute.
+
+PR repository-hygiene validation runs in the guarded remote Linux `lint` job,
+including documentation-only changes. Its checkout and Node prerequisites run
+for every admitted PR; JavaScript lint and dependency installation retain their
+path conditions. Hosted classification computes routing outputs only.
+
+Required ruleset check names remain unchanged. The historical
+`tarball smoke (ubuntu-latest)` context now executes in the remote Linux
+container; the check name is retained for ruleset compatibility.
+
+## Admission
+
+This is a public repository. An operator-owned copy of
+`scripts/ci-runner-admission.mjs` runs through
+`ACTIONS_RUNNER_HOOK_JOB_STARTED` before checkout. The shell wrappers and admission
+module live outside the job checkout and runner application directory. Keep
+those deployed copies synchronized when changing the policy.
+
+Admission requires matching repository metadata and allows only `push`,
+`workflow_dispatch`, `schedule`, `release`, and pull requests whose base and head
+both belong to this repository. Fork pull requests, `pull_request_target`,
+unknown events, missing metadata and invalid event files fail before job steps.
+Workflow job conditions independently exclude fork pull requests. Fork test
+validation requires a separate isolated execution environment; these machines
+do not run fork contributions.
+
+The hook does not sandbox admitted code. Repository write access is therefore a
+trust boundary. The Linux runner container has no Windows filesystem mounts or
+Docker socket mount. Its workspace and GitHub-managed runner credentials stay
+inside the dedicated container. Native macOS and Windows jobs run with their
+configured local accounts.
+
+## Installed locations and status
+
+Local macOS:
+
+```sh
+cd /Users/cassio/.local/share/forgeloop-ci/macos
+./svc.sh status
+```
+
+Windows PowerShell:
+
+```powershell
+Get-Service actions.runner.cassiomc1-forgeloop.forgeloop-windows-remote
+docker inspect forgeloop-linux-remote --format '{{json .State}}'
+docker logs --tail 40 forgeloop-linux-remote
+```
+
+The Windows runner is installed at `C:\forgeloop-ci\windows`. Its deployed hook
+is `C:\forgeloop-ci\hooks\windows-admission.ps1`. Isolated runtimes live below
+`C:\forgeloop-ci\runtime`; the runner environment includes portable Node, Git,
+Bash and unzip. Runner service credentials are managed by Windows; no account
+password belongs in repository files, job logs or shell scripts.
+
+The Linux image is built from `.github/runner/Dockerfile` using the repository
+root as its build context:
+
+```sh
+docker build -f .github/runner/Dockerfile -t forgeloop-actions-linux:2.337.0 .
+```
+
+The Node base image is pinned by digest. The GitHub runner archive is checked
+against its published SHA-256 before extraction. System dependency packages are
+resolved by the official runner dependency installer at build time; rebuilding
+is not a claim of byte-identical package resolution. The deployed image and
+runner version must be recorded with validation evidence.
+
+Docker Desktop credential helpers can fail in a noninteractive WinRM session.
+The dedicated `C:\forgeloop-ci\docker-config` uses an empty public Docker Hub auth
+entry and the already-installed Docker Desktop CLI plugin directory. Commands
+using that configuration target the existing Linux engine explicitly. They do
+not modify the user's Docker credential store.
+
+Registration tokens expire and must be obtained through an authorized GitHub
+operator. Pass them transiently through `ACTIONS_RUNNER_INPUT_TOKEN`; do not
+store registration tokens in Docker image layers, repository scripts or a
+container's persistent environment. A stopped or offline runner is not evidence
+that its checks passed.
+
+## Verification boundary
+
+Runner registration, admission probes, a native SQLite smoke, quick suites,
+full core suites, MCP/package checks and GitHub workflow execution are separate
+evidence dimensions. Record the source fingerprint and exact command for each
+run. A workflow routing edit becomes externally verified only after GitHub
+executes the affected jobs on these runners.

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.