@cassiomc1/forgeloop 1.8.1 → 1.10.0

package/THREAT_MODEL.md

@@ -124,6 +124,54 @@ provide a universal exactly-once guarantee.
 | Signature confusion | A plain digest or platform publication signal is presented as a cryptographic signature | External signing-provider boundary | `ATTESTED` requires a valid external signature under the requested signer policy; private keys and tokens never enter persisted artifacts | Trust in the external signer and transparency infrastructure remains outside ForgeLoop | `tests/signing-provider.test.js` |
 | Incomplete revision coverage | A changed source path has no valid task attestation or overlaps another task with a conflicting digest | Provider-neutral range coverage evaluator | Changed, covered, uncovered, and overlapping paths are computed from the selected revision provider; enforcement fails closed on gaps or conflicts | Coverage is limited to the provider's observable revision/content boundary | `tests/attestation-coverage.test.js`, `tests/generic-ci-attestation.test.js` |
 
+## Advisory context provider boundary
+
+Advisory provider output is untrusted external input. ForgeLoop exposes only a
+bounded, allowlisted, non-evidence and non-executable projection through the
+Integration API. Provider identity and availability are explicit; no provider
+is discovered or invoked by lifecycle commands, and provider text is never
+treated as trusted protocol input.
+
+| Threat | Mitigation | Residual limitation | Test evidence |
+| --- | --- | --- | --- |
+| Prompt injection in advisory results | Portable text checks, authority-field stripping, and `actionability: NON_EXECUTABLE` prevent provider text from becoming commands or lifecycle instructions | A host may still choose to display or act on advisory text outside ForgeLoop | `tests/advisory-context-security.test.js`, `tests/portable-context.test.js` |
+| Sensitive provider-output leakage | Secret-like values are rejected in selected portable fields; unknown fields are discarded before logging or projection | Unknown encodings and secrets returned only through an external host remain outside this scanner | `tests/advisory-context-security.test.js` |
+| Provider identity substitution | Registry key and resolved provider `id` must match the declared identity | A host that controls the runtime registry can replace its own provider before the call | `tests/advisory-context-runtime.test.js` |
+| Unbounded provider retrieval | Query, item, total-output, raw-result, and timeout budgets are normalized and enforced before/while provider execution | The host controls provider resource usage outside the bounded call | `tests/advisory-context-service.test.js`, `tests/advisory-context-provider.test.js` |
+| Historical command replay from advisory text | Advisory output cannot satisfy command input, evidence, state, or next-action authority; recall is never automatic | A receiving host must still avoid copying untrusted text into its own command runner | `tests/advisory-context-security.test.js` |
+| Handoff acceptance replay | Acceptance is keyed by the immutable handoff and consumer identity and is checked against the append-only ledger | External systems may still deliver duplicate messages; callers must surface the canonical rejection | `tests/handoff-acceptance.test.js` |
+| Handoff double-consumption race | Serialized ledger append and exactly-once acceptance projection permit one consumer; same-consumer retry is idempotent | Filesystem privilege outside ForgeLoop can still corrupt local artifacts | `tests/handoff-acceptance.test.js`, `tests/concurrent-ledger.test.js` |
+| Stale Git checkout acceptance | Acceptance compares the handoff snapshot with the current branch and HEAD, work-state, contract, route, and changed paths | A separately privileged process can change the checkout immediately after validation | `tests/handoff-acceptance.test.js` |
+| Stale contract/route handoff | Handoff creation and acceptance bind contract and route fingerprints and fail closed on drift | The caller must create a fresh handoff after a legitimate contract or route change | `tests/handoff-envelope.test.js`, `tests/handoff-acceptance.test.js` |
+| Invalid ledger projection | Handoff readers validate digest, event relationships, and the complete ledger; invalid history projects `INCONSISTENT`, never `OPEN` or `ACCEPTED` | Local consistency validation is not remote attestation against a privileged rewrite | `tests/handoff-acceptance.test.js`, `tests/handoff-tamper.test.js` |
+
+ForgeLoop does not make advisory text trusted. It makes the boundary explicit,
+bounded, and fail-closed where protocol-owned interpretation is required.
+
+## Structural-quality provider boundary
+
+Structural-quality observations are untrusted external data. The built-in
+adapter fixes the executable name to `sentrux`, passes `--mcp` with
+`shell: false`, validates the MCP handshake and minimum version, bounds
+combined stdout/stderr, and terminates a hung process. Project configuration
+cannot choose an executable path, shell fragment, arbitrary arguments, or a
+score. Runtime hosts may inject a provider only through the typed integration
+context.
+
+| Threat | Mitigation | Residual limitation | Test evidence |
+| --- | --- | --- | --- |
+| Malicious config launches `./sentrux` or another arbitrary executable | Config normalization rejects executable/argv/shell fields; built-in resolution uses the fixed `sentrux` command and shell-free spawn | A privileged host can launch its own process outside ForgeLoop | `tests/sentrux-structural-quality-provider.test.js` |
+| PATH resolves an unexpected executable | Provider/version/transport identity is recorded and the provider boundary remains explicit; portable artifacts omit absolute executable paths | PATH itself is host-managed and cannot prove binary provenance | `tests/sentrux-structural-quality-provider.test.js` |
+| Provider hangs, floods stdout/stderr, or sends malformed JSON-RPC | Monotonic request IDs, strict response validation, bounded output, timeout, SIGTERM, and bounded forced termination fail closed | A hostile process may still consume resources until the OS releases it | `tests/sentrux-structural-quality-provider.test.js` |
+| Provider leaks confidential fields or outside-project paths | Normalization applies secret scanning, string/list limits, project containment, and safe relative paths before persistence | Unknown encodings may require host-level review | `tests/structural-quality-provider.test.js` |
+| Provider version or provider configuration changes after baseline | Version, provider-config, policy, route, contract, and scope fingerprints bind baseline/current comparison; incompatible drift is incomparable | External files can change again after validation; architecture-rule provenance is intentionally a separate sensor | `tests/structural-quality-lifecycle.test.js`, `tests/structural-quality-policy.test.js` |
+| Agent launders a regression by replacing the baseline | Replacement is allowed only before `EXECUTING`; superseded fingerprints remain in the ledger | A separately privileged actor can rewrite all local artifacts | `tests/structural-quality-artifacts.test.js` |
+| Bundle quality evidence is tampered | Bundle import revalidates typed artifacts, bindings, fingerprints, cycle, and check references without rescanning | Local consistency is not remote attestation | `tests/structural-quality-bundle.test.js` |
+| Observe or diagnostic absence is misreported as success | Unavailable evidence maps to `NOT_OBSERVED`, absent diagnostics remain `null`, and only gate PASS satisfies the quality requirement | Provider capability still determines diagnostic detail | `tests/structural-quality-lifecycle.test.js`, `tests/sentrux-structural-quality-provider.test.js` |
+
+ForgeLoop never changes Sentrux analytics preferences, installs the provider,
+or treats Sentrux Free diagnostics as necessary for score correctness.
+
 ## Boundary rules
 
 - Safe paths are checked before reading or writing; no protocol field is a

