@cassiomc1/forgeloop 0.1.14 → 0.1.15

package/.forgeloop/forgeloop.gitignore

@@ -1,2 +1,3 @@
 # Local resumable task state is untrusted, target-specific data.
 work-state.json
+executions/

package/LOOP_ENGINEERING.md

@@ -52,6 +52,7 @@ the supported ForgeLoop lifecycle commands or canonical ForgeLoop APIs:
 - `.forgeloop/work-state.json`
 - `.forgeloop/events.ndjson`
 - `.forgeloop/execution-receipt.json`
+- `.forgeloop/executions/<executionId>.json`
 - completion recovery metadata
 - canonical check/evidence state
 - terminal-result lifecycle state
@@ -117,11 +118,32 @@ Every verification command path is classified by resolution mode:
 | `LOCAL_EXECUTABLE` | `node scripts/test.js`, `python3 -m unittest`, `./bin/check` | No | No |
 | `LOCAL_PACKAGE_BINARY` | `./node_modules/.bin/tool`, `npm test`, `pnpm test`, `yarn test` | No | No |
 | `NON_INSTALLING_RESOLUTION` | `npx --no-install tool`, `npx --no tool` | No | No |
-| `INSTALL_CAPABLE_RESOLUTION` | `npx tool`, `pnpm dlx tool`, `yarn dlx tool`, `bunx tool`, `uvx tool`, `pipx run tool` | Yes | Yes (`E_INSTALLATION_AUTHORITY_REQUIRED`) |
+| `INSTALL_CAPABLE_RESOLUTION` | `npx tool`, `npm exec tool`, `npm x tool`, `pnpm dlx tool`, `yarn dlx tool`, `bunx tool`, `uvx tool`, `pipx run tool` | Yes | Yes (`E_INSTALLATION_AUTHORITY_REQUIRED`) |
 | `EXPLICIT_INSTALLATION` | `npm install tool`, `pnpm add tool`, `pip install tool`, `cargo install tool` | Yes | Yes (`E_INSTALLATION_AUTHORITY_REQUIRED`) |
 
 **Validator-enforced rule**: Any verification command executed via an installation-capable or explicit-installation resolution mode without a valid canonical installation authority grant is rejected by `record-check`, `audit`, and `complete` with error code `E_INSTALLATION_AUTHORITY_REQUIRED`, `E_AUTHORITY_INVALID`, `E_AUTHORITY_SCOPE_MISMATCH`, or `E_AUTHORITY_UNTRUSTED_SOURCE` and cannot contribute to `VALID` completion.
 
+Recognized command dispatchers (such as `npm test`, `npm start`, `npm stop`, `npm restart`, `npm run <script>`, `npm run-script <script>`, `npm rum <script>`, `npm urn <script>`) are classified by their effective package resolution behavior across recognized lifecycle scripts before process launch. npm invocation parsing recognizes options (e.g. `--silent`, `--loglevel=error`) before the subcommand. Recognized npm-script dispatch is resolved recursively before process launch. `npm restart` uses npm's restart-specific lifecycle semantics (`prerestart`, `prestop`, `stop`, `poststop`, `prestart`, `start`, `poststart`, `postrestart` when `restart` is absent; `prerestart`, `restart`, `postrestart` when `restart` is present) rather than generic pre/main/post handling. ForgeLoop fails closed (`mayInstall: true`) when recursive npm-script resolution encounters a cycle or exceeds its maximum resolution depth (16). ForgeLoop does not resolve npm workspace selection in `run-check` for `0.1.15`. npm script executions using `--workspace`, `-w`, `--workspaces`, or `--ws` fail closed (`E_COMMAND_RESOLUTION_AMBIGUOUS`) because the effective `package.json` execution context may differ from the current ForgeLoop target. Run ForgeLoop against the selected workspace directory directly instead. If any nested lifecycle script invokes an installation-capable command (such as `npx`, `npm exec`, or `pnpm dlx`), the execution is elevated to `INSTALL_CAPABLE_RESOLUTION` and blocked before launch without authority.
+
+**npm Classification Model**: npm classification is semantic and fail-closed. Unknown npm commands are not assumed safe. The classifier specifically identifies install-capable families including: `exec`/`x`, `install` aliases, `ci` aliases, `install-test` families, `install-ci-test` families, `update` aliases, `audit fix`, and conditional `init`/`create`/`innit` invocations. Unknown or ambiguous semantics fail closed (`E_COMMAND_RESOLUTION_AMBIGUOUS`).
+
+Use `forgeloop run-check --id <id> --requirement <requirement> -- <argv>` for
+observed command evidence. ForgeLoop preserves the exact argv vector, target
+cwd, resolution classification, timestamps, exit status, and task/check
+binding in `.forgeloop/executions/<executionId>.json` before recording the
+check. Resolution is classified before process launch; install-capable
+resolution is rejected without a valid host-attested authority, while
+`npx --no-install` remains a non-installing path and may fail honestly when a
+tool is absent. `run-check` launches the supplied argv without a shell.
+
+`forgeloop record-check` is serialization-only. Its `--command` value is
+metadata and is never executed. A `kind: command`, `evidenceKind: OBSERVED`
+check must carry `provenance: FORGELOOP_EXECUTED` and a valid `executionRef`;
+manual or actor-reported observations must use an explicit non-command kind or
+provenance and must not be upgraded to command execution evidence. Completion,
+audit, protocol validation, and bundles revalidate the referenced artifact and
+its task, check, requirement, cycle, cwd, status, and exit-code binding.
+
 Authority cannot be self-issued by the actor consuming it. Boolean fields inside verification evidence (such as `installationAuthorized: true`) are not sufficient proof of installation authority. Installation authority must be established via a canonical authority grant supplied by a host/operator trust boundary and referenced via `installationAuthorityRef`.
 
 The runtime authority context has two modes:
