# Project Briefing — dry-aged-deps Per-topic briefing index. Each topic file holds short, durable observations across "What You Need to Know" and "What Will Surprise You". The Critical Points roll-up below is loaded at session start; topic files are read on demand. ## Critical Points - **Release model is non-standard.** `package.json` version is stale (per ADR-0005). semantic-release reads commit types from git, ignores the repo's `version` field, and publishes to npm on push to `main` when commits map to a bump. Current published version: `dry-aged-deps@2.16.0`. The repo file still shows `0.1.3`. - **Releases are gated on no-pending-safe-deps.** `ci-publish.yml`'s Build & Test runs `dry-aged-deps --check`, which exits 1 (fails the job, skips the release) while any safe dep update is pending. A `feat:`/`fix:` won't publish until the deps land in a `chore(deps):` commit. `push:watch` enforces the same gate. Use `ci:`/`chore:` (not `feat(ci):`) for internal-tooling/workflow changes or a stray `feat:` triggers an unwanted minor release. - **Auto-update is one workflow now (ADR-0017, supersedes 0009+0010).** `auto-update.yml` is a single inline loop (detect→apply→bounded prepush+claude-fix retry→PR+auto-merge); `auto-update-recover.yml` was deleted; the `needs-human` path is gone. Only DIRECT deps are tracked — transitive security fixes (npm-bundled deps, npm via `@semantic-release/npm`) never land via the scheduled flow (P013). **As of 2026-07:** `--update` reconciles `package-lock.json` itself (P030/ADR-0021, v2.15.0); `--update`/`--check` flag+skip un-landable peer-graph updates as `incompatible-peers` (P028/ADR-0022, v2.16.0, default-on, `--no-landable-check` to disable). The workflow's `jq` was reading fields the tool never emits (`.safeUpdate`/`.severity`) — every bump rendered `→ null` and security updates never promoted to a release; fixed 2026-07-11 to read `.latest` (safe target) + `.vulnerabilities.maxSeverity`. - **TBD with admin-bypass branch protection.** Branch protection on `main` requires the `Build & Test` status check AND leaves "Do not allow bypassing" UNCHECKED. The repo owner is admin, so direct pushes bypass the rule; the bot's PR (non-admin) is gated. Do not enable "Require a pull request before merging" — it would block TBD. - **`dry-aged-deps --update` writes the `latest`-safe version per ADR-0014 (P001 verifying, shipped in v2.7.1).** `applyUpdates()` destructures the 4th tuple element (post-filter / post-smart-search safe target), not the 3rd (`wanted`). Exact-pinned packages bump cleanly. Cross-major bumps are reachable; consumer-side breakage caught by `prepush` + `ci-publish.yml`. ADR-0009 §Confirmation criteria 2+7 now satisfiable. **The safe target now surfaces in JSON/XML as BOTH `.latest` and `.recommended`** — P031 fixed `output-utils.js:36` (`recommended: wanted` → `recommended: latest`, 2026-07-11, verifying), so `.recommended === .latest` (the post-smart-search safe target). Before the fix, on exact-pinned projects `.recommended === current` (an X→X no-op); `auto-update.yml` reads `.latest` to stay robust regardless. - **CLAUDE_CODE_OAUTH_TOKEN is for Claude API auth only.** GitHub-API operations in workflows use a runtime-minted GitHub App installation token via OIDC exchange against `api.anthropic.com/api/github/github-app-token-exchange` (per ADR-0012). No `ANTHROPIC_API_KEY`. No `DEPS_BOT_TOKEN` (deferred fallback per ADR-0012 Reversion Plan). - **Pre-commit hook auto-writes and re-stages (ADR-0016, supersedes ADR-0013; P009 verifying, shipped in v2.8.0).** `.husky/pre-commit` runs `git diff --cached --name-only --diff-filter=ACM | xargs npx prettier --write --ignore-unknown && xargs git add` on staged files only, then `npm run format:check` as defense-in-depth, then lint + type-check. Formatted output lands IN the commit; working tree is clean post-commit. Workspace state dirs (`.afk-run-state/`, `.claude/`, `.risk-reports/`, `*.backup`) are in `.gitignore` and `.prettierignore`. Reassessment trigger from ADR-0013 (≥2 sessions of abort friction) fired in P008+P009; user's narrowing constraint resolves "no silent mutation" because the fix lands in the commit. - **Push goes through `npm run push:watch`.** A global Claude PreToolUse hook intercepts `git push` and redirects. The wrapper lives at `scripts/push-watch.sh` and aborts pre-emptively if stale safe deps are detected. Post-push release-trigger heuristic captures `@{push}` BEFORE push (P002 closed via v2.7.3 drain). - **Autonomous-update workflow auth is HTTP Basic (`x-access-token`), not bearer.** App installation tokens used for `git push` via `auto-update.yml` MUST use either URL-embedded `https://x-access-token:$APP_TOKEN@github.com/owner/repo.git` (canonical, what ships in v2.7.3) or `git -c http.extraheader=AUTHORIZATION: basic $(base64 of "x-access-token:$APP_TOKEN")`. Bearer works for the API but not for git transport. P008 shipped two-layer fix: v2.7.2 `persist-credentials: false` + v2.7.3 URL-embedded basic auth. Repo also needs "Allow auto-merge" enabled in Settings → General → Pull Requests for the workflow's `gh pr merge --auto` step to succeed. - **Before any `git commit -m "$(cat <<'EOF' ... EOF)"` with risk-scorer / voice-tone gates active: compose the `...` block from the EXACT final commit body, Co-Authored-By trailer included.** Marker hash is `sha256(draft + '\n' + surface)` keyed bytewise. Omitting the trailer in the review draft (or shell-escaping backticks in the heredoc post-PASS) re-blocks the gate. Promoted from `hooks-and-gates.md§52` after 3 hits in 2026-06-05 (iters 3, 5, 7). ## Topic Index | Topic | File | Scope | | ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Releases & CI | [`releases-and-ci.md`](releases-and-ci.md) | semantic-release, ci-publish.yml, version handling, push:watch | | Hooks & gates | [`hooks-and-gates.md`](hooks-and-gates.md) | architect/JTBD/TDD/ITIL gates, husky hooks, marker files | | Governance workflow | [`governance-workflow.md`](governance-workflow.md) | ADR / risk-policy / JTBD review cadence, capture-on-correction | | Autonomous dep updates | [`autonomous-dep-updates.md`](autonomous-dep-updates.md) | single-workflow inline-loop auto-update.yml (ADR-0017), OIDC token-exchange, branch protection, transitive-dep blind spot |