package/completions/_forgeloop

@@ -1,7 +1,7 @@
 #compdef forgeloop
 # Generated by scripts/generate-shell-completions.mjs. Do not edit.
 _arguments \
-  '1:command:(action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle clear-continuity clear-state complete continuity doctor efficiency eval handoff-create handoff-list handoff-show history init inspect metrics migrate-protocol next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check status task-create task-list task-lock-status task-migrate task-recover task-repair-legacy-recovery task-resume task-scope task-show task-unlock trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status)' \
+  '1:command:(action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle clear-continuity clear-state complete continuity doctor efficiency eval handoff-accept handoff-create handoff-list handoff-show history init inspect metrics migrate-protocol next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check status task-create task-list task-lock-status task-migrate task-recover task-repair-legacy-recovery task-resume task-scope task-show task-unlock trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status)' \
   '*::options:->options'
 case $words[2] in
   action-authorize) _arguments '--action[durable action ID]' '--approval[current fingerprint-bound approval]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
@@ -28,6 +28,7 @@ case $words[2] in
   doctor) _arguments '--adopt[preserve an existing adapter in the manifest]' '--fix[restore missing managed template files]' '--help[show this help]' '--json[emit doctor findings as JSON]' '--path[target project directory (default: current directory)]' '--strict[treat warnings as unhealthy]' '--version[show the installed package version]' ;;
   efficiency) _arguments '--baseline[optional comparable efficiency baseline JSON]' '--help[show this help]' '--json[emit efficiency metrics as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   eval) _arguments '--help[show this help]' '--json[emit evaluation as JSON]' '--path[target project directory (default: current directory)]' '--scenario[project-local trajectory scenario JSON]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