@@ -509,7 +531,7 @@ prepare-completion
     ↓
 run applicable project checks
     ↓
-record observed results with record-check
+run commands with run-check; record manual observations with record-check
     ↓ forgeloop next
 advance --to REVIEWING
     ↓ forgeloop next
@@ -524,10 +546,11 @@ subsequent `record-check` operations; completion remains invalid until required
 observed evidence, review state, chronology, and validator requirements are
 satisfied.
 
-The host agent runs applicable checks after the receipt exists, records their
-observed results with `record-check`, and queries `forgeloop next` before each
-subsequent lifecycle action. `record-check` records results already observed by
-the agent; it never executes the supplied command text.
+The host agent runs applicable checks after the receipt exists, uses `run-check`
+for commands, and uses `record-check` for manual or non-command observations.
+`run-check` records exact command provenance; `record-check` records supplied
+metadata only and never executes its `--command` value. Query `forgeloop next`
+before each subsequent lifecycle action.
 
 Continue until the terminal outcome is either validator-backed `COMPLETE` or
 an explicitly reported `BLOCKED` / `PARTIALLY VERIFIED` result with exact

package/PROTOCOL_INTEGRATION.md

@@ -128,6 +128,7 @@ The following protocol artifacts are strictly owned by ForgeLoop:
 - `.forgeloop/work-state.json`
 - `.forgeloop/events.ndjson`
 - `.forgeloop/execution-receipt.json`
+- `.forgeloop/executions/<executionId>.json`
 - Canonical check, evidence, and terminal-result state
 
 If the required CLI or API capability cannot be resolved:
@@ -140,6 +141,38 @@ If the required CLI or API capability cannot be resolved:
 
 Report the corresponding ForgeLoop dimension as `NOT_VERIFIED` / `E_FORGELOOP_CLI_UNAVAILABLE`.
 
+## Trusted command provenance
+
+Command verification has two explicit paths:
+
+- `forgeloop run-check --id <id> --requirement <requirement> -- <argv>` owns
+  execution. It classifies the exact argv before launch, uses a non-shell
+  process boundary, records the target cwd, resolution mode, timestamps,
+  exit status, and task/check binding in
+  `.forgeloop/executions/<executionId>.json`, then records an `OBSERVED` check
+  with `provenance: FORGELOOP_EXECUTED`.
+- `forgeloop record-check` owns serialization only. `--command` is metadata and
+  is never launched. A `kind: command` check with `evidenceKind: OBSERVED`
+  requires both `executionRef` and `FORGELOOP_EXECUTED`; manual or actor-reported
+  observations use their explicit non-command/provenance values and remain
+  distinguishable from process execution.
+
+`run-check` rejects install-capable resolution before process launch unless the
+host supplies a valid trusted authority context. `npm exec` and `npm x` are
+installation-capable resolution paths. Recognized command dispatchers (such as
+`npm test`, `npm restart`, `npm run`, `npm rum`, `npm urn`) are resolved
+recursively across recognized lifecycle scripts before launch with cycle
+detection, leading option normalization, and restart-specific lifecycle fallback.
+npm workspace script executions (`--workspace`, `-w`, `--workspaces`, `--ws`) fail
+closed before launch with `E_COMMAND_RESOLUTION_AMBIGUOUS` because the effective
+`package.json` context cannot be proven from the root target. Unknown npm command semantics are rejected before execution rather than downgraded to local execution. ForgeLoop uses an explicit non-installing allowlist instead of assuming that unrecognized npm commands are safe. `npx --no-install` is
+an allowed non-installing resolution and can return a normal failed result when
+the requested tool is unavailable. Completion, audit, `validate-protocol`, and task
+bundles revalidate execution references rather than trusting duplicated check
+metadata. Invalid or missing references return `E_EXECUTION_REF_INVALID`; an
+observed command without ForgeLoop provenance returns
+`E_COMMAND_PROVENANCE_UNATTESTED`.
+
 ## Missing tool capability
 
 A missing tool is a capability gap, not installation authority.

package/README.md

