yam-flow 2.6.0 → 2.8.0

package/AGENTS.md

@@ -21,6 +21,7 @@
 19. Treat security as the first project lens: identify sensitive surfaces early and guide safer defaults before convenience.
 20. Keep final reports short and concrete, but always include remaining tasks or state that none are meaningful.
 21. When relevant, include architecture hygiene in the Study Note: avoid dumping unrelated logic into `page.tsx`, one-off component CSS into `global.css`, or structured product data into broad DB `jsonb` blobs when existing project boundaries, scoped styles, typed tables, constraints, or indexes fit better.
+22. When an artifact changed, put `Next step` immediately after Study Note. Build it from a quick whole-process scan with current situation, forward outlook, a concrete critical opinion, improvement recommendations, and ordered fix-first then planned actions with evidence and ownership; do not merely rename remaining tasks.
 
 ## Latest Update Trigger
 

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to yam-flow are documented here.
 
+## v2.8.0 - 2026-09-01
+
+### Added
+
+- Added `yam.next-step.v1` plus CLI create/verify commands and Loop integration. Changed-artifact reports now require an evidence-bound whole-process scan, critical opinion, recommendations, and ordered fix-first/planned work immediately after Study Note.
+- Added pure `yam install --dry-run --json` plans with ownership-aware operations, explicit replacement previews, deterministic plan digests, and no mutation authorization.
+- Added immutable `yam.scout-receipt.v1` source/claim baselines with canonical entity aliases, four freshness clocks, acquisition-failure taxonomy, claim links, local integrity verification, and explicit operator-supplied truth boundaries.
+- Added clean-source and strict signed-release ref gates plus exact-tarball Linux/macOS/Windows lifecycle workflows and explicit manual-dispatch npm OIDC/provenance publishing.
+
+### Improved
+
+- Aligned release readiness with npm Trusted Publisher OIDC: local `npm whoami` no longer blocks the selected OIDC path, while missing workflow controls and unverified npmjs account binding fail closed with path-specific guidance.
+- Strengthened Scout guidance with canonical entity resolution, registry/release/main/latest-commit comparison, stable/RC/unreleased classification, opposition, stop reasons, and delta-scan receipts.
+- Updater checks and component receipts now retain npm integrity/`gitHead`, PyPI release-file SHA-256 values, or the Git-pinned Insane Search manifest commit as applicable. Apply commands pin the official npm registry or isolated PyPI index, and Insane Search requires a clean tracked local manifest whose bytes match Git plus matching pre/post-add marketplace commits and pinned manifest versions.
+- Registry readiness now probes the exact immutable package version, accepts only an explicit E404 as unpublished, fails closed on auth or network errors, and binds downstream release-report parsing to the same package/version identity.
+- Install dry-run plans list unowned legacy, retired, and mirror paths that the real transaction preserves.
+- README, commands, roadmap, project pack, route skills, manifest, package exports, and self-verification now describe and exercise the new contracts.
+
+### Security
+
+- Next step receipts reject unknown fields, contradictory blocker/truth combinations, weak evidence for strong claims, invalid ordering, limit overruns, and digest tampering.
+- Scout receipts reject path escapes, symlinked paths, overwrite attempts, credential-bearing URLs, oversized or non-canonical content, incomplete clocks paired with a known stability, unknown claim sources, and digest drift while never trusting fetched content as instructions. Failed opened writes are preserved for manual inspection instead of using an unsafe pathname cleanup.
+- Release workflows pin third-party actions to reviewed commit SHAs, grant OIDC only to the final no-checkout publish job, and require the publish artifact to match the independently carried SHA-256 receipt.
+
+### Verification
+
+- Focused typecheck/build, Next step, Scout receipt, install-transaction, external-update, packaged CLI, release-ref, and same-tarball lifecycle smokes.
+- Full self-verification, package boundary/secrets, dependency audit/signatures, update/status/Doctor, Mission receipt gate, and bounded Deep false-completion audit are release criteria.
+
+## v2.7.0 - 2026-08-24
+
+### Added
+
+- Added immutable final-scope verification closure receipts that bind declared work to the current Git dirty, staged, and untracked path set, promote release-sensitive changes, and separate selected checks from operator-declared execution evidence.
+- Added optional demand-gated media provider receipts with exact call/execution/dry-run/submit state plus confined, identity-bound local asset provenance.
+
+### Improved
+
+- Skill installation and removal now use no-follow regular-file access where available, verify descriptor and path identity, and revalidate parent-directory identity around read, copy, move, rollback, and mutation boundaries.
+- Verification closure and media receipt reads and immutable writes apply confined path, non-symlink parent, descriptor identity, size, and digest checks; media asset hashing is sequential and bounded.
+
+### Security
+
+- Symlinked install source/destination segments, raced path identities, rollback or cleanup targets whose recorded type/device/inode no longer match, unplanned final Git paths, unavailable Git scope, receipt path escapes, local asset symlinks, and incoherent provider-execution claims fail closed.
+- Node does not expose descriptor-relative `openat` traversal, and arbitrary Windows reparse-point coverage remains unverified; these limits are documented instead of overstated.
+
+### Verification
+
+- Focused install-transaction and phase-adoption smokes cover source/destination race handling, rollback preservation, Git-scope drift, immutable/tampered receipts, bounded media assets, and packaged CLI compatibility.
+- Release checks include typecheck, clean build/self-verification, distribution freshness, package boundary/secrets, registry version availability, and CLI smoke.
+
 ## v2.6.0 - 2026-08-07
 
 ### Added

package/COMMANDS.md