+  handoff-accept) _arguments '--consumer-id[consumer identifier accepting the handoff]' '--handoff[handoff identifier]' '--harness[optional harness accepting the handoff]' '--help[show this help]' '--json[emit acceptance result as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   handoff-create) _arguments '--help[show this help]' '--json[emit handoff as JSON]' '--note[non-authoritative handoff note]' '--path[target project directory (default: current directory)]' '--recipient[non-authoritative recipient hint]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   handoff-list) _arguments '--help[show this help]' '--json[emit handoff list as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   handoff-show) _arguments '--help[show this help]' '--id[handoff identifier]' '--json[emit handoff as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
@@ -46,6 +47,9 @@ case $words[2] in
   profile-interview) _arguments '--dry-run[show planned interview questions without changing files]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--version[show the installed package version]' ;;
   progress) _arguments '--help[show this help]' '--json[emit progress evaluation as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   protocol-info) _arguments '--help[show this help]' '--json[emit complete machine-readable protocol metadata]' '--path[target project directory (default: current directory)]' '--version[show the installed package version]' ;;
+  quality-baseline) _arguments '--help[show this help]' '--json[emit baseline result as JSON]' '--path[target project directory (default: current directory)]' '--replace[replace a different baseline before EXECUTING]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--timeout-ms[bounded analyzer timeout in milliseconds]' '--version[show the installed package version]' ;;
+  quality-status) _arguments '--help[show this help]' '--json[emit persisted structural-quality status as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
+  quality-verify) _arguments '--help[show this help]' '--json[emit structural-quality verification as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--timeout-ms[bounded analyzer timeout in milliseconds]' '--version[show the installed package version]' ;;
   reconcile-closure) _arguments '--[exact command argv to execute as objective-satisfaction evidence]' '--details[additional structured execution details]' '--help[show this help]' '--id[contract verification item id used as evidence]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--requirement[exact contract verification item requirement text]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   reconcile-continuity) _arguments '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   record-check) _arguments '--command[recorded only as metadata; it is never executed]' '--details[additional structured check details]' '--evidence-kind[OBSERVED, INFERRED, NOT_VERIFIED, or BLOCKED]' '--execution-ref[ForgeLoop execution artifact reference]' '--exit-code[observed process exit code]' '--help[show this help]' '--id[stable check identifier]' '--json[emit structured output as JSON]' '--kind[check kind (default: command; use manual-review for manual evidence)]' '--path[target project directory (default: current directory)]' '--provenance[FORGELOOP_EXECUTED, ACTOR_REPORTED, or MANUAL_OBSERVATION]' '--requirement[completion requirement covered by the check]' '--result[observed result supplied by the actor]' '--status[passed, failed, blocked, or not-run]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;

package/completions/forgeloop.bash

@@ -30,6 +30,7 @@ _forgeloop() {
       doctor) command="doctor" ;;
       efficiency) command="efficiency" ;;
       eval) command="eval" ;;
+      handoff-accept) command="handoff-accept" ;;
       handoff-create) command="handoff-create" ;;
       handoff-list) command="handoff-list" ;;
       handoff-show) command="handoff-show" ;;
@@ -48,6 +49,9 @@ _forgeloop() {
       profile-interview) command="profile-interview" ;;
       progress) command="progress" ;;
       protocol-info) command="protocol-info" ;;
+      quality-baseline) command="quality-baseline" ;;
+      quality-status) command="quality-status" ;;
+      quality-verify) command="quality-verify" ;;
       reconcile-closure) command="reconcile-closure" ;;
       reconcile-continuity) command="reconcile-continuity" ;;
       record-check) command="record-check" ;;