@@ -110,11 +110,14 @@ owned cleanup. The frozen published installation under
 [`tests/fixtures/legacy-0.1.6/`](./tests/fixtures/legacy-0.1.6/) is derived
 from the real npm tarball, includes provenance and digests, and is copied into
 The latest verified published npm release is `@cassiomc1/forgeloop@0.1.14`.
-The repository release is `0.1.14`.
+The repository package candidate is `@cassiomc1/forgeloop@0.1.15`; it is not
+published yet.
 Earlier `0.1.8`, `0.1.9`, `0.1.10`, `0.1.11`, `0.1.12`, and `0.1.13` references are historical; never move
 their tags or `v0.1.10`. Release `0.1.14` enforces verification installation
 authority, provides recoverable stale receipt lifecycle in `prepare-completion`,
-and validates single-actor protocol runs.
+and validates single-actor protocol runs. The `0.1.15` candidate adds trusted
+command execution provenance without changing the v1 lifecycle or authority
+boundary.
 
 ## How to prompt ForgeLoop
 
@@ -204,7 +207,8 @@ project without overwriting local instructions. When the package is available
 in the npm registry, use the commands below; otherwise use the repository
 checkout fallback.
 
-The current repository package is `@cassiomc1/forgeloop@0.1.14`.
+The current repository package candidate is `@cassiomc1/forgeloop@0.1.15` and is
+not yet published.
 The latest verified published npm release is `@cassiomc1/forgeloop@0.1.14`.
 For reproducible published-package runs or release-identity checks,
 pin the published version:
@@ -233,7 +237,8 @@ npx @cassiomc1/forgeloop advance --to PLANNED
 npx @cassiomc1/forgeloop advance --to EXECUTING
 npx @cassiomc1/forgeloop advance --to VERIFYING
 npx @cassiomc1/forgeloop prepare-completion --json
-npx @cassiomc1/forgeloop record-check --id tests --requirement tests --status passed --evidence-kind OBSERVED --command "npm test" --result "exit 0" --exit-code 0 --json
+npx @cassiomc1/forgeloop run-check --json --id tests --requirement tests -- npm test
+npx @cassiomc1/forgeloop record-check --id docs-review --kind manual-review --requirement "documentation synchronized" --status passed --evidence-kind OBSERVED --provenance MANUAL_OBSERVATION --result "reviewed" --json
 npx @cassiomc1/forgeloop record-terminal-result --requirement "Package published" --type PUBLICATION --status published --source "npm publish" --result "Published package to npm" --json
 npx @cassiomc1/forgeloop advance --to REVIEWING
 npx @cassiomc1/forgeloop audit --json
@@ -263,7 +268,7 @@ implementation
 → forgeloop next
 → prepare-completion
 → forgeloop next
-→ checks + record-check
+→ checks + run-check/record-check
 → forgeloop next
 → advance --to REVIEWING
 → forgeloop next
@@ -287,10 +292,15 @@ Before implementation, write the canonical contract, persist the route, create
 required gate artifacts under `.forgeloop/gates/`, and require `preflight` to
 return `READY`. `advance` enforces legal phase transitions; it never runs the
 project's commands. After implementation, advance to `VERIFYING`, use
-`prepare-completion` to create a safe receipt skeleton, and use `record-check`
-to serialize results that the agent has already observed. `record-check` never
-executes the supplied command text. Advance to `REVIEWING` before running
-`audit` and `complete`.
+`prepare-completion` to create a safe receipt skeleton, use `run-check` for
+commands, and use `record-check` for manual or non-command observations.
+`run-check` accepts the exact argv after `--`, classifies resolution before
+launch, blocks install-capable resolution without trusted host authority, and
+writes `.forgeloop/executions/<executionId>.json` before recording the check.
+`record-check` never executes `--command`; that option is metadata only. A
+command check with `OBSERVED` evidence must reference a ForgeLoop execution
+artifact with `provenance: FORGELOOP_EXECUTED`. Advance to `REVIEWING` before
+running `audit` and `complete`.
 `audit` is a read-only consistency check. `complete` validates the final
 contract, route, gates, phase ledger, structured evidence, coverage, receipt,
 and freshness before it can return `VALID`. `report` renders the same result as
@@ -377,6 +387,7 @@ target project. Its main threat boundaries are:
 | Installation authority provenance | Standalone CLI uses `trustMode: NONE`: environment-selected `FORGELOOP_AUTHORITY_FILE`/`FORGELOOP_AUTHORITY_DIR` sources are untrusted candidates; only an internal `HOST_ATTESTED` context may select a trusted source outside the actor-writable target. Project-local authority claims remain untrusted. |
 | Stale replay | Work state records contract and repository fingerprints; drift requires revalidation and never reruns destructive or publication actions automatically. |
 | Unverified publication | Receipts carry explicit publication booleans; local success never implies a push, pull request, merge, release, or deployment. |
+| Unattested observed command | `record-check --command` is metadata only; command `OBSERVED` evidence requires a bound ForgeLoop execution artifact. `run-check` preserves exact argv, target cwd, resolution mode, timestamps, and exit status, and rejects install-capable resolution before launch without trusted host authority. |
 
 The full boundary inventory, residual limitations, and executable evidence are
 in [`THREAT_MODEL.md`](./THREAT_MODEL.md).
