devflow-kit 3.7.0 → 3.9.0

package/CHANGELOG.md

@@ -5,6 +5,482 @@ All notable changes to Devflow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.9.0] - 2026-10-22
+
+### Upgrade notes — Evaluate by level
+
+**What you must do:**
+- At `standard`, the default, and at `lean`, `/implement` now runs one Evaluate pass and at most one alignment Fix round, with no second Evaluate. Run `devflow gates --set full` to keep up to two Fix rounds, each checked again.
+
+**Stale-install window:**
+- Until you run `devflow init`, your installed level reference has no Evaluate row, so Evaluate runs as at `full`. If the reference is new and the installed Evaluate agent is old, `/implement` runs one pass at the full report scope.
+
+### Upgrade notes — Severity tiers by level
+
+**What changes:**
+- At `standard`, the default, and at `lean`, `/resolve` no longer fixes every finding that the matrix sends to FIX_NOW. Triage sorts each kept item into a severity tier. `full` keeps today's triage and fixes. At every level, each issue cell in `resolution-summary.md` starts with its severity in brackets.
+  - CRITICAL, HIGH and severe MEDIUM findings in the branch's own code stay FIX_NOW.
+  - A prose-only MEDIUM finding is fixed with text edits alone. If Code must change logic to fix it, Code leaves it unedited and the item goes to Fix Separately.
+  - Lower MEDIUM and LOW findings go to Fix Separately. One backlog issue records them.
+  - A pre-existing finding that is not a security finding goes to Fix Separately, also when the branch touched its file.
+  - A security finding stays FIX_NOW or ESCALATED at every severity, LOW and pre-existing included.
+- Run `devflow gates --set full` to keep today's `/resolve`: Triage applies no tiers, every FIX_NOW item is fixed, and a pre-existing finding in a touched file is fixed.
+
+**Stale-install window:**
+- Until you run `devflow init`, your installed `/resolve` and Triage agent have no tiers, so they behave as at `full`. If Triage is new and the installed reference is missing or unreadable, Triage applies no tier, keeps every verdict and reports `Tiers: not applied (reference unreadable)`.
+
+### Changed
+
+- **`/resolve` applies severity tiers at `standard` and `lean`** ([#484](https://github.com/dean0x/devflow/issues/484)).
+  - At `standard` and `lean`, Triage reads a new reference, `triage/severity-tiers.md`, once, after its normal checks. It runs a nine-step checklist in order, and the first step that matches decides.
+    The checklist only narrows. It never changes a FALSE_POSITIVE, BY_DESIGN or ESCALATED verdict, and it never moves a finding up.
+    A duplicate group takes the highest tier of its members. At `full`, Triage skips the new section, and the rest of the Triage agent text is byte-for-byte what it was.
+  - Triage judges a security finding by its label and also by the defect that it reads in the code, at every severity. A security control that fails open or is weakened, and a false security or safety claim, count as security at every severity.
+  - A prose-only fix goes to Code `issue-fix` with the Risk Tier `Standard, prose only`. No new agent is spawned. If Code leaves an item unedited for a logic change, `/resolve` records it as Fix Separately with the Reason `needs a logic change`.
+  - A DEFER item goes to Fix Separately with the Reason `severity tier: DEFER`. The manage-debt step puts the items of one run in one shared backlog issue.
+  - At every level, each issue cell in `resolution-summary.md` starts with its severity in brackets when the issue has one, for example `[HIGH]`. The `**Gate level**` header can carry a level note.
+  - The gate level hints, the effect text of `devflow gates`, `README.md`, `docs/cli-reference.md` and `docs/commands.md` name the tiers.
+  - Residual risk: the tiers rest on the Triage classification, and no live test checks it. The guards pin the text that the agents read. A finding that Triage ranks too low waits in the backlog issue until a later review brings it back.
+- **The level references state that a waiting phase starts at once** ([#600](https://github.com/dean0x/devflow/issues/600)).
+  - The Skipped line of `resolve-levels.md` and `implement-levels.md` now says: a phase that waits for a skipped phase starts at once.
+  - The `harden-scope` bullet of `implement-levels.md` no longer says `, and Phase 5 starts at once`, because the Skipped line now covers it.
+  - Behaviour is unchanged. Only the wording moved.
+- **Validate re-runs each failed test file alone** ([#477](https://github.com/dean0x/devflow/issues/477)).
+  - After a failed test run, Validate re-runs each failed test file alone, once, with verbose output.
+    The bound is 20 files.
+    Validate waits at most 120 seconds for each re-run, so the worst case is 40 minutes for each Validate run.
+    The 120 seconds is a bound on the wait, not on the re-run: the platform moves a foreground command that reaches its timeout to the background, where it runs to the end (see `docs/reference/platform-assumptions.md`).
+    A re-run that times out makes the file REAL.
+    A re-run starts only after the path passes a strict check, and it uses the full run's own test command with only that file added.
+  - Only the Phase 6 validation in `/implement` labels files, because only that run is given the branch base.
+    In every other run, including the re-validation after QA fixes, the re-runs give failure detail and every failure is REAL.
+  - A file is PASSED-ALONE only if all of these hold:
+    the path is checked and tracked, neither the branch nor the working tree changed the file, its failure was a timeout, a spawn error or a resource error,
+    the re-run used only that file with no name filter, it exited 0, and the tests that failed in the full run ran and passed.
+    Every other failure is REAL and goes to Fix.
+  - The cause is the failure that the test runner reports.
+    An assertion failure is REAL, also when its message names a timeout.
+    A child-process timeout that a test reports as a failed assertion is therefore REAL.
+    Issue [#332](https://github.com/dean0x/devflow/issues/332) tracks the repair of such tests.
+  - The gate and its `gate:validate` claim pass only when the PASSED-ALONE files explain every failure.
+    Only Validate's own report lists them, on one `Passed alone:` line.
+    The `/implement` summary and the PR body do not show that line.
+  - The re-run steps are in the agent reference `validate/passed-alone.md`.
+    After updating, run `devflow init`.
+- **`/implement` runs one Evaluate pass at `standard` and `lean`** ([#483](https://github.com/dean0x/devflow/issues/483)).
+  - At `standard` and `lean`, Phase 5 runs Evaluate once and spawns Fix at most once. It never spawns Evaluate again. `full` is unchanged.
+    If Fix returns COMPLETE, the report shows `MISALIGNED (fixed once, not re-checked)` and Phase 6 starts. Any other Fix report sends the misalignments to you for a decision.
+  - Evaluate keeps every criterion and plan step in scope, security, data handling, negative and docs ones included. It drops only docs, KB, CHANGELOG, comment or cosmetic items that no criterion or step names.
+    `/dynamic-build` and `/dynamic-plan` keep the full scope.
+  - Evaluate reads the level only from line 1 of its prompt. The level line goes first in every spawn prompt of the phase, right after a leading `OPERATION:` line.
+    The Fix agent no longer says that the command runs Evaluate again after each attempt.
+  - Expected effect: about 25-30% less spend on Evaluate and its fixes. This figure comes from the studied episodes and is not measured here.
+  - Residual risk: at `standard` and `lean`, nothing checks the one Fix round against the criteria again. Phase 6 Validate and Phase 7 QA cover behaviour. A non-behavioural criterion or the removal of unrequested code has no later check before the PR opens.
+  - Known limit: no CI test checks where the level line lands in a spawn prompt at run time.
+- **devflow ignores curation and memory files that git tracks, and says so at session start** ([#626](https://github.com/dean0x/devflow/issues/626)). When git tracks a file in a curation or memory data folder, or does not answer, devflow reads and writes no file in that folder. One fixed notice at session start says what to run to untrack the files. `devflow curation`, `devflow memory`, the HUD and `devflow uninstall` leave such a folder alone.
+  - On a paused project, `devflow curation --list`, `--show`, `--clear`, `--reset`, `--restore` and `--configure` (project scope) print the pause notice and exit 1. `devflow curation --status` and `devflow memory --status` print the notice and exit 0.
+  - The settings line that `resolve-settings.cjs` prints when it fails now reads `MEMORY=off CURATION=off`.
+  - A direct Skim delegation that passes no `CURATION` value now reports `(none)` under "Active Decisions". An absent value now reads as `off`.
+  - A checkout where a `.git` entry exists but git does not answer now pauses both features.
+
+### Fixed
+
+- **Sections marked private stay out of posted summaries** ([#567](https://github.com/dean0x/devflow/issues/567)).
+  - A review or resolution summary can hold a section whose heading starts with the word `Private`, in any letter case, for example `## Private notes`. A heading line inside a code block counts too.
+  - The PR comment leaves that section out, up to the next heading of the same or a higher level. This holds for the full report and for the stub.
+  - If no public text remains, devflow posts no comment and reports `**Status**: DEGRADED (no postable summary)`.
+  - The review and resolution writers now put text that must stay out of the PR comment in a final `## Private notes` section.
+  - The strip does not edit your local summary file.
+  - Run `devflow init` after you update.
+- **`/resolve` adds only triaged items to the tech debt backlog** ([#630](https://github.com/dean0x/devflow/issues/630)).
+  - Under GitHub, Linear and Jira, the `manage-debt` operation takes backlog items only from the `## Fix Separately` and `## Deferred to Tech Debt` sections of `resolution-summary.md`.
+  - If `resolution-summary.md` is missing, the operation returns `TRACEABILITY: DEGRADED (resolution summary missing)` and leaves the backlog unchanged.
+  - Run `devflow init` after you update.
+- **The evidence comment is edited in place** ([#504](https://github.com/dean0x/devflow/issues/504)).
+  - A PR keeps one evidence comment across pushes.
+    `update-pr-evidence` edits your own evidence comment in place for each new head.
+  - It posts a new comment only when you have none, or when an evidence comment from another user is newer.
+  - After the edit, it reads the comment back and prints `**Comment**: EDITED`.
+    If the text read back differs or cannot be read, it prints `TRACEABILITY: DEGRADED (comment read-back mismatch)`.
+  - A refused edit prints `DEGRADED (comment edit failed)`.
+    An own comment with no readable id prints `DEGRADED (comment id unreadable)`.
+    A failed edit never falls back to a new post.
+- **CI PASSING needs a passing GitHub Actions check on a mergeable PR** ([#618](https://github.com/dean0x/devflow/issues/618)).
+  - The CI wait and the merge-readiness report now read CI as passing only when at least one GitHub Actions check passed on the PR head, no check is pending or failing, and GitHub reports the PR mergeable.
+  - These cases now read "status unknown" instead of a pass or "no CI":
+    a PR with only external checks (`reason=no-workflow-check`), a PR with a merge conflict (`reason=merge-conflict`), and a repository with active workflows but no run on the head (`reason=no-workflow-check`).
+    A PR with a merge conflict reads `reason=merge-conflict` even when a check fails or is pending.
+    The gate does not report those checks until you resolve the conflict.
+    A merge state that GitHub does not report in time ends the wait with `reason=deadline`.
+    A PR that is merged or closed ends the wait at once with `reason=not-open`. It does not wait for a merge state.
+  - "No CI" needs a mergeable PR with no checks and no active workflow file under `.github/workflows/`. A repository with no workflow file still reads "no CI".
+    When a PR has no checks and the token cannot read Actions workflows, the wait ends with `reason=gh-failed`.
+  - The merge-readiness report reads CI for the PR head. It counts a pass or "no CI" only when the PR head it read is the head of the evidence.
+    It reads CI once and does not wait, so right after a push or a base move it can say "status unknown".
+  - If your CI is not GitHub Actions, or your workflow does not run on the PR (stacked PRs, `paths` filters, release-only workflows, fork PRs that wait for approval), check the CI result on the PR page before merging.
+    The gate then reports "CI status unknown — verify manually before merging".
+  - Known limit: a passing result shows that a GitHub Actions check passed, not that the test workflow ran by name.
+  - Run `devflow init` after you update.
+
+---
+
+## [3.8.0] - 2026-10-21
+
+### Upgrade notes — Curation rename
+
+The learning feature is now called curation ([#529](https://github.com/dean0x/devflow/issues/529)).
+This is a breaking change. It releases as a minor version (3.8.0).
+Devflow keeps no alias for the old command and the old init flags. The old switch keys stay readable, as the table shows. Read the steps that you must do by hand.
+
+**Superseding statement for 3.6.0:** The 3.6.0 notes say that `devflow learning`, `features.learning`,
+`.devflow/learning/` and the learning ops do not change. That statement is no longer true.
+This release changes all of them. The 3.6.0 text stays as released.
+
+**What you must do:**
+- Run `devflow init` after you update.
+- Replace `devflow learning` and the old init flags in your scripts.
+- Delete each backup folder after `devflow curation --status` shows 0 pending rows for it.
+  A backup made on re-upgrade can hold the only copy of entries that 3.7 wrote. Check them before you delete it.
+- Delete the leftover `.devflow/learning/` folder in each linked worktree whose main checkout has a `.devflow/` folder
+  and is not your home folder.
+  A worktree whose main checkout has no `.devflow/` folder, or is your home folder, keeps a live ledger.
+  That ledger moves like any project.
+- Run `devflow curation --enable` if the machine switch is off and you want it on.
+
+**Renamed names:**
+
+| Old name | New name |
+|----------|----------|
+| `devflow learning` | `devflow curation` |
+| `devflow init --learning` and `--no-learning` | `devflow init --curation` and `--no-curation` |
+| `features.learning` in `~/.devflow/manifest.json` | `features.curation` (the old key stays as a mirror) |
+| `features.learning` in a repository `project.json` or `config.json` | `features.curation` (the old key is still read) |
+| `.devflow/learning/` | `.devflow/curation/` |
+| `learning.json` (in the project folder and in `~/.devflow/`) | `curation.json` |
+| Settings line field `LEARNING=` | `CURATION=` |
+| Prompt markers `<!-- learning:on -->` and the build output `dist/learning-off/` | `<!-- curation:on -->` and `dist/curation-off/` |
+| HUD label `Learning:` | `Curation:` |
+| Session start headers `--- LEARNING MAINTENANCE ---` and `--- LEARNING PAUSED ---` | `--- CURATION MAINTENANCE ---` and `--- CURATION PAUSED ---` |
+| Hook files `learning-lock` and `lib/learning-store.cjs` | `curation-lock` and `lib/curation-store.cjs` (init removes the old files) |
+
+These names do not change: the `self-learning:` source stamp in rendered rows, the design-decision IDs,
+the `decisions-*.jsonl` files, the `apply-decisions` skill, the learn-conventions family and the
+`agents.learning.model` key (it stays an older name for the Curate agent model).
+
+**Breaking change:**
+- `devflow learning`, `devflow init --learning` and `devflow init --no-learning` now fail.
+  They give the unknown command or option error, and the exit code is 1.
+- Change every script, alias and note that uses an old name.
+
+**What the migration does:**
+- `devflow init` moves the learning data of each project that it finds, and of the project where you run it.
+  The move takes the ledger files, the queue and the project tuning file. Entry IDs do not change.
+  Devflow renders the index again at the new path.
+- Init also renames `~/.devflow/learning.json` to `curation.json`.
+  If both names exist, the new one wins, the old one stays, and init logs one line.
+- The session start hook makes the same move for the project of each session.
+  It also runs when the curation switch is off.
+- If a project already has both folders, one rule decides which folder stays.
+  If `.devflow/curation/` has a non-empty log, it wins and the old folder becomes the backup.
+  If not, the old ledger set moves in and the rest of the old folder becomes the backup.
+  Devflow never merges one ledger into the other.
+- After an upgrade, the first `devflow` command that loads the whole manifest
+  (for example `devflow init` or `devflow flags --status`) heals `~/.devflow/manifest.json`.
+  The file then carries both `features.curation` and `features.learning` with the same value.
+  Every later write keeps the two keys equal.
+  The `--status` commands of curation, memory, knowledge and gates write nothing.
+
+**Upgrade, downgrade and re-upgrade:**
+- Upgrade: run `devflow init` (a full init, not `--hud-only`). Until you do, the installed prompts and agents are still the old version.
+  `devflow init --hud-only` and a plugin-only update install the new hooks and settings script, but not the new prompts.
+  The old prompts do not accept the `CURATION=` field, so they use their fail-closed settings until you run a full `devflow init`.
+- Downgrade to 3.7: 3.7 does not read `.devflow/curation/`. It starts a new empty ledger in `.devflow/learning/`.
+  Your moved data stays in `.devflow/curation/`. The mirror key `features.learning` keeps a 3.8 opt-out in force.
+- Re-upgrade to 3.8: the next init or session start finds both folders and applies the rule above.
+  When the folder `.devflow/curation/` has a non-empty log, it wins.
+  The queue rows of the 3.7 folder merge into the winner. The entries that 3.7 wrote stay in the backup only.
+- The Curate model in the global tuning file: init renames `~/.devflow/learning.json` to `~/.devflow/curation.json`,
+  and 3.7 reads only the old name. After a downgrade, set the Curate model again with `devflow learning --configure`.
+  Choose the global scope. On re-upgrade, an existing `curation.json` wins and init logs one line.
+  To keep a value that you set on 3.7, delete `curation.json` first.
+
+**The machine switch:**
+- If `features.curation` and `features.learning` in the manifest disagree, the switch is off.
+  A reader never treats a disagreement as on.
+- To turn it on again, run `devflow curation --enable`. This writes both keys.
+- A 3.7 toggle writes only the old key. An opt-out made on 3.7 stays in force after you upgrade again.
+  If you ran no 3.7 `devflow init`, an enable made on 3.7 after a 3.8 disable stays off until you run `devflow curation --enable`.
+- A 3.7 `devflow init` removes the key `features.curation`. After that, only the old key carries the opt-out.
+  A 3.7 enable made after that init then takes effect when you upgrade again.
+- Between the package update and `devflow init`, `devflow curation --enable` and `--disable` write both keys
+  and move nothing. Only `--disable` drains the queue among these toggles. The commands `--restore`, `--clear`, `--reset`
+  and `--configure` (project scope) refuse until you run `devflow init`.
+
+**The backup:**
+- Where: `.devflow/learning.backup-<stamp>-<8 hex>` in the project, one folder for each move.
+  A move makes a backup only where a project had both folders.
+- No devflow command deletes a backup, except `devflow uninstall`.
+  Uninstall removes the backups of the project at the git root of your current directory, with that project's data, after you confirm.
+  `devflow curation --reset` and `devflow curation --clear` leave the backup in place.
+- A disable drains the queue files in the backups. `devflow curation --disable`, and `devflow init` with curation switched off,
+  remove the queue, claim, private and overflow files in each backup folder (at most 500 folders, and 200 files in each).
+  The ledger files, the swept files and the claim owner file stay in the backup.
+  Without this drain, a later `--enable` and init would merge those rows into the live queue.
+  The drain deletes nothing when a backup folder, or one of its queue files, is a symbolic link, and it says so.
+  The drain also deletes nothing when git tracks any entry under a data folder or a backup folder, or when a `.git` entry stands and git does not answer.
+  It then prints the notice that the git check shows (see Outcomes that need action).
+  If the backups cannot be listed for another reason, the drain still removes the queue files of the live and the old folder, and prints a warning that the backups were not drained.
+- `devflow curation --status` prints one `Backup:` line for each backup folder.
+  The line shows how many pending rows the backup still holds.
+  For the first 50 folders it prints one line each. One more line counts the folders from the 51st to the 500th and their pending rows.
+  If there are more than 500 backup folders, a last line counts the folders after the 500th. Status does not read them, and no init or drain reaches them.
+- Delete a backup folder only when `devflow curation --status` shows 0 pending rows for it.
+  Until then, a later init can still merge the rows.
+  A backup made on re-upgrade can hold the only copy of entries that 3.7 wrote. Check them before you delete it.
+- An init merges rows from at most 50 backup folders in one run. It passes over a folder that holds no pending rows,
+  so a later folder is reached when the earlier ones are done.
+
+**The queue cap:**
+- A merge fills a pending queue up to 100 lines and no further.
+  A capture trim keeps the newest 100 lines and starts only above 200 lines, so a merge never causes a trim.
+- Rows that do not fit wait in overflow files in the backup. A later init merges them as room appears.
+  Status counts them as pending rows, so the delete step waits for zero pending rows.
+- The move drops no row, and it never causes a trim.
+  A queue that holds more than 200 lines is still trimmed to its newest 100 lines when a capture arrives.
+  This is the rule from before 3.8.0, and the move does not change it.
+- `devflow init` drains the queue of a project where curation is off, as it did before 3.8.0.
+
+**Outcomes that need action:**
+- Busy: another run holds the move lock. Init prints `Ledger move skipped for <root>: a lock is held.`
+  A curation command prints `Another run is moving this project's curation data.`
+  Nothing is written. Wait a moment, then run the command again. A session start retries by itself.
+  When a queue claim holds the move, init prints `Ledger move skipped for <root>: a queue claim holds the move.`
+  A curation command prints `A Curate run holds this project's curation queue, and the move waits for it.`
+  The move runs after Curate finishes, which can take up to 15 minutes. Run the command again after that.
+- Refused: a symbolic link sits on the path, or a private, swept or overflow queue file sits directly in the old folder.
+  Nothing moves. Init prints `Ledger move refused for <root>`.
+  The HUD and `devflow curation --status` print `Curation: move refused, see the hook log`.
+  Remove the cause, then run `devflow init` or start a new session.
+- Skipped by the git check: git tracks any entry under `.devflow/learning/`, `.devflow/curation/` or a backup folder
+  (`.devflow/learning.backup-*`), or tracks an entry named `.devflow` ([#598](https://github.com/dean0x/devflow/issues/598)). The same outcome applies when a `.git` entry stands and git does not answer.
+  Nothing in the project changes. Init prints `Ledger move skipped for <root>` and a fixed notice that holds nothing from the repository.
+  The HUD prints `Curation: move skipped, git tracks files in the .devflow data folders`
+  or `Curation: move skipped, git did not answer`.
+  `devflow curation --status`, `--list` and `--show` print the whole notice. The HUD and these commands print the skip also when `.devflow/curation/` exists.
+  While the old folder is there, `--restore`, `--clear`, `--reset` and `--configure` (project scope) print the notice, change nothing and exit 1.
+  `--enable` and `--disable` print the notice as a warning, and their exit code does not change.
+  `--disable`, `--clear` and an init with curation off delete no queue file in these cases, and each prints the notice once.
+  When init has printed the notice in its `Ledger move skipped for <root>` line, its drain adds only `The curation queue was not drained.`
+  When git tracks files, the notice tells you to run `git ls-files .devflow`, and then `git rm --cached <file>`, in the checkout that holds the folders.
+  When git does not answer, the notice tells you to check that git runs in the project. The move runs again at the next session start or the next init.
+  A session start runs the check again in both cases.
+- Not yet moved: `devflow curation --status`, `--list`, `--show` and the HUD print
+  `Curation: run devflow init, or open Claude Code in this project after it`.
+  They do not read the old folder.
+- Failed: init prints `Ledger move failed for <root>` and copies nothing. The next init tries again.
+  A move that fails at session start shows the same `Curation: move refused, see the hook log` line as a refusal.
+  The hook log names the cause. The next session start tries again.
+- Skipped, no repository: git did not name the project's repository within one second, for example on a hung mount.
+  Init prints `Ledger move skipped for <root>: git did not answer in time.` and does not count the project as moved.
+  The other projects move. The next init tries again, and a session start in the project moves it too.
+
+**What stays behind:**
+- Reach: a project that neither `devflow init` nor a Claude Code session reaches keeps its old
+  `.devflow/learning/` folder untouched. It moves at its next session start.
+- Linked worktrees: if the main checkout has a `.devflow/` folder and is not your home folder,
+  the ledger of a linked worktree is the ledger of the main checkout.
+  Devflow does not move a `.devflow/learning/` folder that sits inside that worktree.
+  Delete that leftover folder by hand when you do not need it.
+  If the main checkout does not meet this condition, the `.devflow/learning/` folder of the worktree is a live ledger.
+  It moves like any project.
+- First session: the first session start in a project with an old folder runs the move.
+  This adds a short delay to that one start. Later starts add nothing.
+
+**Mixed-version teams:**
+- A 3.7 install reads only `features.learning` in a committed `.devflow/project.json`.
+  A 3.8 install reads both keys and narrows when either key is `false`.
+- Keep the old key in committed files, or set both keys, until every team member runs 3.8.
+
+### Upgrade notes — Lint pack
+
+**Stale-install window:**
+- Until you run `devflow init`, the installed `/implement` and Validate do not run the lint pack.
+
+### Upgrade notes — Base resolver
+
+The base resolver ([#495](https://github.com/dean0x/devflow/issues/495)) adds stops and a script call.
+Do the step below after you update.
+
+**What you must do:**
+- Run `devflow init` after you update. A full init installs `resolve-base.cjs` and the updated commands.
+
+**Stops:**
+- `/implement` stops when no usable base exists, for example in a shallow clone without the base history. `/code-review` and `/bug-analysis` stop in that case on a full-range run. The message names the cause and the fix: `git fetch --unshallow`, `git fetch origin <base>`, or a re-run (and `devflow init` if the re-run repeats the stop).
+- The same three commands stop on a base branch name outside the allowed set, or one that git refuses. The message states the set.
+- In `/code-review` multi-worktree mode, a rejected base blocks only that worktree.
+- `/code-review` and `/bug-analysis` stop when the branch name does not fit the allowed characters and length. The message states the allowed characters. In `/code-review` multi-worktree mode, this blocks only that worktree.
+- The Git agent's `validate-branch` returns BLOCKED in the same cases. `/resolve` takes its branch diff from it.
+- The Git agent's `ensure-pr-ready` stops only on a base name outside the allowed set, or one that git refuses. For any other base stop it prints `TRACEABILITY: DEGRADED (base {REASON}; fix: {fix})` and goes on.
+- `/dynamic-build`: a ticket whose setup reports no base commit stops with the `base-missing` escalation. Check the setup output, then re-run.
+
+**New resolver call:**
+- `ensure-pr-ready` calls `resolve-base.cjs` in `pr` mode with the base branch of the PR, or with the default branch when no PR applies. The call makes at most one fetch of the base branch.
+- `/implement` passes the base ref that it resolved in Phase 1, so a normal `/implement` run makes one fetch.
+- The `/dynamic-build` wave PR step runs `ensure-pr-ready` with no base ref, so that step makes this call.
+- The base resolver reads the base name from standard input (`--name-stdin`), so the name is not part of shell command text ([#561](https://github.com/dean0x/devflow/issues/561)).
+- The Git agent's `ensure-pr-ready` and `validate-branch` write the base name to a file. The step checks the status of both `gh` calls. It treats `gh` as failed when either status is not 0.
+- In `ensure-pr-ready` and `validate-branch`, a name file whose only content is an empty line counts as empty. The default-branch path then takes `main`, or else `master`.
+- `validate-branch` takes the default branch as the base when no PR applies: the branch has none, `gh` is missing or logged out, or the repository has no GitHub remote.
+
+**Stale-install window:**
+- Until you run `devflow init`, the installed commands and Git agent do not call the resolver.
+
+**Known limits:**
+- A fetch that stops at its 45-second bound can leave a `refs/remotes/origin/<name>.lock` file in the git directory. Later runs then report `fetch-failed` until you delete the file.
+- The fetch needs git 2.29 or newer. With an older git, every run reports `fetch-failed` and prints the base warning.
+- The fetch runs no askpass program. Where an askpass program is the only credential source, a remote that needs credentials gives `fetch-failed` on every run, with the base warning.
+
+### Upgrade notes — Review markers
+
+**What changes:**
+- Incremental review and analysis markers are stored under the git directory of each worktree; the first run after the update covers the full branch.
+
+### Upgrade notes — Review ranges
+
+**What changes:**
+- `/dynamic-build`: in single-ticket mode, the review covers the diff from the commit the ticket branch was forked from to HEAD. On a non-default start branch, that is the ticket's own commits.
+- `/dynamic-build`: the wave evidence step lists the changed files with a diff from the base ref of the wave PR. The base ref must be a commit ID of 40 or 64 lowercase hex digits, and the diff must exit 0. If not, the step is skipped, and the run summary holds `TRACEABILITY: DEGRADED (wave base unusable)`.
+- A Review agent with no patch file and no usable diff range returns `reviewed: false`. After one retry, the engine records a coverage gap, and the run verdict is never PASS.
+
+### Upgrade notes — Level readers
+
+**Stale-install window:**
+- If an installed `/implement` or `/resolve` is newer than its installed level reference, the reference stays unreadable until you run `devflow init`.
+
+### Upgrade notes — Polish by level
+
+**What you must do:**
+- The default level, `standard`, now skips Polish in `/implement` and `/resolve`. Run `devflow gates --set full` to keep Polish.
+- A quality rule that you keep at `~/.devflow/rules/quality.md` replaces the shipped one. At `standard` and `lean`, you then lose Polish and do not get the new bullet. Add the bullet to your copy. Or run `devflow rules unshadow quality`, which deletes your copy, and then run `devflow init`.
+
+**Stale-install window:**
+- Until you run `devflow init`, your install has no level row that skips Polish, so Polish still runs at every level. An install from 3.7.0 has no level reference at all. The installed quality rule also lacks its new bullet.
+
+### Upgrade notes — Harden by level
+
+**What you must do:**
+- At `lean`, `/implement` now skips Harden on a docs-only diff. Run `devflow gates --set standard` or `--set full` to keep Harden on every diff.
+
+**Stale-install window:**
+- Until you run `devflow init`, your installed level reference has no Harden row, so Harden runs at every level.
+
+### Added
+
+- **`devflow init` asks for the gate level** ([#543](https://github.com/dean0x/devflow/issues/543), [#507](https://github.com/dean0x/devflow/issues/507)).
+  - `devflow gates --set <level>` and `devflow init` set the machine gate level, so a user who runs `init` learns that the level exists.
+    An interactive `init` asks for it: `full`, `standard` or `lean`, each with a one-line effect.
+    On a first install the prompt starts on `standard`.
+    On a re-init it shows the current value and starts on it, so Enter keeps a valid level.
+    A malformed or `null` stored value starts the prompt on `full`, and if you accept it, init writes `full` in its place. The machine level that applies does not change.
+  - `devflow init --gate-level <full|standard|lean>` sets the machine level with no prompt, in an interactive or a non-interactive run.
+    A bad value, or no value, exits 1 before `init` writes anything and names the valid levels. The flag cannot be combined with `--hud-only`.
+    `devflow init --recommended` and a non-interactive `init` show no prompt and keep the stored value.
+  - The Recommended settings note has a `Gate level:` row.
+    The summary at the end of `init` shows the level that is set, and adds `(was X)` when the run changes the machine level that applies.
+    `init` writes the same machine default as `devflow gates --set`, and a personal `gateLevel` in a repository's `.devflow/config.json` still wins there.
+  - If `~/.devflow/manifest.json` is valid JSON with a `features` object that devflow rejects (a field is missing or mistyped, or a byte-order mark leads), a promptless `init` and `init --hud-only` keep the gate level stored in it, as it is stored, and warn that they kept the level while they replaced the file.
+    When the prompt runs, your answer is the level. If you accept a malformed or `null` value, init writes `full`.
+  - If the manifest is corrupt, is not JSON, has no `features` object, or is over 1 MiB and also one that devflow rejects, `init` cannot read the level.
+    The prompt shows `Current setting: unknown` and starts on `standard`.
+    A promptless `init` or `init --hud-only` records no level and warns that `standard` applies and that `devflow gates --set <level>` sets it again.
+    `devflow gates --status` words its manifest warning for each case.
+  - `devflow init --reset` removes the stored level, and over a rejected manifest the summary names the level it removed, as in `(was full)`.
+    A bare `devflow gates --set` names the levels in its error, as `devflow init --gate-level` does.
+- **A lint pack template, and a lean lint pack in Validate** ([#475](https://github.com/dean0x/devflow/issues/475)).
+  - The package ships a template in `templates/lint-pack/`: a script, an example config and a README.
+    You copy it into your repository and own the copy.
+    devflow does not install, update or run the template itself.
+  - At `lean`, Phase 6 of `/implement` has Validate run your root `lint-pack` script last, after the build, typecheck, lint and test commands pass.
+    Validate finds it as a `package.json` script, else as a `Makefile` target.
+    The script reads the lines the branch changed.
+    It finds a removed flag that a doc still names, a plan ID or a tombstone phrase in new text, and an oversized function (through your own linter).
+    A match fails validation and reaches Fix as a file and line reference.
+  - Fix does not edit the lint pack, its config, its build-file entry or any `.gitattributes` to clear a match.
+    Fix does not silence the linter to clear a match, with a disable comment or a linter-config change.
+    It reports the match under Blockers.
+    To clear a match that you judge false, add an allow glob to `.lint-pack.conf`, commit it, and ask `/implement` to re-validate.
+  - A pack error does not change the validation result.
+    A git older than 2.30, a config that the script cannot read, a linter that did not run and a run that a timeout stops are pack errors, never a clean run.
+    A pack error reads `UNVERIFIED` in the `/implement` final report and in the Testing part of the PR body.
+    The pack also prints a `pack-changed` line for a changed build-file line in the compared range that names `lint-pack` or `BASE`, a `pack-dirty` line for an uncommitted change to a pack file, and the base it compared.
+    Known limit: the pack prints the base it compared (`base <sha>`), but Validate does not check that base yet, and issue [#537](https://github.com/dean0x/devflow/issues/537) adds that check.
+    If the project has no `lint-pack` script or target, Validate prints one "not configured" line.
+  - The re-validation that you ask `/implement` for runs the pack.
+    The re-validation after QA fixes, `/resolve`, `/self-review`, `/release` and `/dynamic-build` do not run it, and no level below `lean` runs it.
+
+### Changed
+
+- **`/implement` skips Harden at `lean` on a docs-only diff** ([#482](https://github.com/dean0x/devflow/issues/482)). At `lean`, `/implement` skips Phase 4 Harden when the diff is docs-only. The decision reads path names only. It reads no diff content and runs no detection script. Harden is skipped only when all of these hold: the compliance lens is exactly `off`; the branch diff list is not empty; no Code report names a deleted, renamed or moved path; and every changed path is the root `README.md`, the root `CHANGELOG.md` or a `.md` file under the root `docs/`. A path on that list has no segment that starts with a dot, no double quote in its name and no file name that agents load as instructions, in any letter case. No loaded instruction, rules or imported file names the path. A tests-only diff runs Harden. When the decision is unclear, Harden runs. The run report says `Harden: ran` or `Harden: SKIPPED (docs-only diff)` at `lean` only. `full` and `standard` do not change. When Harden runs, it reads the whole branch diff. `/code-review` security runs at every level. The README, the CLI reference and the command reference state the rule. Known limits at `lean` on a docs-only diff: stub and wiring detection does not run; the pitfall check of public text in README and CHANGELOG does not run; a path that only a not-yet-loaded instruction file, such as a nested one, names is not seen; and Harden does not review a delete or a rename that no Code report names ([#571](https://github.com/dean0x/devflow/issues/571)). The docs-only check reads path names. It does not look at symlinks, file-type changes, or docs files that a site generator compiles. Run `devflow gates --set standard` or `--set full` to keep Harden on every diff.
+- **`/implement` and `/resolve` skip Polish at `standard` and `lean`** ([#481](https://github.com/dean0x/devflow/issues/481)).
+  - At `standard` and `lean`, `/implement` skips Phase 3 Polish, and `/resolve` skips Phase 6 Polish in each worktree at that level.
+    At `full`, both spawn Polish.
+    `/self-review`, `/debug` and `/dynamic-build` keep Polish at every level and read no level.
+    Harden still reads the whole branch diff, and Validate does not depend on Polish.
+  - The quality rule has one bullet that holds a subset of Polish's cleanup list: leftover debug statements, unused imports, unnecessary variables used once right after assignment, nested ternaries, checks the types enforce and catches around code that cannot throw.
+    The bullet cuts debug statements everywhere, but it keeps checks and catches at a trust boundary or a fail-closed path.
+    The Code agent applies it while it writes.
+    At `full` and `standard`, `/code-review` can report these items.
+    `devflow gates`, the `devflow init` level hints, the README, `docs/cli-reference.md` and `docs/commands.md` state the effect.
+  - Accepted risk: at `standard` and `lean`, no `/implement` agent grades naming and consistency, and Harden reports both as `SKIP (Polish agent)`.
+    No rule holds two other Polish items: language-behavior tests and verbose names.
+    Harden's test pillar partly covers language-behavior tests.
+  - At `standard` and `lean`, `/resolve` skips Polish and never spawns Harden, so debug statements in its fixes that hold no secret or token get no later pass beyond the quality rule and the review.
+    At `lean`, `/code-review` does not report the cleanup items.
+    Ticket [#568](https://github.com/dean0x/devflow/issues/568) tracks the Harden wording.
+    Run `devflow gates --set full` to keep Polish.
+- **`/implement` and `/resolve` read the gate level** ([#480](https://github.com/dean0x/devflow/issues/480)).
+  - At `standard` and `lean`, each command reads its level reference one time for each run. At `full`, it reads no reference.
+    `/implement` reads it at the start of Phase 3.
+    `/resolve` reads it in Step 0d when any worktree is at `standard` or `lean`.
+    The references hold the phase rows, and the [#481](https://github.com/dean0x/devflow/issues/481) entry lists the rows that this release adds.
+  - The `/implement` report and the `/resolve` display name the level at every level.
+    `/resolve` also names it in `resolution-summary.md`.
+    `devflow gates` says that `/implement` and `/resolve` read the level.
+  - If a reference cannot be read, the command says `level reference unreadable: no level rows applied`.
+    It applies no row and keeps the level, so at `lean` the lint pack still runs.
+  - No level removes Validate, the CI gate, the evidence claims, the Verification Gate or the compliance directive.
+    No level changes the Triage security gate or the ESCALATED route.
+- **Code, Fix and Refactor check the staged diff for secrets or tokens in logs or debug output before each commit** ([#584](https://github.com/dean0x/devflow/issues/584)).
+  - Each of these agents checks the staged diff of every file it commits.
+    The check runs at every level, wherever `/resolve`, `/implement`, `/debug`, `/dynamic-build` (and dynamic workflows that spawn them) or ambient mode spawn these agents.
+    Run `devflow init` to install the updated agents.
+- **`/implement`, `/code-review`, `/bug-analysis` and `/resolve` check branch names against an allowed set** ([#495](https://github.com/dean0x/devflow/issues/495)).
+  - A base branch name outside the allowed set, or one that git refuses, stops the run. The message states the set.
+    In `/code-review` multi-worktree mode, a rejected base blocks only that worktree.
+  - An incremental `/code-review` or `/bug-analysis` run takes the full range when it cannot use the stored review head.
+    A failed patch write in `/code-review` stops the run.
+
+### Fixed
+
+- **`/implement`, `/code-review`, `/bug-analysis` and `/resolve` use a fresh base for branch diffs** ([#495](https://github.com/dean0x/devflow/issues/495)).
+  - A new script, `resolve-base.cjs`, makes at most one fetch of the base branch, picks the base by one stated rule and prints one status line.
+    The fetch updates only the remote-tracking ref of the base branch, and credential prompts are off for it.
+    The branch diff starts at the fork point of that base and `HEAD`.
+  - The fetch stops after 45 seconds, each local git call stops after 30 seconds, and one run has a budget of 100 seconds.
+    A local git call that gives no answer reports `resolver-unavailable`.
+    A normal `/implement` run fetches the base branch once, and a re-validation that you ask for can add one more fetch.
+  - When the fetch fails or times out, `/implement`, `/code-review` and `/bug-analysis` use the best base they have and print a warning.
+    Known limit: `/resolve` uses that base without a warning.
+  - When no usable base exists, for example in a shallow clone without the base history, `/implement` stops, and `/code-review` and `/bug-analysis` stop on a full-range run.
+    Each names the cause and a fix.
+    `/resolve` takes its branch diff from the Git agent's `validate-branch`, which returns BLOCKED in that case.
+  - Run `devflow init` after you update, to install the script and the updated commands.
+- **SessionStart loads the current working memory once** ([#591](https://github.com/dean0x/devflow/issues/591)).
+  - It does not load pre-compaction memory snapshots, also when a snapshot is newer or the current memory is missing.
+  - SessionStart does not delete or move the existing `backup.json` file. The next PreCompact writes it again with Git state only.
+
+---
+
 ## [3.7.0] - 2026-10-16
 
 ### Upgrade notes — Gate level
@@ -1751,7 +2227,9 @@ devflow init
 
 ---
 
-[Unreleased]: https://github.com/dean0x/devflow/compare/v3.7.0...HEAD
+[Unreleased]: https://github.com/dean0x/devflow/compare/v3.8.0...HEAD
+[3.9.0]: https://github.com/dean0x/devflow/compare/v3.8.0...v3.9.0
+[3.8.0]: https://github.com/dean0x/devflow/compare/v3.7.0...v3.8.0
 [3.7.0]: https://github.com/dean0x/devflow/compare/v3.6.0...v3.7.0
 [3.6.0]: https://github.com/dean0x/devflow/compare/v3.5.0...v3.6.0
 [3.5.0]: https://github.com/dean0x/devflow/compare/v3.4.0...v3.5.0