@@ -88,7 +92,7 @@ _forgeloop() {
     esac
   done
   if [[ -z "\${command}" && "\${cur}" != -* ]]; then
-    COMPREPLY=( $(compgen -W 'action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle clear-continuity clear-state complete continuity doctor efficiency eval handoff-create handoff-list handoff-show history init inspect metrics migrate-protocol next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check status task-create task-list task-lock-status task-migrate task-recover task-repair-legacy-recovery task-resume task-scope task-show task-unlock trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status' -- "$cur") )
+    COMPREPLY=( $(compgen -W 'action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle clear-continuity clear-state complete continuity doctor efficiency eval handoff-accept handoff-create handoff-list handoff-show history init inspect metrics migrate-protocol next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check status task-create task-list task-lock-status task-migrate task-recover task-repair-legacy-recovery task-resume task-scope task-show task-unlock trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status' -- "$cur") )
     return
   fi
   case "\${command}" in
@@ -116,6 +120,7 @@ _forgeloop() {
     doctor) COMPREPLY=( $(compgen -W '--adopt --fix --help --json --path --strict --version' -- "$cur") );;
     efficiency) COMPREPLY=( $(compgen -W '--baseline --help --json --path --task --version' -- "$cur") );;
     eval) COMPREPLY=( $(compgen -W '--help --json --path --scenario --task --version' -- "$cur") );;
+    handoff-accept) COMPREPLY=( $(compgen -W '--consumer-id --handoff --harness --help --json --path --task --version' -- "$cur") );;
     handoff-create) COMPREPLY=( $(compgen -W '--help --json --note --path --recipient --task --version' -- "$cur") );;
     handoff-list) COMPREPLY=( $(compgen -W '--help --json --path --task --version' -- "$cur") );;
     handoff-show) COMPREPLY=( $(compgen -W '--help --id --json --path --task --version' -- "$cur") );;
@@ -134,6 +139,9 @@ _forgeloop() {
     profile-interview) COMPREPLY=( $(compgen -W '--dry-run --help --json --path --version' -- "$cur") );;
     progress) COMPREPLY=( $(compgen -W '--help --json --path --task --version' -- "$cur") );;
     protocol-info) COMPREPLY=( $(compgen -W '--help --json --path --version' -- "$cur") );;
+    quality-baseline) COMPREPLY=( $(compgen -W '--help --json --path --replace --task --timeout-ms --version' -- "$cur") );;
+    quality-status) COMPREPLY=( $(compgen -W '--help --json --path --task --version' -- "$cur") );;
+    quality-verify) COMPREPLY=( $(compgen -W '--help --json --path --task --timeout-ms --version' -- "$cur") );;
     reconcile-closure) COMPREPLY=( $(compgen -W '-- --details --help --id --json --path --requirement --task --version' -- "$cur") );;
     reconcile-continuity) COMPREPLY=( $(compgen -W '--help --json --path --task --version' -- "$cur") );;
     record-check) COMPREPLY=( $(compgen -W '--command --details --evidence-kind --execution-ref --exit-code --help --id --json --kind --path --provenance --requirement --result --status --task --version' -- "$cur") );;

package/completions/forgeloop.fish

@@ -1,5 +1,5 @@
 # Generated by scripts/generate-shell-completions.mjs. Do not edit.
-complete -c forgeloop -f -n '__fish_use_subcommand' -a 'action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle clear-continuity clear-state complete continuity doctor efficiency eval handoff-create handoff-list handoff-show history init inspect metrics migrate-protocol next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check status task-create task-list task-lock-status task-migrate task-recover task-repair-legacy-recovery task-resume task-scope task-show task-unlock trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status'
+complete -c forgeloop -f -n '__fish_use_subcommand' -a 'action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle clear-continuity clear-state complete continuity doctor efficiency eval handoff-accept handoff-create handoff-list handoff-show history init inspect metrics migrate-protocol next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check status task-create task-list task-lock-status task-migrate task-recover task-repair-legacy-recovery task-resume task-scope task-show task-unlock trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from action-authorize' -l 'action' -d 'durable action ID'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from action-authorize' -l 'approval' -d 'current fingerprint-bound approval'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from action-authorize' -l 'help' -d 'show this help'
@@ -173,6 +173,14 @@ complete -c forgeloop -f -n '__fish_seen_subcommand_from eval' -l 'path' -d 'tar
 complete -c forgeloop -f -n '__fish_seen_subcommand_from eval' -l 'scenario' -d 'project-local trajectory scenario JSON'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from eval' -l 'task' -d 'task ID to operate on (when omitted, resolved from context or single active task)'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from eval' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -l 'consumer-id' -d 'consumer identifier accepting the handoff'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -l 'handoff' -d 'handoff identifier'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -l 'harness' -d 'optional harness accepting the handoff'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -l 'help' -d 'show this help'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -l 'json' -d 'emit acceptance result as JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -l 'task' -d 'task ID to operate on (when omitted, resolved from context or single active task)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-accept' -l 'version' -d 'show the installed package version'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-create' -l 'help' -d 'show this help'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-create' -l 'json' -d 'emit handoff as JSON'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from handoff-create' -l 'note' -d 'non-authoritative handoff note'