@@ -649,7 +660,7 @@ adoption. Local rendering requires Node.js 22+ and FFmpeg.
 The source repository keeps canonical documents at the root for package
 development and validation. A bootstrapped target uses the hidden-kit layout
 shown above; mutable contract, route, state, gate, event, preflight, and
-receipt artifacts remain directly under `.forgeloop/`.
+receipt and execution artifacts remain directly under `.forgeloop/`.
 
 ## Maintenance
 

package/THREAT_MODEL.md

@@ -20,6 +20,7 @@ remaining trust boundaries and their executable evidence.
 | Lifecycle artifact repair | Direct state or receipt edits fabricate a legal recovery or terminal phase | Work state, receipt, evidence checks, and event ledger | New verification cycles record phase events and fingerprints; validators reject state/ledger divergence and future lifecycle evidence | Local artifacts are detection-oriented, not cryptographically tamper-proof against a privileged process rewriting every linked artifact | `tests/lifecycle-evidence-recovery.test.js`, `tests/completion-ergonomics.test.js` |
 | Unsupported profile fact | Turns an agent decision into a durable user fact | `PROJECT_PROFILE.md` and `.forgeloop/sources.json` | Source IDs, source-kind validation, unknown-reference rejection, and explicit misclassification failures | Arbitrary Markdown semantics still require a human or host-specific parser | `tests/profile-provenance.test.js`, `src/core/profile.js` |
 | Weak verification | Treats a vague or inferred claim as observed evidence | Receipt checks and coverage | Versioned check schema, contradictory-status rejection, observed-evidence requirements, and coverage matrix | Evidence remains local and declarative; it is not a remote attestation service | `tests/evidence-coverage.test.js`, `tests/completion.test.js` |
+| Unattested observed command | An actor supplies `--command "..."` or forged command metadata and makes an unrun process appear to be observed evidence | Check provenance, execution artifact, and process boundary | `run-check` captures exact argv, cwd, resolution, timestamps, exit status, and task/check binding; it classifies before launch, uses `shell: false`, and rejects install-capable resolution without trusted authority. `record-check --command` is metadata only; command `OBSERVED` checks require `FORGELOOP_EXECUTED` plus a valid `executionRef`; completion, audit, protocol validation, and bundles revalidate it | The local execution artifact is not cryptographic remote attestation, and a separately privileged process can alter the target after execution | `tests/run-check.test.js`, `tests/completion-cli.test.js`, `tests/verification-capability.test.js`, `tests/validate-protocol-cli.test.js` |
 | Malicious receipt | Turns local claims into false publication or completion claims | Execution receipt JSON | Semantic evidence checks for completion, checks, review, push, commit, and deployment; explicit publication booleans | Evidence text is declarative and must still be reviewed for provenance | `tests/receipt-semantics.test.js`, `tests/observability.test.js` |
 | Malicious task brief | Grants a child task more authority than intended | Delegation brief JSON and host harness | Relative path boundaries, guide/verification/authority checks, secret-free validation, set validation, parent integration ownership | The host harness remains responsible for OS permissions and execution policy | `tests/delegation.test.js`, `tests/delegation-set.test.js` |
 | Artifact content exposure | Sensitive material enters portable artifacts or diagnostics | State, receipt, delegation, evidence, and repository text | Nested key/value detection, shaped marker patterns, scanner coverage, no content echo in errors | Content scanners cannot prove that an unknown encoding is harmless | `tests/security-limits.test.js`, `tests/test_scan_secrets.py`, `scripts/scan_secrets.py` |
@@ -39,6 +40,10 @@ remaining trust boundaries and their executable evidence.
 | Forged local authority artifact | The active actor creates `.forgeloop/authorities/auth-modlens.json`, claims `source=operator`, and uses the reference to authorize its own installation-capable check | Host/operator authority source versus actor-writable project state | Resolve grants only from an explicit `HOST_ATTESTED` runtime context with an external source outside the target; reject project-local grants with `E_AUTHORITY_UNTRUSTED_SOURCE`; revalidate in `record-check`/`audit`/`complete` | If the host exposes the attested source as writable to the actor, ForgeLoop cannot distinguish genuine grants from actor fabrication without a stronger trust anchor | Local fake rejection, host-attested external acceptance, inside-target rejection, post-record removal and revocation tests |
 | Environment-injected trust root | The active actor creates an authority file outside the project target and sets `FORGELOOP_AUTHORITY_FILE` or `FORGELOOP_AUTHORITY_DIR` when invoking ForgeLoop | Actor-controlled process environment versus host-attested runtime authority | Standalone CLI uses `trustMode: NONE`; environment-selected sources are metadata/candidates only and fail with `E_AUTHORITY_UNTRUSTED_SOURCE`; trusted authority requires an internal `HOST_ATTESTED` context not exposed as a self-assertable CLI option | If the host integration allows the actor to mutate or replace the attested source/context, the host trust boundary is compromised | Environment-injection rejection, standalone audit/complete rejection, host-attested positive path |
 | Stale receipt recovery dead-end | Work state changes after preparing a receipt, leaving a mismatch that cannot be refreshed because the old receipt is rejected during re-preparation | Preparation lifecycle and recovery action resolution | Recoverable stale receipt binding in `prepareCompletion`, executable `PREPARE_COMPLETION` return from `next`, atomic refresh of stateFingerprint and changedPaths | Manual file corruption outside CLI commands requires manual diagnostic recovery | `tests/stale-receipt-recovery.test.js`, `tests/next-executability.test.js` |