@@ -114,6 +114,24 @@ Next.js에서 이 기능을 구현하는 가장 안전한 방식을 찾아줘.
 코드는 아직 수정하지 마.
 ```
 
+For a repeated scan, resolve the canonical entity first and store a non-overwriting source/claim baseline:
+
+```bash
+yam scout receipt create --root /path/to/project --receipt-path .yam/scout/run.json --spec ./scout-spec.json --json
+yam scout receipt verify --root /path/to/project --receipt-path .yam/scout/run.json --json
+```
+
+The spec records aliases, registry/release/main/latest-commit clocks, source receipts, claim links, acquisition failures, opposition, recommendation, and stop reason. All four clocks are required for a stability other than `unknown`. Verification proves the local structure and digest, not the truth of operator-supplied source interpretation. A failed opened write is preserved for manual inspection because Node cannot prove a race-free pathname cleanup without descriptor-relative unlink support.
+
+## Install Planning
+
+```bash
+yam install --dry-run --json
+yam install --dry-run --replace-user-skill quick --json
+```
+
+Dry-run is a pure plan: it writes no lock, receipt, active skill, replacement, or retired-skill removal. Review `operations`, `preserved_paths`, `blockers`, and `plan_digest`; run ordinary `yam install` separately to authorize mutation.
+
 ## Project Pack
 
 Use the CLI to create and inspect the small project direction file.
@@ -154,7 +172,17 @@ yam update apply --component yam --json
 yam update apply --all --json
 ```
 
-`yam update check` is read-only. Every `apply` needs explicit authorization, uses a concurrent-run lock, records a component receipt, and stops on failed/manual results. `--all` runs yam last. A yam install verifies the effective executable identity before any yam-side install command and repeats that check during rollback. This identity contract currently supports POSIX symlink layouts; Windows npm `.cmd` shims fail closed as unverified. Insane Search is never remove-first and `.codex/plugins/cache` is never edited directly.
+`yam update check` is read-only. Its component result preserves the registry artifact source receipt: npm integrity/`gitHead` for yam, PyPI release-file SHA-256 values for Scrapling, and the Git-pinned manifest commit for Insane Search. Every `apply` needs explicit authorization, pins the official npm registry or isolated PyPI index, uses a concurrent-run lock, records a component receipt, and stops on failed/manual results. `--all` runs yam last. A yam install verifies the effective executable identity before any yam-side install command and repeats that check during rollback. This identity contract currently supports POSIX symlink layouts; Windows npm `.cmd` shims fail closed as unverified. Insane Search requires a clean tracked local manifest whose bytes match Git and matching pre/post-add commits, is never remove-first, and never edits `.codex/plugins/cache` directly.
+
+## Release Supply Chain
+
+```bash
+npm run release:ref:smoke
+npm run release:packed-lifecycle:smoke
+npm run release:supply-chain:smoke
+```
+
+Ordinary CI uses clean-source verification. Publishing is manual-dispatch only and additionally requires an exact signed annotated version tag contained in `origin/main`, reuses one SHA-256-bound tarball across the OS matrix, and publishes those tested bytes with npm OIDC provenance. Before the first release, register the exact `.github/workflows/release.yml` workflow in npm Trusted Publishing; do not add a long-lived npm token as a fallback.
 
 ## Demand-Gated Design Production
 
@@ -174,6 +202,36 @@ yam ueye production phase verify --receipt-path .yam/ueye/design-production/camp
 
 Canvas artifact specs use `{ "id", "role", "file_path" }`; gallery specs include `{ "id", "role", "provenance", "revision_ref", "dimensions", "sha256", "completion_state", "final_path" }`. A revision reference also carries the archive receipt's exact `archived_at`, which must match its Ueye manifest entry. All project paths are relative and confined; Canvas session/render paths and the single revision state are fixed under the session-specific `.yam/ueye/design-production/` directory. Revision init binds that state to the closed `request_changes` Canvas path and digest; record/show/finalize reject alternate state files, and record immediately checks the source Canvas comment plus the current archive-time boundary. Demand is operator-asserted but must be recorded before Canvas creation and match at finalize. Canvas source hashes and exact anchors are rechecked before comment/close/finalize. Every phase round names its source Canvas comment and supplies at least one newly archived Ueye revision created within that round's review window; gallery artifacts bind to the final round. Ueye asset/revision hashes are rechecked, a protected `do_not_replace` asset requires `intent: "preserve"`, and `edit_copy` requires `allowed_for_edit: true`. The phase receipt stores upstream and canonical receipt digests, and `phase verify` re-reads their semantics as well as detecting later byte changes. Overall phase truth remains `partial`, and gallery visual, license, and implementation claims always remain `not_verified`.
 
