Add 0.7.x verifier enforcement implementation plan

docs/0.7-verifier-enforcement-plan.md sequences the reference and hosted verifier
enforcement of the bounded-execution findings that 0.7.0 defines but does not yet
emit. Scoped by the adversarial pass's decidability limits: block only the
decidable named-local-script case; treat the ambiguous middle (make targets, -m
modules, npm run) as documented under-enforcement; exec-sha256 unverified in
local mode and verified via the github.com repository-file channel in hosted mode.
Roadmap and finding-ids point to it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: snapsynapse

docs/0.7-verifier-enforcement-plan.md

@@ -0,0 +1,224 @@
+# 0.7.x Verifier Enforcement Implementation Plan (bounded execution)
+
+Status: committed implementation plan. The bounded-execution rule is normative in
+`spec.md` section 12 as of 0.7.0; the reference and hosted verifiers do not yet
+emit its findings. This plan sequences that enforcement. Until it lands, the
+`action.exec-unbounded`, `action.exec-opaque`, `exec-sha256.mismatch`,
+`exec-sha256.transitive-unpinned`, and `exec-sha256.unverified` ids are defined
+but not emitted, and bounded-execution compliance is self-asserted.
+
+This plan is non-normative. It does not change the conformance contract; it
+describes how to make the reference verifier check what the 0.7.0 spec already
+requires.
+
+## Goal
+
+Emit the five bounded-execution findings from the reference verifier
+(`scripts/guidecheck_verify.py`) and the hosted verifier (`api/verify.py`,
+`scripts/guidecheck_hosted_anchors.py`), scoped by the decidability limits the
+adversarial pass established, so that a guide invoking an unbounded in-repo script
+fails Level 3 while honest guides and exempt dependency installers stay
+conformant.
+
+## Design constraints carried from the adversarial pass
+
+These are the corrections that shaped the 0.7.0 spec text and must shape the
+implementation. They are recorded in `threat-register.md` under
+"Runtime-indirection and transitive execution".
+
+1. Classify by invocation shape, not program head. `make`, `npm`, `pip`, `cargo`,
+   and `go` stay in `_PACKAGE_TOOLS` for class detection (they are correctly
+   `code-executing`), but the exempt-versus-bound decision is separate and keys on
+   the subcommand and argv shape. `npm install` is exempt; `npm run <script>` is
+   bound.
+2. Block only the decidable case. Reserve blocking `action.exec-unbounded` for a
+   named local script file invoked without a pin: a path-qualified executable
+   (`./x`, `../x`, `/abs/x`) or an interpreter with a local script-file argument
+   (`bash scripts/setup.sh`, `sh ./install`). These are already detected as
+   `code-executing` by `_segment_runs_code` as of the 0.6.x detection work.
+3. Do not block the undecidable middle. `make <target>`, `npm run <script>`,
+   `pip install .`, `python -m <module>`, and `cargo`/`go build` with an in-repo
+   build hook are bound per the spec, but the verifier cannot statically tell a
+   first-party module or a malicious recipe from a benign one. Per spec section 19
+   (best-effort, allowlist-bounded), the verifier emits an informational finding
+   for these rather than a false-positive block. This is a deliberate, documented
+   under-enforcement: the verifier is weaker than the spec on the ambiguous middle,
+   and human review remains required.
+4. The inline carve-out is absolute. An action whose executed instructions are in
+   the `command` field (an inline `-c`/`-e`/`-E`/`--eval`/`--exec` program, or a
+   bare-program interpreter such as `awk`/`perl`) is bounded by definition and is
+   never flagged. The tokenizer is quote-naive, so the trigger is the presence of
+   an external artifact reference, never content inspection of an inline program.
+5. `exec-opaque` is a control only for the exempt class. On an exempt installer it
+   is `action.exec-opaque` (warning) and fully conformant. On a bound artifact it
+   is `action.exec-unbounded` (blocking): a bound artifact is always inlinable or
+   pinnable, so opaque there is a bypass.
+6. A pin is worth nothing unverified. `exec-sha256` can only be verified where the
+   verifier can read the artifact. Local-file mode cannot fetch, so it always
+   reports `exec-sha256.unverified` (info) and renders the pin as declared, not
+   satisfied. Hosted mode reads the artifact through the github.com repository-file
+   channel and recomputes.
+
+## Building blocks already in place
+
+Landed under the 0.6.x line (commits on `main`):
+
+- `_segment_runs_code` recognizes path-qualified executables, script-extension
+  program names, interpreters with a path-qualified positional, and container
+  `build`/`run`/`exec`/`start` (and `compose up|run|build`).
+- `_NET_TOOLS` includes DNS clients and `/dev/tcp`; `command.fetch-execute` fires
+  on `dig TXT | bash` as on `curl | sh`.
+- `_command_head`, `_invoked_path_token`, `_is_path_arg`, `_container_runs_code`,
+  `_command_segments`, `_PACKAGE_TOOLS`, `_INTERPRETERS`, `_CODE_FLAGS`,
+  `_SCRIPT_EXTENSION`.
+- False-positive guards proven: `docker ps`, `docker version`, `sed`, `jq`,
+  `hostname`, `.venv/bin/python`, `python3 --version`, `git clone`.
+
+## Work items
+
+### Phase 1: bound-versus-exempt classifier
+
+Add `classify_exec_target(command) -> str` returning one of `inline`,
+`bound-script`, `exempt-installer`, `ambiguous`, `none`:
+
+- `inline`: any segment head is an interpreter with an inline-code flag
+  (`_CODE_FLAGS`) or a bare-program interpreter. Bounded; no finding.
+- `bound-script`: a path-qualified executable, or an interpreter whose positional
+  argument is a local script file (matches `_SCRIPT_EXTENSION` or `_is_path_arg`).
+  Decidable; subject to the pin-or-inline requirement.
+- `exempt-installer`: head plus subcommand in a new `_DEPENDENCY_INSTALLERS`
+  set (`npm ci`, `npm install` with no `run`, `pnpm install`, `yarn install`,
+  `pip install -r`, `pip install <named-non-local>`, `bundle install`,
+  `cargo build` with no `build.rs`, `go build` with no invoked `go generate`), plus
+  committed bootstrap wrappers whose basename is `gradlew`, `mvnw`, `configure`, or
+  `autogen.sh`.
+- `ambiguous`: `make <target>`, `npm run <script>`, `just <recipe>`,
+  `pip install .`/`-e .`, `python -m <module>`, `go generate`, `docker build`,
+  and `cargo`/`go build` when an in-repo build hook is present. Not blocked.
+- `none`: not code-executing.
+
+Publish `_DEPENDENCY_INSTALLERS` as the spec-level exempt table in
+`verifier-conformance.md` so independent verifiers agree, rather than leaving it a
+private constant.
+
+### Phase 2: field parsing
+
+Extend the action-block parser to read `exec-sha256` and `exec-opaque`:
+
+- `exec-sha256`: must be 64 lowercase hex characters, else a malformed-field
+  finding (reuse `action-block.malformed`).
+- `exec-opaque`: value must be `acknowledged`; require a `notes` rationale on the
+  same action; else a malformed-field finding.
+
+### Phase 3: local emission
+
+In `check_actions`/`check_command`, for each code-executing action:
+
+- `bound-script` with no `exec-sha256` and no `exec-opaque` -> `action.exec-unbounded`
+  (error).
+- `exec-opaque` on a `bound-script` -> `action.exec-unbounded` (error).
+- `exec-opaque` on an `exempt-installer` -> `action.exec-opaque` (warning).
+- `exec-sha256` present -> `exec-sha256.unverified` (info) in local-file mode, and
+  suppress `action.exec-unbounded` (the pin is declared).
+- `ambiguous` -> at most an info finding; never blocking.
+- `inline`, `exempt-installer` with no opaque, `none` -> no bounded-execution
+  finding.
+
+Inlining (spec option a) needs no detection: a guide satisfies it by replacing the
+artifact invocation with inline action blocks, so there is simply no bound-script
+action to flag. An action that both inlines a copy and re-invokes the artifact
+still has the bound-script invocation and is flagged, which is the intended guard.
+
+Remove the "not yet emitted" note from the `finding-ids.md` "Bounded execution"
+section and the `verifier-conformance.md` section 19 addition for the ids the
+local verifier now emits (`action.exec-unbounded`, `action.exec-opaque`,
+`exec-sha256.unverified`).
+
+### Phase 4: hosted exec-sha256 verification
+
+In the hosted path, when an action declares `exec-sha256` and the artifact is
+reachable through the github.com repository-file channel
+(`scripts/guidecheck_hosted_anchors.py`):
+
+- recompute the artifact SHA-256; on divergence emit `exec-sha256.mismatch`
+  (error).
+- byte-scan the fetched artifact for further in-repo invocations (`source`/`.`,
+  `bash x.sh`, an interpreter with a script argument, `make`, `npm run`); require
+  each to be inlined or pinned, else `exec-sha256.transitive-unpinned` (error).
+- account for the added fetches against the hosted per-request fetch budget
+  (currently seven in `api/verify.py`); cap artifact reads per request and prefer
+  deduplication. Decide whether to raise the budget or bound the number of pinned
+  artifacts verified per request.
+
+Local-file mode never reaches this phase; it always reports
+`exec-sha256.unverified`.
+
+### Phase 5: corpus and example ripple
+
+- Example guides that invoke a named local script become `action.exec-unbounded`.
+  `examples/` currently has `.venv/bin/python prompter_kit.py ...` in the
+  PrompterKit example; add `exec-sha256` pins (or restructure to inline) and
+  regenerate the affected fixtures. Confirm no other tracked guide invokes a named
+  local script (the self-guide uses `python -m venv` and `sed`/`jq`, which are not
+  bound-script shapes).
+- Add fixtures: valid (a pinned leaf artifact, `exec-opaque` on an exempt
+  installer), invalid (`action.exec-unbounded` for `bash scripts/setup.sh` and
+  `./scripts/setup.sh`, `exec-opaque` on a bound artifact, and in hosted-replay
+  form `exec-sha256.mismatch` and `exec-sha256.transitive-unpinned`).
+- Generate each `expected.json` from real verifier output, as the DNS and
+  local-script fixtures were built.
+
+### Phase 6: Change 3 (separate decision)
+
+Promoting the unambiguous class-understatement warnings
+(`action-block.class.code-executing-missing`, `network.command-implies-networked`)
+from warning to blocking at Level 3 and above is a separable conformance change
+with a large corpus ripple (every under-declaration fixture and any adopter guide
+that understates a class). Decide it on its own, with its own fixture pass; it is
+not a prerequisite for Phases 1 through 5, because `action.exec-unbounded` keys off
+detected code execution, not the declared class.
+
+## Decidability policy, stated plainly
+
+- Block: a named local script file invoked without a pin; `exec-opaque` on a bound
+  artifact.
+- Warn: `exec-opaque` on an exempt installer.
+- Info: `exec-sha256.unverified`; the ambiguous middle.
+- Never flag: inline programs; exempt installers.
+
+The verifier under-enforces the spec on the ambiguous middle by design. A guide
+that hides a payload in a `make` recipe or a first-party `-m` module is
+non-conformant under section 12 but is not mechanically blocked, because the
+verifier cannot decide that shape without executing or fully reading the project.
+This is the section 19 best-effort posture, and it is why conformance is not
+safety and human review remains required.
+
+## Risks
+
+- Ambiguous-middle under-enforcement (verifier weaker than the spec). Documented
+  above and in `threat-register.md`; not a silent gap.
+- Example ripple and notional pins in fixtures (pins the local verifier reports as
+  unverified anyway).
+- Hosted fetch budget pressure from artifact reads.
+- Quote-naive tokenizer: never content-inspect an inline program to decide the
+  carve-out.
+
+## Test strategy
+
+- Unit tests in `scripts/test_parser_edge_cases.py` for `classify_exec_target`
+  across every shape in Phase 1 plus the false-positive guards.
+- One fixture per emitted finding, `expected.json` generated from real output.
+- `make test` green: `eval`, `verify-fixtures`, `validate-contracts`,
+  `check-guide-artifacts`, and the finding-id contract check
+  (`check_reference_verifier.py`) which requires every emitted id to be documented
+  in `finding-ids.md`.
+
+## Suggested release sequencing
+
+- 0.7.1: Phases 1 through 3 and 5 (local enforcement: blocking
+  `action.exec-unbounded` for named scripts, `exec-opaque` handling,
+  `exec-sha256.unverified`, fixtures, example pins). Drop the "not yet emitted"
+  caveat for the locally emitted ids.
+- 0.7.2: Phase 4 (hosted `exec-sha256` verification and transitive-closure
+  scanning).
+- Change 3: separate decision, separate release.