@@ -279,6 +287,24 @@ complete -c forgeloop -f -n '__fish_seen_subcommand_from protocol-info' -l 'help
 complete -c forgeloop -f -n '__fish_seen_subcommand_from protocol-info' -l 'json' -d 'emit complete machine-readable protocol metadata'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from protocol-info' -l 'path' -d 'target project directory (default: current directory)'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from protocol-info' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-baseline' -l 'help' -d 'show this help'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-baseline' -l 'json' -d 'emit baseline result as JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-baseline' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-baseline' -l 'replace' -d 'replace a different baseline before EXECUTING'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-baseline' -l 'task' -d 'task ID to operate on (when omitted, resolved from context or single active task)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-baseline' -l 'timeout-ms' -d 'bounded analyzer timeout in milliseconds'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-baseline' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-status' -l 'help' -d 'show this help'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-status' -l 'json' -d 'emit persisted structural-quality status as JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-status' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-status' -l 'task' -d 'task ID to operate on (when omitted, resolved from context or single active task)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-status' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-verify' -l 'help' -d 'show this help'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-verify' -l 'json' -d 'emit structural-quality verification as JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-verify' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-verify' -l 'task' -d 'task ID to operate on (when omitted, resolved from context or single active task)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-verify' -l 'timeout-ms' -d 'bounded analyzer timeout in milliseconds'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from quality-verify' -l 'version' -d 'show the installed package version'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from reconcile-closure' -l '' -d 'exact command argv to execute as objective-satisfaction evidence'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from reconcile-closure' -l 'details' -d 'additional structured execution details'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from reconcile-closure' -l 'help' -d 'show this help'

package/docs/ADVISORY_CONTEXT.md