+## Verification Closure And Media Provider Receipts
+
+These are explicit, immutable artifacts. They do not run verification commands or contact media providers.
+
+Prepare one JSON file per selected/executed/skipped/truncated command record, then repeat the corresponding flag:
+
+```json
+{"id":"typecheck","command":"npm run typecheck","scope":"affected","required":true}
+```
+
+```json
+{"id":"typecheck","command":"npm run typecheck","exit_code":0,"evidence":"exit 0 observed in the final worktree"}
+```
+
+```bash
+yam verification closure create --root /path/to/project --receipt-path .yam/verification/final.json --planned-scope affected --changed-file src/example.ts --selected-spec ./selected.json --executed-spec ./executed.json --json
+yam verification closure verify --root /path/to/project --receipt-path .yam/verification/final.json --json
+```
+
+`create` snapshots the Git top-level dirty, staged, and untracked path set. Every observed path must be declared; unplanned paths, missing declared paths, unavailable Git scope, missing required execution, and release-sensitive paths without a required release-scope check fail closed. `verify` re-reads the current Git path set as well as the receipt digest. A later path-set change returns `current_git_scope_drift`; rerun checks against the final state and create a new receipt path because receipts are non-overwriting. Content-only changes to an already-dirty path do not alter the Git path set, and command results remain operator-asserted `partial` evidence.
+
+Media provider receipts are optional and should be used only after real execution-tracking demand exists. Each asset spec contains `{ "id", "role", "file_path", "provenance": { "kind", "source_ref", "recorded_at" } }`.
+
+```bash
+yam media provider create --root /path/to/project --receipt-path .yam/media/dry-run.json --demand-kind media_generation --demand-evidence "coordinated asset work needs an execution boundary" --provider example --model example-v1 --provider-calls 0 --dry-run --asset-spec ./input-asset.json --json
+yam media provider verify --root /path/to/project --receipt-path .yam/media/dry-run.json --json
+```
+
+A dry run requires zero calls, no execution, and no submit. Explicit execution requires `--provider-execution --submit`, at least one call, and a provider-provenance output asset. Local asset and receipt integrity is verified, but provider execution, visual quality, and implementation correctness are not independently proven.
+
 ## Bounded Promotion
 
 ```bash
@@ -192,8 +250,10 @@ yam tools doctor /path/to/project --json
 yam context pressure /path/to/project --json
 yam cleanup scan /path/to/project --json
 yam detect /path/to/project --json
-yam study-note check /path/to/project --text "Study Note: The hook handler's role is final-report validation. It runs at Codex Stop. Before it only reminded; after it requests one correction pass. Expected behavior is a complete note. Structure insight: decision=block creates a continuation prompt. Verification checked the packaged CLI. Limits: a restarted real task remains to be observed." --json
-yam loop report --route quick --intent "fix release readiness" --stage "inspect:passed:read release report" --evidence "typecheck passed" --evidence-level local --evidence-stamp "sha256:release-report" --touched-file src/bin/yam.ts --read-file README.md --verified-file scripts/cli-smoke.mjs --skipped-check "npm publish skipped by design" --stop-condition "stop after readiness evidence is recorded" --resume-hint "rerun release report after npm auth refresh" --readiness-state blocked --covered-requirement "release report is read-only" --uncovered-requirement "npm auth verified" --blocked-kind auth_blocked --failure-cause auth_token_invalid --safe-retry "retry after npm whoami succeeds" --recovery-hint "refresh npm auth, then rerun readiness checks" --fix-first-item "npm auth must be verified before publish" --remaining-task "rerun release report after auth refresh" --recommended-direction "fix npm auth first, then publish manually" --implementation-note "keep loop report read-only" --why-this-next "auth blocks public release claims" --blocked-by "npm whoami E401" --owner-route deep --owner-scope "release readiness only" --scope-owner deep --side-effect "no publish attempted" --avoidance-note "do not retry publish before npm auth is proven" --issue-code "src/bin/yam.ts release report" --issue-role "summarizes release readiness without publishing" --issue-symptom "npm auth failure needs clearer next action" --changed-code "yam loop report" --changed-role "records loop evidence and learning note" --change-summary "added a read-only loop artifact" --why-important "it helps users learn what changed without overclaiming verification" --learning-note "fix blockers before claiming done" --json
+yam study-note check /path/to/project --report ./completion-report.md --json
+yam next-step report --spec ./next-step-spec.json --json
+yam next-step verify --receipt ./next-step-receipt.json --json
+yam loop report --route quick --intent "fix release readiness" --stage "inspect:passed:read release report" --evidence "typecheck passed" --evidence-level local --evidence-stamp "sha256:release-report" --touched-file src/bin/yam.ts --read-file README.md --verified-file scripts/cli-smoke.mjs --skipped-check "npm publish skipped by design" --stop-condition "stop after readiness evidence is recorded" --resume-hint "rerun release report after npm auth refresh" --readiness-state blocked --covered-requirement "release report is read-only" --uncovered-requirement "npm auth verified" --blocked-kind auth_blocked --failure-cause auth_token_invalid --safe-retry "retry after npm whoami succeeds" --recovery-hint "refresh npm auth, then rerun readiness checks" --fix-first-item "npm auth must be verified before publish" --remaining-task "rerun release report after auth refresh" --recommended-direction "fix npm auth first, then publish manually" --implementation-note "keep loop report read-only" --why-this-next "auth blocks public release claims" --blocked-by "npm whoami E401" --owner-route deep --owner-scope "release readiness only" --scope-owner deep --side-effect "no publish attempted" --avoidance-note "do not retry publish before npm auth is proven" --next-step-spec ./next-step-spec.json --issue-code "src/bin/yam.ts release report" --issue-role "summarizes release readiness without publishing" --issue-symptom "npm auth failure needs clearer next action" --changed-code "yam loop report" --changed-role "records loop evidence and learning note" --change-summary "added a read-only loop artifact" --why-important "it helps users learn what changed without overclaiming verification" --learning-note "fix blockers before claiming done" --json
 yam proof /path/to/project
 yam proof --route deep --truth verified --command "npm run build: pass"
 yam proof --route ueye --truth verified --visual "reference image only"
@@ -217,10 +277,16 @@ yam proof write /path/to/project --format md --truth assumed --assumption "No ru
 yam safety "supabase db reset --linked"
 ```
 
+`completion-report.md` places a complete Study Note immediately before Next step. Next step must record the current situation, outlook, critical opinion, recommendations, then order `[fix-first]` before `[planned]` actions with owner, blocker/safe retry, evidence, side effects, and truth status.
+
 Release reporting intentionally runs the release checks and returns a machine-readable summary.
 
