yam-flow 2.3.1 → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to yam-flow are documented here.
 
+## v2.4.0 - 2026-07-27
+
+### Added
+
+- Added ownership-aware skill replacement: an existing active skill is replaced only when the previous yam receipt and complete regular-file inventory and content hashes prove yam ownership, unless the operator explicitly names that skill with `--replace-user-skill`.
+- Added a central CLI help contract so `--help` and `-h` return usage before any command dispatch, including install and uninstall.
+- Added deterministic smoke coverage for user-owned conflicts, explicit replacement, prior-version upgrades, local drift, safe uninstall and rollback, preserved legacy/mirror entries, and help-path state immutability.
+- Added `yam detect [dir] --json` changed-file verification recommendations for dirty, staged, and untracked Git paths. Each advisory records its matched rule, confidence, reason, fallback, and source files; its command plan deduplicates available project commands while retaining rule/file provenance, and unavailable Git scope cannot masquerade as a clean project.
+- Added a deterministic packaged-hook latency and read-only regression smoke for zero, one, and many changed files, including the eight-file prompt cap and bounded Study Note `Stop` behavior.
+
+### Improved
+
+- `yam uninstall` now requires a valid receipt and matching active skill hashes, then removes the verified set transactionally. User-owned, locally modified, legacy, retired, and Codex mirror entries that cannot be proven yam-owned are preserved.
+- Install ownership is checked before staging and again immediately before mutation so conflicts fail closed without replacing the existing skill or receipt.
+- `yam doctor` reports safely preserved legacy/retired/mirror entries as informational unproven entries instead of failing with an ineffective reinstall recommendation.
+- `yam cleanup scan` now includes a bounded, advisory-only AGENTS/SKILL directive-duplication budget with exact normalized matching, digests, redacted limited previews, and file/line provenance. It remains non-destructive and never becomes a hard gate.
+- Study Note check, prompt, and `Stop` paths now preserve Git change-scope availability. A non-Git or failed Git probe reports partial truth and a manual-inspection warning instead of silently claiming that no artifacts changed.
+
+### Verification
+
+- Passed TypeScript typecheck, clean build, hook latency/read-only smoke, the 174-file install/uninstall transaction smoke, packaged CLI smoke, self-verification, forbidden-name scan, distribution freshness, package-boundary validation, and diff whitespace checks.
+
+## v2.3.2 - 2026-07-21
+
+### Added
+
+- Added a bounded Codex `Stop` completion gate to the opt-in `study-note` hook profile. Changed work with a missing or incomplete Study Note receives one correction prompt before completion.
+- Added hook health inspection for missing executables, missing script targets, incomplete event coverage, duplicate handlers, unsupported command shapes, and unreadable hook config.
+- Added deterministic packaged-CLI smoke coverage for broken-path detection, nonzero health status, backup-backed migration, unrelated-hook preservation, Stop blocking/passing, and loop prevention.
+
+### Improved
+
+- `yam hook status` now reports configured-but-broken profiles as `broken` and exits nonzero instead of calling a stale command `enabled`.
+- Re-enabling a hook profile migrates stale absolute paths to the current installed Node and package entrypoint, adds the required events, preserves unrelated hooks, creates a timestamped backup, and writes config atomically.
+- Study Note Guard checks now cover execution point, expected behavior, syntax or structure insight, verification, and limits separately.
+
+### Verification
+
+- `npm run verify:self`
+- `npm run dist:freshness`
+- `npm run package-boundary:check`
+- `npm run cli-smoke`
+
 ## v2.3.1 - 2026-07-21
 
 ### Added

package/COMMANDS.md

@@ -152,7 +152,8 @@ yam tools doctor /path/to/project
 yam tools doctor /path/to/project --json
 yam context pressure /path/to/project --json
 yam cleanup scan /path/to/project --json
-yam study-note check /path/to/project --text "Study Note: Touched code role before/after verification limits." --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 proof /path/to/project
 yam proof --route deep --truth verified --command "npm run build: pass"