@@ -0,0 +1,174 @@
+# Advisory Context & External Provider Boundary
+
+## Overview
+
+ForgeLoop treats external advisory context as **optional, host-injected, lazy,
+and strictly advisory**.
+
+The core invariant of the protocol is:
+
+```
+MEMORY != STATE
+MEMORY != EVIDENCE
+MEMORY != AUTHORITY
+MEMORY != COMPLETION
+MEMORY != NEXT ACTION
+```
+
+ForgeLoop contains **no built-in vector database, SQLite engine, or full-text search (FTS)** dependencies. Memory systems belong to hosts, IDEs, orchestrators, and harnesses. ForgeLoop provides the hardened runtime contract, trust boundary, portable text sanitization, and allowlist normalization.
+
+## Architectural Boundaries
+
+1. **Non-Authoritative (`ADVISORY`)**: Advisory memory can provide context or suggestions to an agent, but cannot dictate lifecycle state, phase transitions, or next actions.
+2. **Non-Evidence (`evidenceAuthority: "NONE"`)**: Stored memories or suggestions cannot satisfy verification requirements, pass gates, or serve as execution receipts.
+3. **Non-Executable (`actionability: "NON_EXECUTABLE"`)**: Output items cannot be executed directly as protocol commands.
+4. **Ephemeral & Unpersisted (`persisted: false`)**: ForgeLoop never persists external recall results to `.forgeloop/` state or the event ledger.
+5. **Lazy Provider Evaluation**: ForgeLoop runtime commands (`next`, `status`, `preflight`, `complete`, `task-show`, etc.) never invoke advisory memory providers. Recall occurs only when a host explicitly invokes the integration recall service.
+
+## Registering Providers
+
+Hosts configure providers through the runtime context:
+
+```javascript
+import { createForgeLoopContext } from "@cassiomc1/forgeloop/integration";
+
+const runtimeContext = createForgeLoopContext({
+  advisoryContextProviders: {
+    "my-memory": {
+      id: "my-memory",
+      version: "1.0.0",
+      async recall({ projectPath, taskId, query, limit, maxItemChars, maxTotalChars, timeoutMs }) {
+        // Query host vector database, knowledge base, or memory cache
+        return {
+          items: [
+            {
+              title: "Previous Architecture Decision",
+              summary: "Decided to use rotating refresh tokens with 15-minute expiry.",
+              sourceRef: "docs/decisions/auth-tokens.md",
+              confidence: 0.95,
+            },
+          ],
+        };
+      },
+    },
+  },
+});
+```
+
+Provider IDs must match `^[a-z0-9][a-z0-9_-]*$`. Providers may be plain objects or async factory functions. The registry key and the resolved provider `id` must match exactly; a factory that resolves to another identity fails with `E_ADVISORY_CONTEXT_PROVIDER_INVALID` before `recall` is called.
+
+## Querying Advisory Context
+
+Hosts explicitly invoke `recallAdvisoryContext`:
+
+```javascript
+import { recallAdvisoryContext } from "@cassiomc1/forgeloop/integration";
+
+const result = await recallAdvisoryContext({
+  target: "/path/to/project",
+  taskId: "auth-impl-42",
+  providerName: "my-memory",
+  query: "token refresh strategy",
+  limit: 5,
+  runtimeContext,
+});
+```
+
+### Result Schema
+
+Every returned result is normalized, frozen, and stamped with immutable trust metadata:
+
+```json
+{
+  "provider": {
+    "id": "my-memory",
+    "version": "1.0.0"
+  },
+  "taskId": "auth-impl-42",
+  "authority": "ADVISORY",
+  "evidenceAuthority": "NONE",
+  "actionability": "NON_EXECUTABLE",
+  "trustRole": "NON_EVIDENCE_ADVISORY_CONTEXT",
+  "persisted": false,
+  "items": [
+    {
+      "title": "Previous Architecture Decision",
+      "summary": "Decided to use rotating refresh tokens with 15-minute expiry.",
+      "sourceRef": "docs/decisions/auth-tokens.md",
+      "confidence": 0.95,
+      "itemFingerprint": "4a7d...3b1f"
+    }
+  ]
+}
+```
+
+## Normalization & Authority Stripping
+
+ForgeLoop checks the raw result shape and item count, then selects bounded items and projects only allowlisted fields before portable safety inspection. Unknown raw fields—including secret-like or cyclic metadata—are discarded and are never copied or logged. A secret in a selected field still fails closed.
+
+Any raw fields returned by a provider that attempt to assert protocol authority are completely stripped during normalization:
+
+- `nextAction`, `command`, `phase`
+- `evidence`, `approval`, `authority`
+- `writeClaims`, `changedPaths`, `checkIds`
+
+Only allowlisted fields (`title`, `summary`, `sourceRef`, `observedAt`, `confidence`) survive. Each item receives a deterministic SHA-256 `itemFingerprint`.
+
+## Portable Safety Boundary
+
+All text flowing into or out of advisory recall is verified:
+
+- **Control Character Rejection**: ASCII control characters (`\x00-\x08`, `\x0B-\x0C`, `\x0E-\x1F`, `\x7F`) throw `E_PORTABLE_CONTEXT_INVALID`.
+- **Secret Scanning**: Inputs and outputs containing secret tokens (e.g., `Bearer <token>`, `ghp_`, AWS keys, private keys) throw `E_PORTABLE_CONTEXT_INVALID`.
+- **Budget Enforcements**:
+
+  - Max query characters: 1,000 chars (`E_ADVISORY_CONTEXT_QUERY_INVALID`)
+  - Max item summary: 4,000 chars (`E_ADVISORY_CONTEXT_OUTPUT_LIMIT`)
+  - Default item limit: 6 items (max 20)
+  - Default total characters: 6,000 chars (max 16,000) (`E_ADVISORY_CONTEXT_OUTPUT_LIMIT`)
+  - Raw provider result ceiling: 100 items (`E_ADVISORY_CONTEXT_OUTPUT_LIMIT`)
+  - Default timeout: 5,000 ms, max 30,000 ms (`E_ADVISORY_CONTEXT_TIMEOUT`)
+
+ForgeLoop normalizes recall limits before provider dispatch. Valid oversized
+integer requests are clamped to the canonical maxima, and non-finite,
+non-integer, below-minimum, string, boolean, object, or null values fail before
+provider lookup with `E_ADVISORY_CONTEXT_REQUEST_INVALID`. Providers therefore
+never receive caller-requested budgets above ForgeLoop's supported maxima.
+
+## Replay safety and failure handling
+
+Advisory recall is an explicit host operation. ForgeLoop does not record a
+provider query, provider response, or item fingerprint in the task event ledger,
+and a later recall is never treated as proof that an earlier response was
+current. Hosts should re-query when context is needed and must independently
+validate any proposed action or lifecycle step against canonical state.
+
+Provider failures remain advisory failures and do not block the canonical loop.
+The public boundary reports these stable codes:
+
+| Code | Meaning |
+| --- | --- |
+| `E_ADVISORY_CONTEXT_PROVIDER_INVALID` | Provider identity or recall contract is invalid. |
+| `E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE` | The requested provider is not registered in the runtime context. |
+| `E_ADVISORY_CONTEXT_QUERY_INVALID` | The query is empty, unsafe, or exceeds the query budget. |
+| `E_ADVISORY_CONTEXT_REQUEST_INVALID` | A recall budget has an invalid type, range, or numeric value. |
+| `E_ADVISORY_CONTEXT_RESULT_INVALID` | The provider returned an invalid result shape. |
+| `E_ADVISORY_CONTEXT_TIMEOUT` | Provider recall exceeded the bounded timeout. |
+| `E_ADVISORY_CONTEXT_OUTPUT_LIMIT` | The raw or normalized provider output exceeded a bounded limit. |
+| `E_PORTABLE_CONTEXT_INVALID` | Portable text contains unsafe controls, secrets, or unsupported content. |
+
+## What ForgeLoop Never Does Automatically
+
+- It does not look up a provider on startup.
+- It does not look up a provider for `status`, `next`, `preflight`, `complete`,
+  `task-show`, or the read-only `task/context` resource.
+- It does not persist provider results, queries, or provider metadata in
+  `.forgeloop/` or the event ledger.
+- It does not turn provider text into a command, lifecycle transition, check,
+  evidence record, approval, claim, or next action.
+- It does not infer provider trust from a package version, a source path, or a
+  host label. The provider identity contract is resolved at the Integration
+  API boundary and remains descriptive rather than authenticated authority.
+
+The host owns whether and when to display or use advisory context. ForgeLoop
+owns only the bounded normalization and trust-role projection.