+| Recursive npm script dispatch | A recognized npm lifecycle script invokes another npm script, which later invokes an installation-capable resolver (e.g. `test` -> `npm run visual` -> `npx package`) | Recognized npm dispatcher semantics before ForgeLoop process launch | Recursive npm-script resolution with cycle detection, maximum depth (16), lifecycle hook inspection, restart special semantics, and fail-closed behavior when the resolver cannot prove the chain is non-installing | Opaque executables may spawn arbitrary descendants. Full descendant-process attestation requires host-level process controls and is outside this release | `tests/run-check.test.js`, `tests/verification-capability.test.js` |
+| npm invocation rewriting and workspace dispatch | npm configuration flags appear before the subcommand, or npm workspace selectors cause script execution to occur against a package.json different from the ForgeLoop target root | Raw npm argv versus effective npm command and execution context | Canonical npm invocation parsing, effective subcommand extraction, workspace flag detection across the full npm argv, and fail-closed workspace script handling when the selected package.json cannot be proven from the current target | ForgeLoop 0.1.15 intentionally does not implement full npm workspace resolution. Users should execute run-check from the selected workspace target directory | `tests/run-check.test.js`, `tests/verification-capability.test.js` |
+| Unclassified npm Install-Capable Command | The npm security classifier recognizes only a small denylist of package-mutating commands. Another official npm command or alias with install/update/bootstrap semantics falls through as a local package command | Effective npm command semantics versus ForgeLoop's command classifier | Semantic npm command classification with explicit install-capable families, explicit script-dispatch families, a deliberately small non-installing allowlist, and fail-closed behavior for unknown or ambiguous npm commands | Future npm commands are blocked until ForgeLoop explicitly classifies them | `tests/verification-capability.test.js`, `tests/run-check.test.js` |
+| npm Option Value Ambiguity | An unknown npm config option with a separate value appears before the effective subcommand, and a parser misinterprets the option value as the npm subcommand | Raw npm argv and unsupported config syntax | Recognize self-contained `--key=value`, explicitly supported options-with-value, and known boolean options. Unknown long option followed by a non-option token fails closed with `NPM_OPTION_VALUE_AMBIGUOUS` | Unsupported npm config grammar is intentionally rejected rather than guessed | `tests/verification-capability.test.js`, `tests/run-check.test.js` |
 
 ## Boundary rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",

package/schemas/check.schema.json

@@ -13,6 +13,8 @@
     "status": { "enum": ["passed", "failed", "blocked", "not-run"] },
     "evidenceKind": { "enum": ["OBSERVED", "INFERRED", "NOT_VERIFIED", "BLOCKED"] },
     "source": { "type": "string", "minLength": 1 },
+    "executionRef": { "type": "string", "minLength": 1 },
+    "provenance": { "enum": ["FORGELOOP_EXECUTED", "ACTOR_REPORTED", "MANUAL_OBSERVATION"] },
     "exitCode": { "type": "integer" },
     "timestamp": { "type": "string", "minLength": 1 },
     "repositoryFingerprint": { "type": "string", "pattern": "^[a-f0-9]{40}$" },

package/schemas/execution.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/execution.schema.json",
+  "title": "ForgeLoop command execution artifact",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "protocolVersion",
+    "executionId",
+    "taskId",
+    "checkId",
+    "requirement",
+    "verificationCycle",
+    "kind",
+    "argv",
+    "cwd",
+    "resolution",
+    "startedAt",
+    "finishedAt",
+    "status",
+    "exitCode"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "executionId": { "type": "string", "minLength": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "checkId": { "type": "string", "minLength": 1 },
+    "requirement": { "type": "string", "minLength": 1 },
+    "verificationCycle": { "type": "integer", "minimum": 1 },
+    "kind": { "const": "COMMAND_EXECUTION" },
+    "argv": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "cwd": { "type": "string", "minLength": 1 },
+    "resolution": {
+      "type": "object",
+      "required": ["resolutionMode", "mayInstall", "installer", "tool"],
+      "properties": {
+        "resolutionMode": { "type": "string", "minLength": 1 },
+        "mayInstall": { "type": "boolean" },
+        "installer": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+        "tool": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] }
+      },
+      "additionalProperties": false
+    },
+    "dispatch": {
+      "type": "object",
+      "properties": {
+        "kind": { "type": "string", "minLength": 1 },
+        "scriptName": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "startedAt": { "type": "string", "minLength": 1 },
+    "finishedAt": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["passed", "failed"] },
+    "exitCode": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] }
+  },
+  "additionalProperties": false
+}