@@ -206,18 +207,19 @@ Supported report shapes:
 - 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.
 - 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`.
-- Study Note guard: read-only check for changed files and supplied final-report text; opt into prompt-time reminders with `yam hook enable study-note --global`.
+- 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.
 - Ueye continuity/comparison: previous report, current report, comparison delta, design quality, next action.
 - Ueye design brief/anti-slop: brief dimensions, constraints, invented metrics, placeholder copy, generic visuals, and custom P0 blockers.
 - Ueye deep visual review: acceptance criteria, touched/read/verified files, skipped checks, residual risks, stop condition, resume hint, design-system evidence, implementation evidence, and state matrix.
 - Context pressure: project pack age/size, memory summary, dirty scope, scripts, instruction surfaces, and route hint.
-- Cleanup scan: advisory-only list of confusing surfaces with destructive=false.
+- Changed-file verification detector: dirty/staged/untracked Git paths grouped into advisory rules with confidence, reason, fallback, source files, and available project commands; the command plan is deduplicated while retaining rule/file provenance, Git-unavailable scope stays low confidence, and no recommendation is executed.
+- Cleanup scan: advisory-only list of confusing surfaces with `destructive=false`, plus a bounded exact-normalized AGENTS/SKILL cross-surface duplication budget with file/line provenance.
 
-## Lite Hook
+## Hooks
 
-Advisory-only hook. It does not run checks or force routes.
+`lite` is advisory-only. `study-note` runs the read-only Study Note Guard against the final assistant message and can request one correction pass; neither profile runs verification or forces routes.
 
 ```bash
 yam hook status --global
@@ -226,3 +228,5 @@ yam hook enable study-note --global
 yam hook disable lite --global
 yam hook disable study-note --global
 ```
+
+`yam hook status` exits nonzero for unreadable configs, stale paths, missing targets, duplicate handlers, or incomplete event coverage. Re-enable the affected profile to back up the file, preserve unrelated hooks, and migrate its command and events.

package/README.md

@@ -35,6 +35,7 @@ See `ROADMAP.md` for remaining implementation stages.
 
 - No required hooks.
 - Optional `yam-lite` hook is advisory-only and off by default.
+- Optional `study-note` hook adds a prompt reminder and a bounded final-response check; it is off by default.
 - No automatic Team routing.
 - No automatic proof loops.
 - No automatic tmux.
@@ -87,6 +88,19 @@ yam hook disable lite --global
 
 It only adds short advisory context. It does not run verification, tmux, browser QA, subagents, or dependency installs.
 
+## Study Note Hook
+
+Enable this profile when you want Codex to check changed work at final-response time as well as remind the agent at prompt time.
+
+```bash
+yam hook enable study-note --global
+yam hook status --global
+```
+
+The profile installs `UserPromptSubmit` and `Stop` handlers. At `Stop`, yam checks the latest assistant message with the same read-only Study Note Guard used by `yam study-note check`. If changed artifacts lack the required role, execution point, before/after, expected behavior, syntax/structure, verification, limits, or relevant architecture hygiene, Codex receives one correction prompt. A second failed check warns but does not loop forever. If Git change scope is unavailable, the guard reports partial truth and keeps a manual-inspection warning visible instead of claiming the project is clean. The hook never writes the Study Note or runs verification for the agent.
+
+`yam hook status` reports stale or missing command targets as `broken` and exits nonzero. Run `yam hook enable <profile> --global` again to create a timestamped backup, preserve unrelated hooks, and migrate that profile to the current installed path and event coverage. Restart Codex or open a new task after changing hooks.
+
 ## Install
 
 Recommended:
@@ -96,10 +110,20 @@ cd ~/Documents/Codex/tools/yam
 yam install
 ```
 
