@cassiomc1/forgeloop 1.13.0 → 1.14.0

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.

package/docs/BROWSER_VERIFICATION.md

@@ -0,0 +1,136 @@
+# Browser Verification
+
+## Status
+
+Browser verification is a provider-neutral, host-injected v1 observation
+contract. It is experimental and explicit. ForgeLoop does not select a browser
+vendor, install a browser, or invoke verification from lifecycle commands.
+
+## Purpose and Architecture
+
+`runBrowserVerification` validates a bounded request, resolves one registered
+provider, and turns its untrusted observation into an immutable result. Core
+does not perform browser I/O. The runtime registry is inert at context
+construction; factories are lazy and are invoked only by the explicit API call.
+
+## Invocation
+
+Provide an explicit task, target, requirement, and verification identity along
+with `runtimeContext.browserVerificationProviders`:
+
+```js
+const result = await runBrowserVerification({
+  taskId: "task-123",
+  target: "/workspace/project",
+  providerName: "playwright",
+  verificationId: "checkout",
+  requirement: "Checkout is usable",
+  startUrl: "https://app.example.test/checkout",
+  allowedOrigins: ["https://app.example.test"],
+  steps: [{ id: "open", kind: "NAVIGATE", url: "https://app.example.test/checkout" }],
+  assertions: [{ id: "title", kind: "TITLE_EQUALS", expected: "Checkout" }],
+  runtimeContext: { browserVerificationProviders: { playwright: provider } },
+});
+```
+
+Providers are registered by ID and must expose `verify(input)`. Factories are
+lazy and are resolved only when the explicit invocation runs. Provider input
+contains the normalized request, `signal`, and remaining `timeoutMs`. The
+`AbortSignal` is an invocation control, not protocol state.
+
+## Request Model
+
+Requests require `taskId`, `target` (or `projectPath`), `verificationId`,
+`requirement`, `startUrl`, `allowedOrigins`, at least one bounded step, and at
+least one bounded assertion. Optional viewport, screenshot capture policy, and
+timeout values are bounded. Unknown request, step, locator, assertion, capture,
+or viewport fields are rejected. Arbitrary scripts, headers, cookies, uploads,
+downloads, shell commands, and executable paths are not part of this contract.
+
+Supported steps are `NAVIGATE`, `CLICK`, `FILL`, `PRESS`, and `WAIT_FOR`.
+Supported assertions include visibility, text, value, attribute, URL, title,
+and their documented bounded variants. Assertion results must match the
+requested IDs, kinds, cardinality, and order exactly.
+
+`WAIT_FOR` is strict: visibility, hidden-state, and text waits require a
+locator; text and URL waits require an expected value, and URL wait values must
+also be in the exact origin allowlist.
+
+## Origins and Navigation
+
+Authored URLs and provider-reported `finalUrl` and `navigations` must use
+`http:` or `https:`, contain no credentials, and have an exact origin in
+`allowedOrigins`. Hostnames are case-normalized and trailing-dot hostnames are
+rejected. `localhost` and IPv4 origins are supported; bracketed IPv6 literals
+are intentionally excluded in v1. The allowlist is an observation policy, not
+a network sandbox: providers remain responsible for browser network access.
+
+## Result Model
+
+The normalized result contains task and requirement binding, provider identity,
+assertions, final navigation state, diagnostics, optional accessibility
+snapshots, and structured screenshot metadata. Raw image bytes are never
+returned. Artifact references are portable, bounded, credential-free metadata
+with a lowercase SHA-256 digest.
+
+ForgeLoop derives overall status: any `FAIL` assertion yields `FAIL`, otherwise
+any `BLOCKED` yields `BLOCKED`, otherwise all assertions yield `PASS`. A raw
+provider status is optional and, when present, must match that derived value.
+Provider output cannot choose lifecycle state, evidence, completion, claims, or
+next actions. Unknown top-level fields and authority-bearing fields fail closed.
+
+Snapshots are optional explicit `ACCESSIBILITY` observations with bounded
+portable text. They are never assertion status or authority.
+
+## Timeout and Cancellation
+
+Factory resolution, provider validation, provider verification, and result
+normalization share one ForgeLoop-owned deadline. On expiry ForgeLoop aborts
+the shared signal, allows only bounded cooperative cleanup, and returns
+`E_BROWSER_VERIFICATION_TIMEOUT`. Late provider resolution cannot change the
+returned result. Providers must observe the signal and clean up resources they
+own; synchronous JavaScript cannot be forcibly preempted.
+
+## Trust Boundary and Credentials
+
+Provider output is untrusted and normalized under strict size limits. Results
+are stamped with `authority: "OBSERVATION"`, `evidenceAuthority: "NONE"`,
+`actionability: "NON_EXECUTABLE"`, `lifecycleAuthority: false`, and
+`completionAuthority: false`. Provider output cannot substitute for ForgeLoop
+validation or lifecycle evidence.
+
+Provider errors are mapped to generic, secret-safe public errors. Raw causes,
+stacks, stderr, cookies, tokens, signed URLs, and local paths are not public
+metadata. Credentials must not be placed in requests, URLs, artifacts,
+diagnostics, or snapshots.
+
+## Evidence Boundary
+
+Results are observation-only: `persisted: false`, `evidenceAuthority: "NONE"`,
+`completionAuthority: false`, and `evidenceRequiresForgeLoopValidation: true`.
+Running this API does not mutate tasks, claims, routes, contracts, events,
+receipts, checks, evidence, recovery, or actions.
+
+## Network and Session Semantics
+
+The origin allowlist does not provide browser isolation or prevent provider
+network access. Providers own browser sessions and must not reuse credentials
+or session state across unrelated invocations. No automatic browser install,
+executable discovery, browser adapter, or auto-invocation is provided.
+
+## Future Adapters and Troubleshooting
+
+The optional Agent Browser adapter implements this provider contract through
+`createAgentBrowserVerificationProvider`. It requires a host-supplied absolute
+executable and never installs Agent Browser or Chrome. No vendor is canonical,
+and no lifecycle command invokes the adapter. See
+[`AGENT_BROWSER_ADAPTER.md`](./AGENT_BROWSER_ADAPTER.md) for its process,
+session, screenshot, and troubleshooting boundaries. For malformed requests,
+invalid results, origin escapes, provider failures, and timeouts, use the
+stable error codes in `docs/TROUBLESHOOTING.md`.
+
+## Compatibility
+
+The canonical public operation is `runBrowserVerification`. The runtime
+registration key remains `browserVerificationProviders`, and the provider kind
+remains `BROWSER_VERIFICATION`.