finding-ids.md

@@ -120,9 +120,9 @@ files.
 
 Defined for guide-profile 0.7.0 (spec section 12, "Code-executing actions and
 the review boundary"). Reference-verifier and hosted-verifier support arrives in
-a subsequent 0.7.x release; until then these ids are part of the contract but are
-not yet emitted, and a guide's compliance with the bounded-execution rule is
-self-asserted.
+a subsequent 0.7.x release, sequenced in `docs/0.7-verifier-enforcement-plan.md`;
+until then these ids are part of the contract but are not yet emitted, and a
+guide's compliance with the bounded-execution rule is self-asserted.
 
 | ID | Severity | Trigger |
 |---|---|---|

roadmap.md

@@ -138,7 +138,8 @@ five finding ids in `finding-ids.md` and `verifier-conformance.md`. The profile
 bumped to 0.7.0 across all surfaces. Reference-verifier and hosted-verifier
 enforcement of `action.exec-unbounded`, `exec-sha256` verification, and
 transitive-closure scanning is the remaining work and is deferred to a 0.7.x
-release; until then bounded-execution compliance is self-asserted. Tagging v0.7.0,
+release, sequenced in `docs/0.7-verifier-enforcement-plan.md`; until then
+bounded-execution compliance is self-asserted. Tagging v0.7.0,
 republishing the self-guide DNS TXT hash, and deploying the site are out-of-band
 release steps. The bound-versus-exempt axis and the adversarial hardening behind
 it are summarized in the covered/landed/candidate notes in this section and in