+With the default `--auth-mode auto`, `.github/workflows/release.yml` selects Trusted Publisher OIDC. A local `npm whoami` result is recorded only as an optional manual-token probe because the [official npm Trusted Publisher documentation](https://docs.npmjs.com/trusted-publishers/) states that it does not reflect publish-time OIDC authentication. Use `--auth-mode token` only when intentionally preparing a direct local token publish. The report stays blocked until the selected path has appropriate evidence; it never publishes.
+
 ```bash
 yam release report --json
+yam release report --auth-mode oidc --json
+yam release report --auth-mode token --json
 ```
 
 ## Flow Artifact Shapes
@@ -236,7 +302,7 @@ yam release report --json
 yam runtime evidence --backend terminal --claim cleanup-verified --cleanup-observed --exit-code 0 --cleanup-method "exit observed" --json
 yam mission receipt --thread-id reviewer-1 --role reviewer --lifecycle stopped --outcome passed --scope "changed files review" --evidence "read-only findings recorded" --json
 yam benchmark report --label "bundle size" --baseline 120 --current 118 --unit kB --target lower --json
-yam loop report --route deep --intent "verify release readiness" --blocked "npm auth not verified" --next-action "refresh npm token, then rerun npm whoami" --json
+yam loop report --route deep --intent "verify an explicitly selected manual-token release path" --blocked "npm auth not verified" --next-action "refresh npm token, then rerun npm whoami" --json
 ```
 
 Supported report shapes:
@@ -244,8 +310,9 @@ Supported report shapes:
 - Runtime evidence mini: command/process, observation, cleanup, truth status, next action.
 - Patch queue lite: mission lane status, changed files, verification hint, rollback hint, truth status.
 - Verification Ladder: L0 stated, L1 inspected, L2 local check, L3 integrated, L4 release/runtime/visual proof, L5 bounded deep with stop condition and skipped/remaining work.
-- Loop report: intent, guided stage outcomes, touched/read/verified files, skipped checks, stop condition, resume hint, readiness state, evidence level/stamp, blockers, blocker kind, safe retry, next action, fix-first items, remaining tasks, recommended direction, blocked-by notes, owner route/scope, side effects, and study note.
+- Loop report: intent, guided stage outcomes, touched/read/verified files, skipped checks, stop condition, resume hint, readiness state, evidence level/stamp, blockers, blocker kind, safe retry, next action, fix-first items, remaining tasks, recommended direction, blocked-by notes, owner route/scope, side effects, Study Note, and a Next step receipt when artifacts changed.
 - Study note: non-specialist explanation of the changed code/artifact, its role, execution point, before/after behavior, expected behavior, one syntax/structure insight, verification, uncertainty, and architecture hygiene around `page.tsx`, `global.css`, and DB `jsonb`.
+- Next step: whole-process situation/outlook scan, critical opinion, improvement recommendations, ordered fix-first then planned actions, ownership, blockers, safe retry, side effects, evidence level/stamp, truth status, and deterministic digest.
 - Study Note guard: read-only check for changed files and supplied final-report text; the opt-in `study-note` hook adds a prompt reminder and one bounded Codex `Stop` correction pass.
 - Benchmark optimization loop lite: baseline, one change, rerun, keep/revert decision.
 - Structured diagnostic next action: severity, evidence, owner route, next action, truth status.

package/README.md

@@ -45,6 +45,7 @@ See `ROADMAP.md` for remaining implementation stages.
 - Small work stays small, but serious work is allowed to become serious.
 - Security-sensitive work is never treated as ordinary polish.
 - When code, config, release metadata, documentation, or project artifacts changed, final reports include a Study Note even if no yam skill was invoked.
+- A changed-artifact report puts `Next step` immediately after Study Note. It rescans the whole process, states the situation and outlook, adds a critical opinion and improvement recommendations, then orders fix-first work before planned work.
 - Useful Study Notes explain what the changed code or artifact does, what role it has, what was wrong or missing, what changed, what behavior is expected, one small syntax/structure insight, what was verified, and what remains uncertain.
 - Research and reference scans should keep source boundaries clear, then rework good ideas into yam style.
 - Token economy is part of quality.
@@ -112,7 +113,18 @@ cd ~/Documents/Codex/tools/yam
 yam install
 ```
 
-`yam install` first checks ownership of every existing active skill. A skill is replaced automatically only when the previous yam receipt names it and its complete regular-file inventory and content hashes still match the receipt. The installer then stages every managed skill plus the shared `references/` directory, verifies the complete staged file manifest with SHA-256, and replaces the verified active set in `~/.agents/skills/`. If any commit or post-install verification step fails, yam restores the previous managed skill set and receipt.
+Preview the ownership and mutation plan without writing a lock, receipt, skill, or replacement:
+
+```bash
+yam install --dry-run --json
+yam install --dry-run --replace-user-skill quick --json
+```
+
+The `yam.install-plan.v1` result always reports `mutation_authorized: false` and includes a deterministic digest over the source manifest, destination, operations, preserved paths, and blockers. A replacement flag changes only the previewed ownership decision; mutation still requires a later `yam install` command.
+
+`yam install` first checks ownership of every existing active skill. A skill is replaced automatically only when the previous yam receipt names it and its complete regular-file inventory and content hashes still match the receipt. The installer then stages every managed skill plus the shared `references/` directory, verifies the complete staged file manifest with SHA-256, and replaces the verified active set in `~/.agents/skills/`. If any commit or post-install verification step fails, yam restores the previous managed skill set and receipt. Rollback and cleanup remove newly installed skills, receipts, locks, and transaction roots only while their recorded type and device/inode identity still match; an identity-swapped path is preserved and reported instead of being treated as yam-owned.
+
+Install source, destination, receipt, and managed-tree paths must use canonical physical directories. A symlink alias used as the package source or `YAM_SKILLS_HOME`, or a symlinked parent segment inside either boundary, fails closed; resolve the alias to its real path before retrying. Regular-file reads use descriptor identity checks and `O_NOFOLLOW` where the platform exposes it, while mutation boundaries revalidate parent directory identities. This narrows symlink-swap risk but is not `openat`-grade proof because Node does not expose descriptor-relative traversal here. Arbitrary Windows reparse-point handling is also unverified, so Windows receives the portable identity checks without a claim of complete reparse coverage.
 
 If an existing active directory is user-owned, locally modified, or cannot be proven yam-owned, installation stops before staging and preserves it. After reviewing the files, replace only the intended conflicting name explicitly:
 
@@ -152,7 +164,7 @@ yam update apply --all --json
 
 `--all` processes Scrapling, then Insane Search, then yam so the running updater replaces itself last. It stops at the first failed or manual-only component. After the global npm install, yam resolves `npm root -g`, the installed package manifest and bin mapping, the first `yam` on `PATH`, canonical realpaths, and the observed version before any `yam install` mutation. A same-version PATH shadow, malformed package, or identity mismatch fails closed; legitimate multi-hop symlinks remain valid. Rollback repeats the same identity check before rollback-side yam commands.
 
-A yam update is successful only after the installed version and status checks plus a final read-only `yam doctor --json` return the expected healthy contract. Doctor failure triggers the existing rollback path, and rollback is considered automatic only when its own identity, version, status, and Doctor checks pass. The deepest actionable rollback or Doctor cause remains primary even if receipt persistence also fails. Each attempt writes a bounded, redacted component receipt under `~/.local/state/yam/update-receipts/` with the old/new version, source revision, executable identity, checks, side effects, outcome, and rollback guidance. The aggregate apply response emits and verifies the strict `yam.gate-result.v1`; an already-held lock also returns a blocked gate without mutating components. A lock prevents concurrent apply runs.
+A yam update is successful only after the installed version and status checks plus a final read-only `yam doctor --json` return the expected healthy contract. Doctor failure triggers the existing rollback path, and rollback is considered automatic only when its own identity, version, status, and Doctor checks pass. The deepest actionable rollback or Doctor cause remains primary even if receipt persistence also fails. Each attempt writes a bounded, redacted component receipt under `~/.local/state/yam/update-receipts/` with the old/new version, source revision, registry artifact provenance, executable identity, checks, side effects, outcome, and rollback guidance. Read-only checks retain npm integrity plus `gitHead` for yam, PyPI release-file SHA-256 values for Scrapling, and the Git-pinned manifest commit for Insane Search. Apply pins the official npm registry and an isolated official PyPI index even when user config names an alternate source; npm and pip retain their native registry artifact-integrity enforcement, while the post-install identity/version checks bind the result. Insane Search requires a clean marketplace tree and tracked local manifest whose bytes match the checked Git object, then re-observes the Git commit and manifest before and after plugin add; a dirty or moved source blocks the receipt. The aggregate apply response emits and verifies the strict `yam.gate-result.v1`; an already-held lock also returns a blocked gate without mutating components. A lock prevents concurrent apply runs.
 
 Effective yam identity currently verifies POSIX-style executable/symlink layouts through `which` and canonical realpaths. Windows npm `.cmd` shim identity is intentionally unverified and fails closed until a dedicated shim parser and fixture exist.
 
@@ -160,6 +172,17 @@ Scrapling updates install an exact stable PyPI version into a new versioned virt
 
 There is no unattended updater. The exact project trigger in `AGENTS.md` grants one-time authorization for a checked `--all` run, and Codex is never restarted automatically.
 
+## Scout Receipts
+
+Repeated research can preserve an immutable delta-scan baseline without turning Scout into a default database:
+
+```bash
+yam scout receipt create --root . --receipt-path .yam/scout/run.json --spec scout-spec.json --json
+yam scout receipt verify --root . --receipt-path .yam/scout/run.json --json
+```
+
+The `yam.scout-receipt.v1` artifact binds the canonical entity and aliases, registry/release/main/latest-commit clocks, source URLs and digests, claim-to-source links, acquisition failures, opposition, recommendation, and stop reason. A non-`unknown` stability requires all four clocks; incomplete clock evidence must stay `unknown`. It rejects path escapes, symlinks, overwrites, oversized receipts, non-canonical ordering, and digest drift. Descriptor identity plus parent-directory revalidation narrows path-swap races, but Node does not expose `openat`-grade traversal and a receipt is not a signature against another process running as the same OS user. If an opened receipt write fails, yam preserves the possibly partial path for manual identity inspection instead of risking a path-based cleanup outside the root. The receipt proves local structure and integrity only: source interpretation remains operator-supplied and external content is never trusted as an instruction.
+
 ### Scrapling Usage
 
 The isolated executable can be used directly from the shell:
@@ -207,7 +230,11 @@ yam tools doctor /path/to/project --json
 yam context pressure /path/to/project --json
 yam cleanup scan /path/to/project --json
 yam detect /path/to/project --json
-yam study-note check /path/to/project --text "Study Note: ..." --json
+yam study-note check /path/to/project --report ./completion-report.md --json
+yam next-step report --spec ./next-step-spec.json --json
+yam next-step verify --receipt ./next-step-receipt.json --json
+yam scout receipt create --root /path/to/project --receipt-path .yam/scout/run.json --spec ./scout-spec.json --json
+yam scout receipt verify --root /path/to/project --receipt-path .yam/scout/run.json --json
 yam proof /path/to/project
 yam proof write /path/to/project --route quick --truth verified --command "npm run verify:self: pass"
 yam proof --route ueye --truth verified --visual "reference image only"
@@ -232,7 +259,7 @@ yam media proof --requested --attempted --output ./generated.png --wait-loop --j
 yam proof --route mission --mission-envelope '{"agent_id":"implementer","assigned_scope":"target component","changed_files":["src/file.ts"],"verification_hint":"npm run typecheck","truth_status":"partial"}'
 yam mission receipt --thread-id reviewer-1 --role reviewer --lifecycle stopped --outcome passed --scope "read-only review" --evidence "review completed without edits" --out .yam/mission/reviewer-1.json --json
 yam mission gate --expected-thread reviewer-1 --receipt .yam/mission/reviewer-1.json --out .yam/mission/completion.json --json
-yam loop report --route quick --intent "fix release readiness" --stage "inspect:passed:read release report" --evidence "typecheck passed" --evidence-level local --evidence-stamp "sha256:release-report" --touched-file src/bin/yam.ts --read-file README.md --verified-file scripts/cli-smoke.mjs --skipped-check "npm publish skipped by design" --stop-condition "stop after readiness evidence is recorded" --resume-hint "rerun release report after npm auth refresh" --readiness-state blocked --covered-requirement "release report is read-only" --uncovered-requirement "npm auth verified" --blocked-kind auth_blocked --failure-cause auth_token_invalid --safe-retry "retry after npm whoami succeeds" --recovery-hint "refresh npm auth, then rerun readiness checks" --fix-first-item "npm auth must be verified before publish" --remaining-task "rerun release report after auth refresh" --recommended-direction "fix npm auth first, then publish manually" --implementation-note "keep loop report read-only" --why-this-next "auth blocks public release claims" --blocked-by "npm whoami E401" --owner-route deep --owner-scope "release readiness only" --scope-owner deep --side-effect "no publish attempted" --avoidance-note "do not retry publish before npm auth is proven" --issue-code "src/bin/yam.ts release report" --issue-role "summarizes release readiness without publishing" --issue-symptom "npm auth failure needs clearer next action" --changed-code "yam loop report" --changed-role "records loop evidence and learning note" --change-summary "added a read-only loop artifact" --why-important "it helps users learn what changed without overclaiming verification" --learning-note "fix blockers before claiming done" --json
+yam loop report --route quick --intent "fix release readiness" --stage "inspect:passed:read release report" --evidence "typecheck passed" --evidence-level local --evidence-stamp "sha256:release-report" --touched-file src/bin/yam.ts --read-file README.md --verified-file scripts/cli-smoke.mjs --skipped-check "npm publish skipped by design" --stop-condition "stop after readiness evidence is recorded" --resume-hint "rerun release report after npm auth refresh" --readiness-state blocked --covered-requirement "release report is read-only" --uncovered-requirement "npm auth verified" --blocked-kind auth_blocked --failure-cause auth_token_invalid --safe-retry "retry after npm whoami succeeds" --recovery-hint "refresh npm auth, then rerun readiness checks" --fix-first-item "npm auth must be verified before publish" --remaining-task "rerun release report after auth refresh" --recommended-direction "fix npm auth first, then publish manually" --implementation-note "keep loop report read-only" --why-this-next "auth blocks public release claims" --blocked-by "npm whoami E401" --owner-route deep --owner-scope "release readiness only" --scope-owner deep --side-effect "no publish attempted" --avoidance-note "do not retry publish before npm auth is proven" --next-step-spec ./next-step-spec.json --issue-code "src/bin/yam.ts release report" --issue-role "summarizes release readiness without publishing" --issue-symptom "npm auth failure needs clearer next action" --changed-code "yam loop report" --changed-role "records loop evidence and learning note" --change-summary "added a read-only loop artifact" --why-important "it helps users learn what changed without overclaiming verification" --learning-note "fix blockers before claiming done" --json
 yam release report --json
 yam safety "supabase db reset"
 yam pack /path/to/project
@@ -255,6 +282,8 @@ yam version
 yam init-project /path/to/project
 ```
 
+`completion-report.md` must contain a complete `Study Note` followed immediately by `Next step`; the latter records situation, outlook, critical opinion, recommendations, then every `[fix-first]` action before `[planned]` work with owner, blocker/safe retry, evidence, side effects, and truth status.
+
 ## npm / npx Prep
 
 The package exposes the `yam` binary. It does not mutate your home directory during package installation.
@@ -270,7 +299,9 @@ After `yam status` reports all skills and the install receipt as `ok`, restart C
 
 Before packaging or publishing, `verify:self` inspects the exact file list returned by `npm pack --dry-run --json --ignore-scripts`. The release gate scans regular UTF-8 text files up to 2 MiB for high-signal private-key, npm, GitHub, OpenAI, Anthropic, and AWS credential patterns. Findings expose only the pattern id, package-relative path, and line number; matched text is never printed. Binary, symlink, non-regular, unreadable, outside-root, and oversized entries are reported as skipped rather than silently represented as scanned.
 
-Publishing still requires confirming the final npm package name and account access.
+Public release workflows pack one tarball once, record its SHA-256/size/source receipt, reuse those bytes for Linux, macOS, and Windows install/status/Doctor/reinstall/uninstall checks, and publish the same artifact through npm Trusted Publishing with provenance. All referenced GitHub actions are pinned to reviewed commit SHAs. Release mode requires an exact `v<package.version>` annotated signed tag contained in `origin/main`.
+
+Publishing remains blocked until the npm package settings register the exact `.github/workflows/release.yml` filename as the trusted publisher. The workflow does not accept a long-lived npm token, does not run from branch or tag pushes, and publishes only after an explicit manual dispatch names the reviewed signed version tag.
 
 ## Trust Kernel
 
@@ -293,6 +324,8 @@ Publishing still requires confirming the final npm package name and account acce
 - release report JSON
 - loop report JSON
 - study note JSON
+- evidence-bound Next step JSON and verification
+- immutable Scout source/claim receipt verification
 - structured diagnostic next actions
 - context pressure summaries
 - advisory cleanup scans
@@ -313,13 +346,14 @@ These shapes keep reports machine-readable without turning normal work into a he
 - Patch queue lite: `$mission` lane records with pending/applied/verified/reverted/blocked state, changed files, verification hint, rollback hint, truth status, and next action.
 - Mission completion receipt: every expected thread records lifecycle and outcome separately; reviewer/doctor write access, missing evidence, ambiguous stops, and receipt inventory gaps block the aggregate gate.
 - Verification Ladder: L0 stated, L1 inspected, L2 local check, L3 integrated, L4 release/runtime/visual proof, and L5 bounded deep. Heavier claims require heavier evidence, but stop conditions prevent endless proof loops.
-- Release report JSON: `yam release report --json` summarizes typecheck, forbidden-name scan, package boundary, registry status, CLI smoke, dist freshness, diagnostics, readiness receipt, and final truth status.
-- Loop report JSON: `yam loop report --json` records a read-only handoff artifact: guided stages, touched/read/verified files, skipped checks, stop condition, resume hint, readiness state, requirement coverage, evidence level/stamp, blocker kind, failure cause, safe retry, recovery hint, owner route/scope, side effects, next action, fix-first items, remaining tasks, recommended direction, implementation notes, blocked-by notes, avoidance note, tool intent, truth status, and study note.
-- Study note: `yam.study-note.v1` and `references/study-note.md` keep non-specialist explanations for what code/artifact changed, what role it plays, where it runs, what changed from before to after, what behavior is expected, one syntax/structure insight, what was verified, and what remains uncertain. Missing details stay in `limits` instead of being guessed. Study Note v3 also asks whether work was dumped into `page.tsx`, `global.css`, or broad DB `jsonb` when a smaller component, style module/token, typed column, relation, or validation schema would teach and scale better.
+- Release report JSON: `yam release report --json` summarizes typecheck, forbidden-name scan, package boundary, registry status, CLI smoke, dist freshness, diagnostics, readiness receipt, and final truth status. Default `--auth-mode auto` selects Trusted Publisher OIDC when the reviewed release workflow is present, treats `npm whoami` as an optional manual-token probe rather than OIDC evidence, and blocks on missing workflow controls or unverified npmjs package binding instead. `--auth-mode token` explicitly selects direct local token readiness.
+- Loop report JSON: `yam loop report --json` records a read-only handoff artifact: guided stages, touched/read/verified files, skipped checks, stop condition, resume hint, readiness state, requirement coverage, evidence level/stamp, blocker kind, failure cause, safe retry, recovery hint, owner route/scope, side effects, next action, fix-first items, remaining tasks, recommended direction, implementation notes, blocked-by notes, avoidance note, tool intent, truth status, Study Note, and an optional `--next-step-spec` receipt. Changed artifacts without a valid Next step are blocked.
+- Study note: `yam.study-note.v1` and `references/study-note.md` keep non-specialist explanations for what code/artifact changed, what role it plays, where it runs, what changed from before to after, what behavior is expected, one syntax/structure insight, what was verified, and what remains uncertain. Missing details stay in `limits` instead of being guessed. Study Note v4 keeps the architecture-hygiene check for `page.tsx`, `global.css`, and broad DB `jsonb`, then requires an evidence-bound Next step immediately afterward.
+- Next step: `yam.next-step.v1` records the whole-process scan, outlook, critical opinion, recommendations, ordered fix-first/planned actions, owner scope, blockers, safe retry, side effects, L0-L5 evidence, and a deterministic digest. Unknown fields, contradictory truth, weak evidence for strong claims, and tampering fail closed.
 - Study Note guard: `yam study-note check` is a read-only missing-note guard. The opt-in `yam hook enable study-note --global` profile reuses it for a prompt reminder and one bounded Codex `Stop` correction pass; it still does not generate or edit a report.
 - Avoidance note: loop reports may include one short mistake-to-avoid note, but durable memory stays explicit through `yam memory add`; `yam loop report` does not write `.yam/memory`.
 - Publish blocker evidence: release reports classify common npm auth, permission, OTP, immutable-version, cache, registry, and tarball failures into safe next actions.
-- Publish readiness evidence: release reports run read-only registry/auth/version probes, redact account/token details, keep npm publish outside the report, and include a `yam.release-readiness-receipt.v1` basis for the readiness judgment.
+- Publish readiness evidence: release reports run read-only registry/auth/version probes, redact account/token details, keep npm publish outside the report, and include a `yam.release-readiness-receipt.v1` basis for the readiness judgment. OIDC account binding remains explicitly unverified until the npmjs Trusted Publisher configuration and hosted publish result provide evidence; this follows the [official npm Trusted Publisher behavior](https://docs.npmjs.com/trusted-publishers/), where `npm whoami` does not reflect OIDC authentication.
 - Context pressure: `yam context pressure` explains when project context is getting stale, broad, or confusing enough to summarize, refresh, narrow scope, or deepen route.
 - Changed-file verification detector: `yam detect [dir] --json` reads dirty, staged, and untracked Git paths and returns advisory `matched_rule`, `confidence`, `reason`, `fallback`, source files, and only commands that exist in the project. Its deduplicated command plan retains the contributing rules and files, but never runs the commands. If Git status is unavailable, it reports a low-confidence fallback instead of claiming the project is clean.
 - Cleanup scan: `yam cleanup scan` is read-only and advisory; it reports confusing hooks, local skill folders, stale traces, or old proof artifacts without deleting anything. Its bounded AGENTS/SKILL duplication budget scans at most 24 files and 128 KB per file, reports exact normalized cross-surface directive matches with redacted previews and provenance, and never becomes a hard gate.
@@ -335,6 +369,8 @@ These shapes keep reports machine-readable without turning normal work into a he
 - Bounded promotion receipt: `yam benchmark report` can compare paired candidate/baseline measurements under explicit sample, mean-delta, and win-rate thresholds. Arithmetic is verified, while measurement provenance remains `operator_asserted` and overall truth stays `partial`.
 - Honest capability matrix: `yam tools doctor --json` reports feature maturity separately from observed runtime readiness; instruction-only or unprobed capabilities are not reported as executed.
 - Strict gate result: release, update, benchmark-promotion, and Mission completion boundaries emit a digest-bound `yam.gate-result.v1` and fail closed on missing or inconsistent required evidence.
+- Final-scope verification closure: `yam verification closure create|verify` binds the planned boundary, current Git dirty/staged/untracked paths, release-sensitive escalation, selected versus operator-declared executed commands, skipped/truncated reasons, and an immutable digest. Missing required execution, unknown results, unplanned files, unavailable Git scope, and later receipt tampering fail closed; yam does not execute the recorded commands or upgrade their truth beyond `partial`.
+- Optional media provider receipt: `yam media provider create|verify` records an explicit demand trigger, exact `provider_calls`/`provider_execution`/`dry_run`/`submit` state, and identity-bound local asset provenance. It never calls a provider, and integrity verification never proves visual or implementation correctness.
 
 ## Ueye Capture And Compare
 
@@ -366,4 +402,8 @@ Generated media can guide visual direction, but it cannot prove the implemented
 yam media proof --requested --attempted --output ./generated.png --wait-loop --json
 ```
 
+When real repeated media work needs an execution boundary, prepare bounded JSON asset specs and opt in explicitly. Dry-run receipts require zero calls/no submit; execution receipts require a submitted call plus a provider-provenance output. Both the receipt and local asset paths are confined below the project root and can be re-read with `yam media provider verify`. The existing `yam media proof` command remains the lightweight default.
+
+For completion evidence, `yam verification closure create` consumes small selected/executed/skipped/truncated JSON specs. It snapshots actual Git status before writing under `.yam/verification/`; declare every expected changed path with repeated `--changed-file`, then use `verify` to detect semantic, digest, or current Git path-set drift. `current_git_scope_drift` means checks must be rerun against the final state and a new immutable receipt must be created. This remains an explicit artifact, not an always-on hook or command runner.
+
 For agent-driven visual QA, prefer the Codex in-app Browser plugin. Use the user's Chrome browser only when explicitly requested or when Chrome-only session/profile state is required.

package/ROADMAP.md

@@ -9,11 +9,15 @@ Implemented:
 - Shared references.
 - Local CLI: list, status, verify, doctor, examples, path, install, uninstall.
 - Transactional skill install with rollback, SHA-256 receipt, install lock, and status drift detection. Done.
+- Pure install dry-run plans with ownership blockers, explicit replacement previews, deterministic digests, and zero mutation authorization. Done.
 - CLI helpers: detect, budget, template, tune-log, version.
 - Optional advisory `yam-lite` hook with status/enable/disable. Done.
 - Optional Study Note prompt reminder plus bounded Codex `Stop` completion gate, hook health, and stale-path migration. Done.
 - Opt-in project memory: init, add, list, summary, resolve.
 - Honest completion guard: no verified/cleanup/visual claims without evidence.
+- Evidence-bound Next step contract and Study Note adjacency guard for changed artifacts. Done.
+- Immutable Scout source/claim receipts and four-clock freshness classification for repeated scans. Done.
+- Exact-tarball cross-platform supply-chain workflows with signed-tag gating and npm OIDC provenance. Done locally; npm trusted-publisher registration remains external.
 - No hooks, automations, or global config mutations unless the user explicitly enables them.
 - Token economy policy.
 
@@ -53,6 +57,7 @@ Tasks:
 - Detect common commands: typecheck, lint, test, build. Done.
 - Map changed files to likely checks. Done: dirty, staged, and untracked paths now map to focused rules with confidence, reason, fallback, and available commands.
 - Keep this advisory, not mandatory. Done.
+- Add an explicit final-scope closure artifact without turning the detector into an auto-runner. Done: immutable receipts bind current Git scope, release escalation, selected/executed command separation, skipped/truncated reasons, and partial operator-asserted truth.
 
 ### 4. Token Budget Reporter
 
@@ -76,6 +81,7 @@ Tasks:
 - Add local reference asset provenance/protection manifest and non-overwriting revision history. Done.
 - Add optional browser/screenshot capture notes.
 - Keep image generation optional, never a gate.
+- Add an optional provider-execution boundary only when real media demand exists. Done: exact fail-closed execution fields, confined hash-bound local assets/provenance, and verify/tamper detection without provider calls or correctness claims.
 
 ### 6. Deep Runtime Workflow
 
@@ -94,10 +100,12 @@ Goal: make install/update simpler.
 
 Tasks:
 
-- Add symlink-friendly local install.
+- Reconsider symlink-friendly local install only if Node exposes a safe descriptor-relative traversal boundary or an equivalent proven design. Deferred: current package source, `YAM_SKILLS_HOME`, and managed-tree paths intentionally reject symlink aliases and symlinked parent segments.
 - Add version command. Done.
 - Add staged transactional install, rollback, receipt, and drift-aware status. Done.
+- Add a non-mutating install plan before authorization, including conflict and explicit-replacement operations. Done.
 - Add checked component updates for yam, Scrapling, and Insane Search with explicit authorization, receipts, and rollback guidance. Done.
+- Preserve registry artifact provenance in updater checks and component receipts. Done.
 - Consider npm packaging only after route behavior stabilizes.
 
 ### 8. Scout / Research Workflow
@@ -121,6 +129,8 @@ Tasks:
   - realistic view: near-term feasibility and cost
   - future view: second-order effects and durable bets
 - Match source count to the decision: focused scouts use a few high-signal sources, broad scouts may use more. Done.
+- Resolve one canonical entity and compare registry, release/tag, main, and latest-commit clocks before calling an update new or stable. Done.
+- Add an immutable, digest-bound source/claim receipt for repeated delta scans while keeping source truth operator-supplied. Done.
 - Avoid making research a default gate for implementation. Done.
 
 ### 9. Question Workflow
@@ -140,11 +150,14 @@ Goal: prepare yam for a personal GitHub repo under `0kim0bos`.
 
 Tasks:
 
-- Choose repository description.
-- Add a short public README intro.
-- Add install/update instructions for local Codex skills.
-- Add a clear note that yam installs no hooks and no automations by default.
-- Re-run source/install verification before publishing.
+- Choose repository description. Done.
+- Add a short public README intro. Done.
+- Add install/update instructions for local Codex skills. Done.
+- Add a clear note that yam installs no hooks and no automations by default. Done.
+- Pack one tarball once and reuse its exact bytes across Linux, macOS, and Windows lifecycle checks. Done.
+- Require a clean, exact-version, `origin/main`-contained signed tag before public publishing. Done.
+- Publish only through npm OIDC/provenance without a repository npm token. Workflow done; npm package settings still need the exact trusted-publisher workflow registration.
+- Re-run source/install/release verification before publishing. Required for each release.
 
 ### 11. Memory Workflow
 
@@ -276,7 +289,7 @@ Tasks:
 - Add `$ueye`. Done.
 - Retire `$fast`, `$build`, `$ui`, `$eye`, and `$review`. Done.
 - Update CLI budgets, templates, docs, manifest, install cleanup. Done.
-- Re-run source and installed-skill verification. Pending after install.
+- Re-run source and installed-skill verification. Done for the local 2.8.0 install; repeat for each release candidate.
 
 ### 15. Lite Hook / Progressive Tool Trust Layer