package/docs/AGENT_PROTOCOL_SUMMARY.md

@@ -7,7 +7,7 @@
 ForgeLoop is a portable protocol and support CLI for verifiable engineering workflows. It records and validates task state, contracts, routing, checks, evidence, continuity, and optional code attestations. It does not become an agent scheduler, delegation service, source-control authority, or secret manager.
 
 Protocol version: 1
-Package version: 1.8.1
+Package version: 1.10.0
 
 ## Canonical loop
 
@@ -74,7 +74,8 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | Feature | Version | Supported |
 | --- | --- | --- |
 | adaptiveExecutionProfiles | 1 | yes |
-| canonicalHandoffs | 1 | yes |
+| advisoryContextProviders | 1 | yes |
+| canonicalHandoffs | 2 | yes |
 | capabilityPolicy | 1 | yes |
 | codeAttestation | 1 | yes |
 | compactLifecycleOutput | 1 | yes |
@@ -90,6 +91,7 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | observabilityStability | n/a | yes |
 | reflection | 1 | yes |
 | responsibilityConstraints | 1 | yes |
+| structuralQuality | 1 | yes |
 | structuredTrace | 1 | yes |
 | taskClaimRecovery | 1 | yes |
 | taskInspection | 1 | yes |
@@ -99,6 +101,21 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | verificationExecutionIsolation | 1 | yes |
 | workspaceBinding | 1 | yes |
 
