@cassiomc1/forgeloop 1.6.2 → 1.6.4

package/docs/GETTING_STARTED.md

@@ -389,7 +389,103 @@ forgeloop task-migrate --json
 
 ---
 
-## 8. Next Steps
+## 8. Optional advanced capabilities
+
+The default walkthrough above is complete without these extensions. Add them
+only when the task needs an extra boundary or provenance result.
+
+### Workspace binding, handoff, and responsibility
+
+For a task that must remain in one Git worktree, bind it explicitly and check
+the derived status before mutation:
+
+```bash
+forgeloop workspace-bind --task <taskId> --json
+forgeloop workspace-status --task <taskId> --json
+```
+
+Record a deterministic handoff snapshot or an optional pass constraint when
+the workflow needs those boundaries:
+
+```bash
+forgeloop handoff-create --task <taskId> --note "Continue verification" --json
+forgeloop handoff-list --task <taskId> --json
+forgeloop handoff-show --task <taskId> --id <handoffId> --json
+forgeloop responsibility-set --task <taskId> --label implementation --allowed-path src --required-check unit-tests --json
+forgeloop responsibility-status --task <taskId> --json
+```
+
+Workspace binding, handoff, and responsibility artifacts are optional. A
+binding checks the complete derived repository/worktree identity; a branch name
+or HEAD alone is not enough. A handoff is immutable protocol-derived context,
+not delegation or evidence. A responsibility label is descriptive, not a
+coder/reviewer/cleaner role, and its allowed paths, required checks, and frozen
+inputs are mechanically enforced when present.
+
+### Differential Verification Scope
+
+Configure a trusted scoped checker only when it can consume canonical paths:
+
+```json
+{
+  "verification": {
+    "checkers": [
+      {
+        "checkId": "unit-tests",
+        "scopeMode": "PATH_ARGUMENTS",
+        "argvPrefix": ["node", "--test"],
+        "pathInsertion": "APPEND"
+      }
+    ]
+  }
+}
+```
+
+Then ask ForgeLoop to resolve the scope and pass its exact paths to the
+checker:
+
+```bash
+forgeloop verify-scope --task <taskId> --mode AUTO --json
+forgeloop run-check --task <taskId> --id unit-tests \
+  --requirement "Unit tests" \
+  --scope-ref .forgeloop/task-state/<taskKey>/verification-scope.json \
+  -- node --test <paths-returned-by-verify-scope>
+```
+
+`AUTO` can resolve to `CHANGED` or `CLAIMED` only with a trusted scoped
+checker; otherwise it resolves to `FULL`. Explicit `CHANGED` or `CLAIMED`
+without that checker returns `E_VERIFICATION_SCOPE_UNRESOLVED`, and an argv
+mismatch is rejected before launch. This pre-completion decision is not
+revision-range attestation coverage.
+
+## 9. Optional code attestation
+
+When the project enables attestation, completion captures a source-content
+manifest transactionally. After completion, create and inspect the deterministic
+statement:
+
+```bash
+forgeloop attestation-create --task <taskId> --json
+forgeloop attestation-status --task <taskId> --json
+forgeloop attestation-verify --task <taskId> --ref HEAD --json
+```
+
+For a revision range, use the provider-neutral coverage command:
+
+```bash
+forgeloop attestation-verify-range \
+  --revision-provider git \
+  --base origin/main \
+  --head HEAD \
+  --require-complete-coverage \
+  --json
+```
+
+Verification commands are read-only. A valid source manifest proves exact
+content binding to ForgeLoop evidence; only an additional valid external
+signature can raise the trust level to `ATTESTED`.
+
+## 10. Next Steps
 
 - Continue a task across different AI harnesses: [`docs/CROSS_HARNESS_CONTINUITY.md`](./CROSS_HARNESS_CONTINUITY.md)
 - Optional: use ForgeLoop through MCP or the Integration API — [`docs/MCP.md`](./MCP.md) and [`docs/UNIVERSAL_INTEGRATION.md`](./UNIVERSAL_INTEGRATION.md). MCP is not required; CLI and MCP share the same canonical project/task state.