package/src/cli.js

@@ -24,6 +24,7 @@ import { formatPolicyResult, runPolicy } from "./commands/policy.js";
 import { formatBundleResult, runBundle } from "./commands/bundle.js";
 import { formatPrepareCompletionResult, runPrepareCompletion } from "./commands/prepare-completion.js";
 import { formatRecordCheckResult, runRecordCheck } from "./commands/record-check.js";
+import { formatRunCheckResult, runCheck } from "./commands/run-check.js";
 import { formatRecordTerminalResult, runRecordTerminalResult } from "./commands/record-terminal-result.js";
 import { formatNextActionResult, runNext } from "./commands/next.js";
 import { resolveTarget } from "./core/filesystem.js";
@@ -31,7 +32,7 @@ import { getPackageRoot } from "./core/templates.js";
 import { ARTIFACT_PATHS } from "./core/artifacts.js";
 
 function usage(command = null) {
-  const commands = "init|doctor|update|activate|route|preflight|advance|next|prepare-completion|record-check|record-terminal-result|complete|audit|report|policy|bundle|inspect|status|validate-state|clear-state|validate-receipt|validate-protocol";
+  const commands = "init|doctor|update|activate|route|preflight|advance|next|prepare-completion|run-check|record-check|record-terminal-result|complete|audit|report|policy|bundle|inspect|status|validate-state|clear-state|validate-receipt|validate-protocol";
   const options = ["  --path <directory>  target project directory (default: current directory)"];
   if (!command || command === "init" || command === "update") {
     options.push("  --dry-run           show planned writes without changing files");
@@ -53,7 +54,7 @@ function usage(command = null) {
   if (!command || command === "advance") {
     options.push("  --to <phase>        destination workflow phase");
   }
-  if (!command || ["activate", "advance", "next", "prepare-completion", "record-check", "record-terminal-result", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(command)) {
+  if (!command || ["activate", "advance", "next", "prepare-completion", "run-check", "record-check", "record-terminal-result", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(command)) {
     options.push("  --json              emit structured output as JSON");
   }
   if (!command || ["preflight", "complete", "audit", "report"].includes(command)) {
@@ -78,16 +79,23 @@ function usage(command = null) {
   if (!command || command === "validate-receipt") {
     options.push("  --file <path>       receipt file relative to target");
   }
-  if (!command || command === "record-check") {
+  if (!command || command === "record-check" || command === "run-check") {
     options.push("  --id <id>            stable check identifier");
-    options.push("  --kind <kind>        check kind (default: command)");
     options.push("  --requirement <id>   completion requirement covered by the check");
+    options.push("  --details <json>     additional structured check details");
+  }
+  if (!command || command === "record-check") {
+    options.push("  --kind <kind>        check kind (default: command; use manual-review for manual evidence)");
     options.push("  --status <status>    passed, failed, blocked, or not-run");
     options.push("  --evidence-kind <kind> OBSERVED, INFERRED, NOT_VERIFIED, or BLOCKED");
-    options.push("  --command <text>     command already run by the agent (recorded only)");
-    options.push("  --result <text>      observed result supplied by the agent");
+    options.push("  --command <text>     recorded only as metadata; it is never executed");
+    options.push("  --result <text>      observed result supplied by the actor");
     options.push("  --exit-code <number> observed process exit code");
-    options.push("  --details <json>     additional structured check details");
+    options.push("  --execution-ref <id> ForgeLoop execution artifact reference");
+    options.push("  --provenance <value> FORGELOOP_EXECUTED, ACTOR_REPORTED, or MANUAL_OBSERVATION");
+  }
+  if (!command || command === "run-check") {
+    options.push("  -- <argv>            exact command argv to classify, execute, and attest");
   }
   if (!command || command === "record-terminal-result") {
     options.push("  --requirement <id>   terminal requirement covered by the result");
@@ -133,6 +141,9 @@ export function parseArgs(argv) {
     checkResult: null,
     checkExitCode: null,
     checkDetails: null,
+    checkExecutionRef: null,
+    checkProvenance: null,
+    commandArgv: [],
     checkType: null,
     checkSource: null,
     policy: null,
@@ -144,7 +155,7 @@ export function parseArgs(argv) {
 
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
-    if (["init", "doctor", "update", "activate", "route", "preflight", "advance", "next", "prepare-completion", "record-check", "record-terminal-result", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(argument)) {
+    if (["init", "doctor", "update", "activate", "route", "preflight", "advance", "next", "prepare-completion", "run-check", "record-check", "record-terminal-result", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(argument)) {
       if (command) throw new Error(`Multiple commands are not supported: ${argument}`);
       command = argument;
     } else if (argument === "--help" || argument === "-h") {
@@ -304,6 +315,19 @@ export function parseArgs(argv) {
         throw new Error("--details must be a JSON object");
       }
       index += 1;
+    } else if (argument === "--execution-ref") {
+      const executionRef = argv[index + 1];
+      if (!executionRef || executionRef.startsWith("-")) throw new Error("--execution-ref requires an execution ID");
+      options.checkExecutionRef = executionRef;
+      index += 1;
+    } else if (argument === "--provenance") {
+      const provenance = argv[index + 1];
+      if (!provenance || provenance.startsWith("-")) throw new Error("--provenance requires a provenance value");
+      options.checkProvenance = provenance;
+      index += 1;
+    } else if (argument === "--" && command === "run-check") {
+      options.commandArgv = argv.slice(index + 1);
+      break;
     } else if (argument === "--path") {
       options.path = argv[index + 1];
       if (!options.path || options.path.startsWith("-")) throw new Error("--path requires a directory");
@@ -324,7 +348,7 @@ export function parseArgs(argv) {
 
   if (!command) return { command: null, options };
 
-  const jsonCommands = ["doctor", "route", "activate", "advance", "next", "prepare-completion", "record-check", "record-terminal-result", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"];
+  const jsonCommands = ["doctor", "route", "activate", "advance", "next", "prepare-completion", "run-check", "record-check", "record-terminal-result", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"];
   if (!jsonCommands.includes(command) && options.json) {
     throw new Error(`Option --json is not valid for ${command}`);
   }
@@ -377,8 +401,10 @@ export function parseArgs(argv) {
     options.checkResult,
     options.checkExitCode,
     options.checkDetails,
+    options.checkExecutionRef,
+    options.checkProvenance,
   ];
-  if (command !== "record-check" && checkOptions.some((value) => value !== null)) {
+  if (!["record-check", "run-check"].includes(command) && checkOptions.some((value) => value !== null)) {
     throw new Error(`Check recording options are not valid for ${command}`);
   }
   if (command === "record-check" && !options.help) {
@@ -388,6 +414,17 @@ export function parseArgs(argv) {
     if (!options.checkEvidenceKind) throw new Error("record-check requires --evidence-kind");
     if (!options.checkCommand && !options.checkResult) throw new Error("record-check requires --command or --result");
   }
+  if (command === "run-check" && !options.help) {
+    if (!options.checkId) throw new Error("run-check requires --id");
+    if (!options.checkRequirement) throw new Error("run-check requires --requirement");
+    if (options.checkKind || options.checkStatus || options.checkEvidenceKind || options.checkCommand
+      || options.checkResult || options.checkExitCode !== null || options.checkExecutionRef || options.checkProvenance) {
+      throw new Error("run-check accepts only --id, --requirement, --details, and -- <argv>");
+    }
+    if (!Array.isArray(options.commandArgv) || options.commandArgv.length === 0) {
+      throw new Error("run-check requires -- followed by an exact command argv");
+    }
+  }
   return { command, options };
 }
 
@@ -490,6 +527,19 @@ export async function main(argv = process.argv.slice(2)) {
       return 0;
     }
 
+    if (command === "run-check") {
+      const result = await runCheck({
+        target,
+        packageRoot,
+        id: options.checkId,
+        requirement: options.checkRequirement,
+        argv: options.commandArgv,
+        details: options.checkDetails ?? undefined,
+      });
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatRunCheckResult(result));
+      return result.check.status === "passed" ? 0 : 1;
+    }
+
     if (command === "record-check") {
       const result = await runRecordCheck({
         target,
@@ -501,8 +551,10 @@ export async function main(argv = process.argv.slice(2)) {
         evidenceKind: options.checkEvidenceKind,
         command: options.checkCommand ?? undefined,
         result: options.checkResult ?? undefined,
-        exitCode: options.checkExitCode,
+        ...(options.checkExitCode === null ? {} : { exitCode: options.checkExitCode }),
         details: options.checkDetails ?? undefined,
+        executionRef: options.checkExecutionRef ?? undefined,
+        provenance: options.checkProvenance ?? undefined,
       });
       console.log(options.json ? JSON.stringify(result, null, 2) : formatRecordCheckResult(result));
       return 0;
@@ -606,7 +658,7 @@ export async function main(argv = process.argv.slice(2)) {
     }
     return result.conflicts.length === 0 ? 0 : 1;
   } catch (error) {
-    console.error(`error: ${error.message}`);
+    console.error(`error: ${error.code ? `${error.code}: ` : ""}${error.message}`);
     return 1;
   }
 }

package/src/commands/run-check.js

@@ -0,0 +1,83 @@
+import {
+  assertRecordCheckPrerequisites,
+  recordCheck as recordCheckArtifact,
+} from "../core/completion-artifacts.js";
+import { runCommandExecution } from "../core/execution.js";
+
+export async function runCheck({
+  target,
+  packageRoot,
+  id,
+  requirement,
+  argv,
+  details,
+  authorityContext,
+  runtimeContext,
+}) {
+  if (typeof id !== "string" || id.trim() === "" || typeof requirement !== "string" || requirement.trim() === "") {
+    const error = new Error("run-check requires non-empty id and requirement");
+    error.code = "E_CHECK_INVALID";
+    throw error;
+  }
+  const ready = await assertRecordCheckPrerequisites({
+    target,
+    packageRoot,
+    requirement,
+    status: "passed",
+    evidenceKind: "OBSERVED",
+    authorityContext,
+    runtimeContext,
+  });
+  const verificationCycle = ready.state.verificationCycle ?? 1;
+  const execution = await runCommandExecution({
+    target,
+    packageRoot,
+    taskId: ready.contract.value.taskId,
+    checkId: id,
+    requirement,
+    verificationCycle,
+    argv,
+    details,
+    authorityContext,
+    runtimeContext,
+  });
+  const status = execution.execution.status === "passed" ? "passed" : "failed";
+  const recorded = await recordCheckArtifact({
+    target,
+    packageRoot,
+    id,
+    kind: "command",
+    requirement,
+    status,
+    evidenceKind: "OBSERVED",
+    command: execution.execution.argv.join(" "),
+    result: execution.result,
+    ...(execution.execution.exitCode === null ? {} : { exitCode: execution.execution.exitCode }),
+    details,
+    executionRef: execution.execution.executionId,
+    provenance: "FORGELOOP_EXECUTED",
+    authorityContext,
+    runtimeContext,
+  });
+  return {
+    ...recorded,
+    execution: execution.execution,
+    executionPath: execution.path,
+  };
+}
+
+export function formatRunCheckResult(result) {
+  return [
+    "FORGELOOP CHECK EXECUTED",
+    `id: ${result.check.id}`,
+    `requirement: ${result.check.requirement}`,
+    `status: ${result.check.status}`,
+    `execution: ${result.execution.executionId}`,
+    `argv: ${result.execution.argv.join(" ")}`,
+    `exit code: ${result.execution.exitCode ?? "not-started"}`,
+    `artifact: ${result.executionPath}`,
+    `coverage: ${result.coverage.find((item) => item.requirement === result.check.requirement)?.status ?? "NOT_VERIFIED"}`,
+    `receipt: ${result.path}`,
+    "",
+  ].join("\n");
+}

package/src/commands/validate-protocol.js

@@ -9,6 +9,7 @@ import { validateTaskBrief, validateDelegatedResult } from "../core/delegation.j
 import { ARTIFACT_PATHS, readJsonArtifact } from "../core/artifacts.js";
 import { evaluatePreflight, validateReadyProtocolConsistency } from "../core/preflight.js";
 import { validateEventLedger, validateStateLedgerCoherence } from "../core/events.js";
+import { validateChecksExecutionProvenance } from "../core/completion-artifacts.js";
 
 async function readArtifact(target, relativePath, label) {
   if (!relativePath) return null;
@@ -87,6 +88,23 @@ export async function runValidateProtocol({
   await validateLoaded(loaded.find((item) => item.label === "route"), "routing-result", async (value) => assertRouteInvariants(value));
   await validateLoaded(loaded.find((item) => item.label === "state"), "work-state", async (value) => assertWorkStateSemantics(value));
   await validateLoaded(loaded.find((item) => item.label === "receipt"), "execution-receipt", async (value) => validateReceipt(value, packageRoot));
+  for (const [value, artifactPath] of [
+    [state, stateFile],
+    [receipt, receiptFile],
+  ]) {
+    if (!value) continue;
+    const provenanceErrors = await validateChecksExecutionProvenance(value.checks, {
+      target,
+      packageRoot,
+      taskId: value.taskId,
+      artifactPath,
+    });
+    schemaErrors.push(...provenanceErrors.map((error) => ({
+      ...error,
+      message: `Command provenance validation failed: ${error.message}`,
+      artifacts: [artifactPath, ...(error.artifacts ?? [])],
+    })));
+  }
   for (const item of loaded.filter((candidate) => candidate.label.startsWith("task brief:"))) {
     await validateLoaded(item, "task-brief", async (value) => validateTaskBrief(value, packageRoot));
   }

package/src/core/artifacts.js

@@ -17,8 +17,16 @@ export const ARTIFACT_PATHS = Object.freeze({
   gates: ".forgeloop/gates",
   state: ".forgeloop/work-state.json",
   receipt: ".forgeloop/execution-receipt.json",
+  executionDirectory: ".forgeloop/executions",
 });
 
+export function executionArtifactPath(executionId) {
+  if (typeof executionId !== "string" || !/^exec-[A-Za-z0-9_-]+$/.test(executionId)) {
+    throw new ArtifactError("E_EXECUTION_REF_INVALID", "Execution reference must be a simple execution ID");
+  }
+  return `${ARTIFACT_PATHS.executionDirectory}/${executionId}.json`;
+}
+
 export class ArtifactError extends Error {
   constructor(code, message, artifacts = []) {
     super(message);