+## Capability contracts
+
+- `canonicalHandoffs` v2: immutable, supported, and
+  ledger-backed for exactly-once operational acceptance through
+  `handoff-accept`. Acceptance statuses are
+  `OPEN` / `ACCEPTED` / `UNBOUND` / `INCONSISTENT`; it creates no claims,
+  evidence, or lifecycle authority.
+- `advisoryContextProviders` v1: provider-neutral,
+  Integration-API-only, lazy, and opt-in. Provider results are not persisted by
+  ForgeLoop and are never lifecycle state, evidence, authority, or executable
+  instructions.
+
+Protocol v1, schema v1, and Integration API v1 remain independent of these
+capability-family versions.
+
 ## Public artifact registry
 
 | Key | Scope | Path | Schema | Trust role |
@@ -131,6 +148,7 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | session | SESSION | .forgeloop/sessions/<session-id>.json | activation | SESSION_MARKER |
 | sources | PROJECT | .forgeloop/sources.json | source-registry | SOURCE_ATTESTATION |
 | state | TASK | .forgeloop/task-state/<task-key>/work-state.json | work-state | CANONICAL_LIFECYCLE_STATE |
+| structuralQuality | TASK | .forgeloop/task-state/<task-key>/structural-quality/baseline.json | structural-quality | STRUCTURAL_QUALITY_EVIDENCE |
 | usage | TASK | .forgeloop/task-state/<task-key>/usage.json | usage | INFORMATIONAL_USAGE_TELEMETRY |
 | verificationScope | TASK | .forgeloop/task-state/<task-key>/verification-scope.json | verification-scope | VERIFICATION_SCOPE_PLAN |
 | workspaceBinding | TASK | .forgeloop/task-state/<task-key>/workspace-binding.json | workspace-binding | WORKSPACE_IDENTITY_BINDING |
@@ -246,12 +264,21 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | responsibility-set | MUTATING | Creates immutable, mechanically verifiable constraints for a task pass. |
 | responsibility-status | READ_ONLY | Validates active responsibility constraints against current paths, inputs, and checks. |
 
+### task
+
+| Command | Mutation | Purpose |
+| --- | --- | --- |
+| handoff-accept | MUTATING | Accepts an immutable handoff exactly once in the task event ledger. |
+
 ### verification
 
 | Command | Mutation | Purpose |
 | --- | --- | --- |
 | audit | READ_ONLY | Performs read-only evaluation of verification receipt coverage and gate satisfaction. |
 | prepare-completion | MUTATING | Initializes execution-receipt.json with empty requirement evidence slots for the active cycle. |
+| quality-baseline | EXTERNAL_EXECUTION | Captures an immutable provider-neutral structural-quality baseline through the trusted analyzer adapter. |
+| quality-status | READ_ONLY | Projects persisted structural-quality baseline and evaluation status without invoking a provider. |
+| quality-verify | EXTERNAL_EXECUTION | Captures one bounded structural-quality evaluation and projects it into canonical verification evidence. |
 | record-check | MUTATING | Records structured verification evidence (command, manual review, or test output) against a requirement. |
 | record-terminal-result | MUTATING | Records external terminal result evidence (PUBLICATION or PRODUCTION_READINESS) into receipt. |
 | report | READ_ONLY | Emits a human-readable or structured JSON summary report of protocol state. |
@@ -296,8 +323,12 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | E_ATTESTATION_TARGET_REF_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
 | E_ATTESTATION_UNSIGNED | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
 | E_CLI_INVOCATION_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_HANDOFF_ACCEPTANCE_INCONSISTENT | Handoff acceptance disagrees with task event ledger history. |
+| E_HANDOFF_ACCEPTANCE_UNBOUND | Handoff snapshot lacks required workStateFingerprint binding. |
+| E_HANDOFF_ALREADY_ACCEPTED | Handoff was already accepted by a different consumer. |
 | E_HANDOFF_INVALID | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
 | E_HANDOFF_NOT_FOUND | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
+| E_HANDOFF_STALE | Handoff snapshot has drifted from the current canonical task state or repository. |
 | E_HANDOFF_STATE_UNAVAILABLE | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
 | E_HANDOFF_TAMPERED | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |
 | E_RESPONSIBILITY_FROZEN_INPUT_DRIFT | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. |