@@ -397,3 +493,4 @@ forgeloop task-migrate --json
 - Artifact and schema reference: [`docs/ARTIFACT_REFERENCE.md`](./ARTIFACT_REFERENCE.md)
 - Common symptoms and recovery: [`docs/TROUBLESHOOTING.md`](./TROUBLESHOOTING.md)
 - Real-world operational recipes: [`docs/RECIPES.md`](./RECIPES.md)
+- Code attestation and revision coverage: [`docs/CODE_ATTESTATION.md`](./CODE_ATTESTATION.md)

package/docs/MCP.md

@@ -83,6 +83,14 @@ content.
 Raw recovery artifacts, transaction journals, lock files, and unbounded event
 ledgers are intentionally not exposed.
 
+Optional workspace binding, handoff, responsibility, verification-scope,
+RevisionProvider, SigningProvider, and attestation operations remain governed
+by the same canonical command executors when exposed by a compatible host.
+MCP transport metadata cannot establish workspace identity, narrow a checker,
+mint signer authority, or turn continuity into evidence. Read-only attestation
+and range verification preserve the core `PROCESSED`, `VERIFIED`, and
+`ATTESTED` distinctions and never write verification events.
+
 ## Optional stateless HTTP transport
 
 `forgeloop-mcp-http` serves the same deterministic catalog over the **strict

package/docs/PLATFORM_ADAPTERS.md

@@ -0,0 +1,69 @@
+# Platform Adapters
+
+Platform adapters are convenience layers around the provider-neutral
+ForgeLoop verifier. They translate platform context into revisions and an
+optional signing policy; they do not become part of ForgeLoop protocol
+semantics.
+
+## Generic contract
+
+Every adapter supplies:
+
+```text
+revisionProvider
+baseRevision
+headRevision
+optional signingProvider and signer policy
+```
+
+The canonical command is:
+
+```bash
+forgeloop attestation-verify-range \
+  --revision-provider "$FORGELOOP_REVISION_PROVIDER" \
+  --base "$FORGELOOP_BASE_REVISION" \
+  --head "$FORGELOOP_HEAD_REVISION" \
+  --require-complete-coverage \
+  --json
+```
+
+The repository includes a shell adapter at
+[`integrations/generic-ci/verify.sh`](../integrations/generic-ci/verify.sh).
+It has no hosting-platform API dependency.
+
+Generic CI is the first-class provider-neutral boundary. A thin platform
+adapter may translate a pull request, merge request, branch comparison, or
+job baseline into the generic `revisionProvider`, `baseRevision`, and
+`headRevision` inputs, then present the canonical result. It must not add
+platform-specific trust rules to the protocol core or treat a platform status
+as a ForgeLoop signature.
+
+The adapter preserves the verifier exit contract:
+
+```text
+0 = VALID
+1 = INVALID, stale, uncovered, or untrusted
+2 = invocation, environment, configuration, or provider error
+```
+
+Missing or unavailable provider state is not a pass. The platform may publish
+annotations after the generic command returns, but it cannot override an
+invalid result or silently convert local success into publication, merge, or
+deployment evidence.
+
+## Mapping examples
+
+| Platform context | Base revision | Head revision |
+| --- | --- | --- |
+| GitHub change request | change-request base commit | change-request head commit |
+| GitLab merge request | merge-request diff base | pipeline commit |
+| Local branch comparison | `origin/main` | `HEAD` |
+| Enterprise CI | job-provided baseline | job-provided candidate |
+
+Adapters may add platform presentation, annotations, or status publication
+after the generic verifier returns. They must not reimplement coverage,
+content, evidence, or signature rules; override an invalid result; or require a
+platform API in the core package.
+
+Optional adapter examples must pin third-party actions or images immutably.
+No adapter is installed into an existing target by ordinary `init` or `update`.

package/docs/RECIPES.md