-`yam install` stages every managed skill plus the shared `references/` directory, verifies the complete staged file manifest with SHA-256, and only then replaces the active set in `~/.agents/skills/`. If any commit or post-install verification step fails, yam restores the previous managed skill set and receipt.
+`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.
+
+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:
+
+```bash
+yam install --replace-user-skill quick
+```
+
+Repeat `--replace-user-skill <name>` for each reviewed conflict. Unproven legacy, retired, and Codex mirror directories are preserved rather than deleted by name.
 
 A successful install writes `~/.agents/skills/.yam-flow-install-receipt.json`. The receipt records the package version, source identity, install timestamp, destination, managed skill inventory, and per-file hashes. `yam status` independently recomputes source and installed hashes, so a stale package install, local file change, unexpected file, or modified receipt is reported as drift.
 
+The receipt is local integrity provenance, not a cryptographic signature or a security boundary against another process running as the same OS user. An actor that can rewrite both the receipt and every recorded file can forge local ownership evidence.
+
 An ordinary install error rolls back automatically. An abrupt process or machine termination can leave `.yam-flow-install.lock` and a hidden transaction directory; `yam status` surfaces the unfinished transaction and yam refuses another mutation while recovery state remains. Remove the lock only after confirming no install is running, and preserve any transaction directory until the previous installation state has been inspected.
 
 Manual copying can still make a skill loadable, but it intentionally remains unverified: without a matching receipt, `yam status` exits non-zero and recommends `yam install`.
@@ -113,6 +137,8 @@ cd ~/Documents/Codex/tools/yam
 yam uninstall
 ```
 
+`yam uninstall` verifies the receipt, complete active inventory, and current file hashes before deleting anything. A missing receipt or locally modified active skill blocks the whole uninstall. Verified active skills and the receipt are removed transactionally; unproven legacy, retired, and Codex mirror entries remain untouched.
+
 No hooks, automations, or global config files are installed.
 
 ## Manage
@@ -126,6 +152,7 @@ yam tools doctor /path/to/project
 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 proof /path/to/project
 yam proof write /path/to/project --route quick --truth verified --command "npm run verify:self: pass"
@@ -147,7 +174,6 @@ yam mission gate --expected-thread reviewer-1 --receipt .yam/mission/reviewer-1.
 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 release report --json
 yam safety "supabase db reset"
-yam detect /path/to/project
 yam pack /path/to/project
 yam hook status --global
 yam hook enable lite --global
@@ -227,12 +253,13 @@ These shapes keep reports machine-readable without turning normal work into a he
 - 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.
-- Study Note guard: `yam study-note check` is a read-only missing-note guard. It checks changed files against supplied final-report text and can be used directly or through the opt-in `yam hook enable study-note --global` advisory hook.
+- 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.
 - Context pressure: `yam context pressure` explains when project context is getting stale, broad, or confusing enough to summarize, refresh, narrow scope, or deepen route.
-- 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.
+- 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.
 - Benchmark optimization loop lite: use `yam measure <route>` and `yam template tuning` to record baseline, one route wording change, rerun result, keep/revert decision, and stop condition.
 - Structured diagnostic next action: every doctor/release diagnostic should say what was observed, what evidence supports it, what to do next, owner route, severity, and truth status.
 - Ueye review continuity/comparison report: `$ueye` run reports can link a previous review, current evidence, comparison delta, design quality result, and next action.

package/ROADMAP.md

@@ -11,9 +11,10 @@ Implemented:
 - Transactional skill install with rollback, SHA-256 receipt, install lock, and status drift detection. 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.
-- No hooks, automations, or global config.
+- No hooks, automations, or global config mutations unless the user explicitly enables them.
 - Token economy policy.
 
 ## Next Stages
@@ -50,8 +51,8 @@ Tasks:
 
 - Read `package.json` scripts.
 - Detect common commands: typecheck, lint, test, build. Done.
-- Map changed files to likely checks. Partial: route-level suggestions added.
-- Keep this advisory, not mandatory.
+- 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.
 
 ### 4. Token Budget Reporter
 
@@ -304,6 +305,8 @@ Tasks:
 
 - Add `yam hook status|enable|disable|run lite`. Done.
 - Keep `yam-lite` advisory-only through `UserPromptSubmit`. Done.
+- Add Study Note `UserPromptSubmit` reminder plus one-pass `Stop` completion gate. Done.
+- Detect broken hook targets and migrate stale paths without replacing unrelated hooks. Done.
 - Add `references/tool-trust-layer.md`. Done.
 - Add read-only `yam tools doctor`. Done.
 - Add `yam proof` summary command. Done.