@@ -22,6 +22,12 @@ Concise, copy-paste friendly recipes for common ForgeLoop tasks.
 14. [Executable Policy, Baseline Ratchet, and Recovery](#recipe-14--executable-policy-baseline-ratchet-and-recovery)
 15. [Release and Reacquire Claims for an Abandoned Task](#recipe-15--release-and-reacquire-claims-for-an-abandoned-task)
 16. [Execute a Durable External Action Safely](#recipe-16--execute-a-durable-external-action-safely)
+17. [Bind a Task to the Current Workspace](#recipe-17--bind-a-task-to-the-current-workspace)
+18. [Create and Inspect an Immutable Handoff](#recipe-18--create-and-inspect-an-immutable-handoff)
+19. [Apply a Responsibility Contract](#recipe-19--apply-a-responsibility-contract)
+20. [Configure Trusted Narrow Verification](#recipe-20--configure-trusted-narrow-verification)
+21. [Generate and Verify Code Attestation](#recipe-21--generate-and-verify-code-attestation)
+22. [Verify a Revision Range](#recipe-22--verify-a-revision-range)
 
 ---
 
@@ -413,6 +419,138 @@ The efficiency comparison is present only when the scenario declares a
 positive `reference.comparableSteps`; absent host token/cost/model data stays
 unknown.
 
+---
+
+### Recipe 17 — Bind a Task to the Current Workspace
+
+Bind only when the task must remain in the current Git worktree. The binding is
+derived by ForgeLoop; do not supply branch or HEAD identity as actor input.
+
+```bash
+forgeloop workspace-bind --task task-001 --json
+forgeloop workspace-status --task task-001 --json
+```
+
+If the repository or worktree identity changes, `workspace-status` reports a
+mismatch and bound mutation or `run-check` fails closed before launch. Rebinding
+is an explicit new decision, not an automatic repair.
+
+---
+
+### Recipe 18 — Create and Inspect an Immutable Handoff
+
+Create a protocol-derived snapshot before changing tools or sessions, then
+inspect it from the receiving harness:
+
+```bash
+forgeloop handoff-create --task task-001 \
+  --recipient "next harness" \
+  --note "Continue verification" \
+  --json
+forgeloop handoff-list --task task-001 --json
+forgeloop handoff-show --task task-001 --id <handoffId> --json
+```
+
+The envelope is immutable and digest-bound. Its note and recipient hint are
+operational context only: a handoff is not delegation, authority, independent
+review evidence, or completion evidence. Use `continuity.json` for mutable
+resume notes and canonical execution artifacts for proof.
+
+---
+
+### Recipe 19 — Apply a Responsibility Contract
+
+Declare a mechanical pass boundary with allowed paths, read-only paths, and
+required checks. The label is descriptive and does not create an agent role.
+
+```bash
+forgeloop responsibility-set --task task-001 \
+  --label implementation \
+  --allowed-path src \
+  --read-only-path docs \
+  --required-check unit-tests \
+  --freeze-contract --freeze-route --freeze-claims \
+  --json
+forgeloop responsibility-status --task task-001 --json
+```
+
+Path changes, missing required checks, or drift in frozen inputs fail closed.
+
+---
+
+### Recipe 20 — Configure Trusted Narrow Verification
+
+Declare the checker capability in `.forgeloop/config.json`:
+
+```json
+{
+  "verification": {
+    "checkers": [
+      {
+        "checkId": "unit-tests",
+        "scopeMode": "PATH_ARGUMENTS",
+        "argvPrefix": ["node", "--test"],
+        "pathInsertion": "APPEND"
+      }
+    ]
+  }
+}
+```
+
+Resolve the scope and pass the exact returned paths to `run-check`:
+
+```bash
+forgeloop verify-scope --task task-001 --mode AUTO --json
+forgeloop run-check --task task-001 --id unit-tests \
+  --requirement "Unit tests" \
+  --scope-ref .forgeloop/task-state/<taskKey>/verification-scope.json \
+  -- node --test <paths-returned-by-verify-scope>
+```
+
+`AUTO` resolves to `CHANGED` or `CLAIMED` only with a trusted scoped checker;
+otherwise it resolves to `FULL`. Explicit `CHANGED` or `CLAIMED` without one
+returns `E_VERIFICATION_SCOPE_UNRESOLVED`. Any prefix or selected-path
+mismatch is rejected before the checker process starts.
+
+---
+
+### Recipe 21 — Generate and Verify Code Attestation
+
+After validator-backed completion, create the deterministic in-toto statement
+and verify its exact content without mutating the task:
+
+```bash
+forgeloop complete --task task-001 --json
+forgeloop attestation-create --task task-001 --json
+forgeloop attestation-status --task task-001 --json
+forgeloop attestation-verify --task task-001 --ref HEAD --json
+```
+
+The result is `PROCESSED` until the applicable relationships validate,
+`VERIFIED` when exact source and completion bindings validate, and `ATTESTED`
+only after a valid external signature passes the configured identity and issuer
+policy. No private key or token is persisted.
+
+---
+
+### Recipe 22 — Verify a Revision Range
+
+Use the provider-neutral command locally or from Generic CI:
+
+```bash
+forgeloop attestation-verify-range \
+  --revision-provider git \
+  --base origin/main \
+  --head HEAD \
+  --require-complete-coverage \
+  --json
+```
+
+The verifier reports changed, covered, uncovered, and conflicting paths. A
+coverage gap or conflicting task digest is invalid; provider or invocation
+failure is an error. This post-completion range result is distinct from the
+pre-completion verification scope used by one checker.
+
 ## Run ForgeLoop through MCP (safe mode)
 
 Start the local MCP adapter and inspect what it exposes:

package/docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,54 @@
+# ForgeLoop Release Checklist
+
+This is the current release checklist for `@cassiomc1/forgeloop`. It is a
+preparation and verification checklist; it does not authorize publication.
+
+## Contract and package identity
+
+- [ ] `package.json` and `package-lock.json` contain the same package version.
+- [ ] The package metadata declares the intended SPDX license (`MIT`).
+- [ ] `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.
+
+## Protocol and attestation
+
+- [ ] `npm run dependency:policy` passes without adding runtime dependencies.
+- [ ] `npm run lint` passes.
+- [ ] `npm test` passes.
+- [ ] `npm run coverage` passes the configured global and critical-module gates.
+- [ ] `npm run docs:check`, `npm run docs:generated:check`,
+      `npm run docs:conformance`, and `npm run docs:examples:check` pass.
+- [ ] `npm run docs:diagrams:check` and `npm run docs:diagram:inventory` pass;
+      every active diagram has typed source, dark-first animated HTML/SVG,
+      reduced-motion handling, a deterministic receipt, a text fallback, and
+      a current source-bound visual review.
+- [ ] `npm run completions:check` and `npm run summary:check` pass.
+- [ ] Workspace binding, handoff, responsibility, verification scope, revision,
+      manifest, statement, signature, and range-coverage tests pass.
+- [ ] Required attestation mode never leaves a task durably `COMPLETE` without
+      its code manifest.
+- [ ] Read-only attestation verification does not write task state or ledger
+      events.
+
+## Integration and cross-platform evidence
+
+- [ ] `npm run pack:check` and `npm run pack:smoke` pass.
+- [ ] `npm run mcp:test` either runs the configured MCP tests or reports the
+      single actionable setup prerequisite.
+- [ ] `npm run mcp:pack:check` passes when MCP dependencies are available.
+- [ ] Generic CI verification uses explicit provider, base, and head revisions.
+- [ ] Windows full-suite evidence is green on the main branch when scheduled.
+- [ ] Frozen Python 3.9+ validators pass with `python3 -m unittest discover -s tests`.
+- [ ] Secret scanning and Markdown validation pass.
+
+## Publication boundary
+
+- [ ] The exact validated commit is the release source.
+- [ ] GitHub Actions remain immutably pinned and use least-privilege permissions.
+- [ ] The npm workflow retains trusted OIDC publishing and explicit provenance.
+- [ ] Publication is performed only by the authorized release workflow.
+- [ ] Post-publication registry, tag, checksum, and release identity checks pass.
+
+Local package creation, a successful validation run, or a signed ForgeLoop
+attestation does not by itself prove npm publication or production deployment.

package/docs/REVISION_PROVIDERS.md

@@ -0,0 +1,136 @@
+# Revision Providers
+
+Revision providers supply the exact source snapshot used by ForgeLoop code
+manifests and revision-range coverage. The interface is source-control-host
+neutral; Git is the first implementation.
+
+## Contract
+
+A provider must expose these methods:
+
+```js
+{
+  detect(target),
+  getCurrentRevision(target),
+  getChangedEntries({ target, baseRevision, headRevision, paths }),
+  readContent({ target, revision, path }),
+  getContentIdentity({ target, revision, path }),
+  getRepositoryIdentity(target)
+}
+```
+
+Changed entries use normalized forward-slash paths and carry an operation,
+content kind, optional raw bytes, an optional provider content identity, and
+provider metadata. Provider revision identifiers are opaque to ForgeLoop.
+
+## Git provider
+
+The built-in `git` provider handles:
+
+- worktree, commit, index, and opaque revision reads;
+- exact raw bytes for files and symlink targets;
+- deletion, rename, copy, type-change, and Gitlink entries;
+- Git object identity when it is available;
+- literal path arguments through `execFile`, without shell interpolation.
+
+Select it explicitly in a range check:
+
+```bash
+forgeloop attestation-verify-range \
+  --revision-provider git \
+  --base origin/main \
+  --head HEAD \
+  --require-complete-coverage
+```
+
+Git metadata is an implementation detail of this provider. The attestation
+core does not import Git helpers and can accept a future snapshot or
+content-addressable provider without changing the statement schema.
+
+## Differential Verification Scope
+
+The provider boundary has two consumers with different semantics:
+
+1. Differential Verification uses current changed entries or effective task
+   claims to decide which paths one checker may execute before completion.
+2. Attestation and revision-range coverage use exact content and valid task
+   attestations to decide whether changed paths across a revision range are
+   covered after completion.
+
+A shared `RevisionProvider` does not make these questions interchangeable.
+Verification scope is an execution-safety boundary; attestation coverage is a
+provenance-coverage result. `CHANGED` or `CLAIMED` never means complete range
+coverage.
+
+### Trusted scoped checker
+
+Differential verification uses the same provider boundary as attestation. A
+project may opt into a narrow checker by declaring a schema-validated,
+deterministic descriptor in `.forgeloop/config.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "protocolVersion": 1,
+  "complianceMode": "standard",
+  "verification": {
+    "checkers": [
+      {
+        "checkId": "unit-tests",
+        "scopeMode": "PATH_ARGUMENTS",
+        "argvPrefix": ["node", "--test"],
+        "pathInsertion": "APPEND"
+      }
+    ]
+  }
+}
+```
+
+With this descriptor, `AUTO` may resolve to `CHANGED` or `CLAIMED`. The
+corresponding `run-check` invocation must contain the exact prefix followed by
+the selected canonical paths:
+
+```bash
+forgeloop verify-scope --task task-001 --mode CHANGED
+forgeloop run-check --task task-001 --id unit-tests \
+  --requirement "unit tests" \
+  --scope-ref .forgeloop/task-state/<task-key>/verification-scope.json \
+  -- node --test src/example.js
+```
+
+Without a trusted descriptor, `AUTO` resolves to `FULL`; explicit `CHANGED`
+and `CLAIMED` requests fail closed. A mismatched scoped argv is rejected
+before the checker process starts, and successful binding records the scope
+and capability fingerprints with the execution evidence.
+
+The [Verification Trust Flow](./assets/diagrams/forgeloop-verification-trust-flow.html)
+explorer and its [animated SVG fallback](./assets/diagrams/forgeloop-verification-trust-flow.svg)
+show the claims, provider changes, checker capability, fingerprints, exact
+argv, and observed evidence boundary. If no trusted checker exists, `AUTO`
+falls back to `FULL`; an explicit `CHANGED` or `CLAIMED` request returns
+`E_VERIFICATION_SCOPE_UNRESOLVED` rather than guessing.
+
+The canonical source is `docs/diagrams/forgeloop-verification-trust-flow.workflow.json`.
+
+## Error boundary
+
+Providers must expose stable ForgeLoop errors rather than requiring callers to
+parse command output:
+
+| Code | Meaning |
+| --- | --- |
+| `E_REVISION_PROVIDER_UNAVAILABLE` | No selected provider can service the target. |
+| `E_REVISION_PROVIDER_AMBIGUOUS` | Automatic detection found multiple providers. |
+| `E_REVISION_PROVIDER_INVALID` | Provider output or contract is malformed. |
+| `E_REVISION_NOT_FOUND` | The requested revision cannot be resolved. |
+| `E_REVISION_CONTENT_UNAVAILABLE` | The requested path content cannot be read. |
+
+Providers must reject unsafe or reserved paths, preserve deletion semantics,
+and distinguish a missing content path from an unavailable provider. Unknown
+provider semantics fail closed.
+
+## Conformance expectations
+
+An implementation should be tested for deterministic identity, exact bytes,
+binary and empty files, Unicode and space-containing paths, symlinks,
+Gitlinks, deletions, renames, path traversal, and stable error mapping.

package/docs/SIGNING_PROVIDERS.md

@@ -0,0 +1,83 @@
+# Signing Providers
+
+Signing providers are external authorities for ForgeLoop attestation
+signatures. They are separate from the provider-neutral attestation predicate
+and revision model.
+
+## Contract
+
+```js
+{
+  detect(),
+  sign({ target, statementPath, outputPath, bundlePath }),
+  verify({ target, statementPath, bundlePath, policy })
+}
+```
+
+The `none` provider is always available and yields `VERIFIED` at most. The
+optional `sigstore` provider can produce `ATTESTED` after successful Cosign
+verification under an exact signer policy.
+
+Signing is optional and never part of the basic completion path. When an
+external signer is unavailable, times out, exits nonzero, or returns output
+over the configured bound, the result stays `VERIFIED` only when the unsigned
+attestation itself validates; a policy that requires a signature returns an
+unavailable or invalid result and never upgrades trust. A manifest, receipt,
+npm provenance signal, or platform status is not a signature.
+
+## Sigstore boundary
+
+ForgeLoop delegates signing and verification to a locally available
+Cosign-compatible executable. The provider:
+
+- uses explicit argument arrays and no shell;
+- applies a bounded timeout and output limit;
+- never logs standard error as a persisted artifact;
+- accepts an optional trusted-root path;
+- keeps identity and issuer policy outside the signed predicate;
+- returns stable unavailable, invalid, identity, and issuer error codes.
+
+The provider must use bounded stdout/stderr capture and an explicit timeout.
+Those limits protect the adapter boundary; they do not make the external
+signer trustworthy by themselves. Credentials remain in the host environment
+or signer configuration and never enter a ForgeLoop artifact, statement, or
+receipt.
+
+Example external signing command:
+
+```bash
+cosign attest-blob \
+  --statement .forgeloop/task-state/<taskKey>/attestations/statement.json \
+  --bundle .forgeloop/task-state/<taskKey>/attestations/statement.sigstore.json \
+  --yes
+```
+
+ForgeLoop never stores the private key, OIDC token, access token, or signing
+credential. A bundle file is not trusted merely because it exists.
+
+## Policy
+
+```json
+{
+  "provider": "sigstore",
+  "required": true,
+  "policy": {
+    "issuer": "https://token.actions.githubusercontent.com",
+    "identities": ["https://github.com/example/project/.github/workflows/attest.yml@refs/heads/main"],
+    "requireTransparencyLog": true
+  }
+}
+```
+
+Exact identity and issuer policy is required for `ATTESTED`. Broad regular
+expressions and inferred trust are not accepted. Signature verification is
+optional in ordinary local audit; a consumer can require it in range
+verification with `--require-signature`.
+
+## Extension rules
+
+KMS, HSM, enterprise PKI, and other implementations may be registered without
+changing `statement.json`. They must not redefine ForgeLoop evidence binding,
+revision coverage, trust levels, or CLI result semantics. Provider conformance
+tests must cover unavailable tools, nonzero exits, invalid signatures, policy
+mismatches, timeouts, and bounded output.