devflow-kit 3.5.0 → 3.7.0

package/CHANGELOG.md

@@ -5,6 +5,181 @@ 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.7.0] - 2026-10-16
+
+### Upgrade notes — Gate level
+
+The settings line has a new last field for the gate level ([#472](https://github.com/dean0x/devflow/issues/472)).
+Do the step below after you update.
+
+**What you must do:**
+- Run `devflow init` after you update. A full init installs the commands that accept the new settings line.
+- After `devflow init`, a user with no level gets `standard` in `/code-review`: no TypeScript focus, and no Dependencies focus on a code diff that changes no dependency manifest. Run `devflow gates --set full` to keep today's set.
+- A user with no level also gets the lean `/plan`: fewer agents, while the security gap analysis and the design review still run. Run `devflow gates --set full` to keep the full `/plan`.
+
+**Stale-install window:**
+- The settings line now ends with `GATE_LEVEL=<full|standard|lean>`. An installed command from an
+  older version accepts only the old fields, so it does not accept the longer line.
+- `devflow init --hud-only` and a plugin-only update refresh the resolver script. They do not
+  refresh the installed prompts.
+- Until you run a full `devflow init`, every installed command uses its fail-closed settings value.
+- Until you run `devflow init`, the installed `/code-review` and `/plan` ignore the level.
+
+**Known limits:**
+- A corrupt manifest, or one over 1 MiB, reads as the `standard` level. `devflow gates --status`
+  warns that `devflow init` will replace the file.
+- `devflow init` still overwrites a corrupt or rejected manifest. The stored level is lost with it.
+- Two commands that write the manifest at the same moment can lose one update.
+- There is no team floor. A repository that declares compliance can run a lower personal level.
+  `/code-review` and `/plan` read the level, so a personal `lean` level narrows the review and the
+  planning run even where compliance is declared. The Compliance focus still runs on its trigger,
+  and in `/plan` the security gap focus and the design review run at every level.
+  Issue [#488](https://github.com/dean0x/devflow/issues/488) (the compliance lens as a floor on
+  the level) is open.
+
+### Upgrade notes — Working memory
+
+The memory worker's write is limited to its staged file. Read the items below after you update.
+
+**What you must do:**
+- Update Claude Code to 2.1.269 or newer. On an older version, working memory does not update and Claude Code shows no message. The worker log has one line that says why.
+- If a worker `env` value lives only in your project or local Claude Code settings, move it to your user settings file. The worker loads only the user settings.
+
+**Your own settings:**
+- Allow rules in your own Claude Code settings also apply to the worker's run. A user-level Edit allow rule that covers other paths covers the worker too.
+
+**Known limits:**
+- A project path that contains any of `* ? [ ] \ " { }` or a control character gets no working-memory updates. The permission rule carries the path without quoting. The worker skips the project, logs the reason and shows one message at session start. Parentheses and spaces in the path are carried as they are.
+
+### Added
+
+- **A gate level on the settings line, and the `devflow gates` command** ([#472](https://github.com/dean0x/devflow/issues/472)). The settings line ends with `GATE_LEVEL=<full|standard|lean>`. The level comes from a personal `gateLevel` key in `.devflow/config.json`, then from the machine default `features.gateLevel` in `~/.devflow/manifest.json`, then from `standard`. The personal key may raise or lower the level. It is not a narrow-only switch, and a later change can make it narrow-only. A `gateLevel` in `project.json` is ignored, and no command writes the personal key. A malformed value reads as `full`. `devflow gates --set <level>` writes the machine default and nothing else. `devflow gates --status` shows the level in effect, the layer that decided it and the machine default. `/code-review` reads the level ([#474](https://github.com/dean0x/devflow/issues/474)) and so does `/plan` ([#473](https://github.com/dean0x/devflow/issues/473)); [#480](https://github.com/dean0x/devflow/issues/480) adds more readers.
+- **`devflow init --hud-only` prints a line when the installed prompts come from another devflow version** ([#472](https://github.com/dean0x/devflow/issues/472)). It tells you to run `devflow init`.
+- **A message at session start when working memory stops for a cause you can fix.** If the worker cannot write its staged file at the project path (for example, a path with a character the permission rule cannot carry), or Claude Code refuses the worker's write in two runs with no successful update between them, the next session start shows one message that points to the log. Each cause is shown once.
+
+### Changed
+
+- **`/code-review` picks its focus set by gate level** ([#474](https://github.com/dean0x/devflow/issues/474)). `full` runs every focus, as before. `standard`, the default, drops TypeScript, and drops Dependencies on a code diff that changes no dependency manifest (a lockfile alone does not count). `lean` runs Security, Testing and Reliability on a code diff. The Compliance focus keeps its own trigger at every level. A docs-only, tests-only or lockfile-only diff keeps its reduced set, and at `lean` a tests-only diff drops Consistency. A mixed non-code diff runs the union of its classes' sets. Security runs at every level and in every class. `/code-review` reads a new level reference only at `standard` or `lean`. If it cannot read the reference, it says so and runs the full sets. The review summary now shows the gate level and the focuses, and a review with no security report gives CHANGES REQUESTED.
+- **`/plan` runs a lean shape at `standard` and `lean`** ([#473](https://github.com/dean0x/devflow/issues/473)). `full` runs the phases as before. `standard`, the default, and `lean` run one Explore round of two agents (three for several issues), or none when a `/research` report from the same conversation covers the scope; no Synthesize step; two gap-analysis agents, one for security and one for completeness, architecture and performance (plus consistency and dependencies for several issues); one Plan agent; and the design review. The security gap agent and the design review run at every level, the Compliance agent keeps its own trigger, and Gates 0, 1 and 2 run at every level. Every agent spawn in `/plan` names its agent type; the planning spawns use Claude Code's built-in `Plan` agent. If `/plan` cannot read its level reference, it says so and runs the full shape. The run report names the gate level. Run `devflow gates --set full` to keep the full shape.
+- **`/implement` splits long plans into sequential Code phases; a run with no plan stays single** ([#452](https://github.com/dean0x/devflow/issues/452)).
+- **Code agents read large files once, by range, and cap printed output** ([#452](https://github.com/dean0x/devflow/issues/452)).
+- **Polish, Harden, Evaluate and Test get the full branch diff as `FILES_CHANGED`** ([#452](https://github.com/dean0x/devflow/issues/452)).
+- **`/implement` stops when the base branch name has a character outside ASCII letters, digits and `._/+@,#-`, or is longer than 200** ([#452](https://github.com/dean0x/devflow/issues/452)). The check also covers the re-validation path. Git accepts some refused names, such as `café`. For them, `/implement` stops and tells the user which characters are allowed.
+- **The token audit counts files written through Bash** ([#442](https://github.com/dean0x/devflow/issues/442)).
+- **The memory worker's write is limited to its staged file.** The `claude -p` run loads only your own Claude Code settings plus two permission rules, an allow rule for `.devflow/memory/WORKING-MEMORY.md.new` and a deny rule for every path under it, and a permission mode that refuses every call that no allow rule covers. Allow rules in your own Claude Code settings also apply to the run, so a user-level Edit allow rule that covers other paths covers the worker too. A folder or a link at the staged path is removed by one guarded delete of exactly that path; when it cannot be removed, the run fails and removes nothing. The worker ignores a project's or a local Claude Code settings file.
+- **Working memory needs Claude Code 2.1.269 or newer.** `devflow init` states the version at its working-memory step. On an older Claude Code the worker does not run, keeps the queue and writes one log line that says why, so working memory does not update until you update Claude Code.
+- **The memory log gets one `Run:` line for each worker run.** `.background-memory-update.log` under `~/.devflow/logs/`, in the folder for the session that ran the worker (`<session-directory-slug>`), ends every run with `Run: cli=<version|unknown> argv=<lean|legacy|none> result=<updated|conflict|failed|skip|below-floor> denials=<count|unknown|n/a> removed=<none|dir|link>`. `cli=unknown` means the worker read no version, `denials=unknown` means the result reported no count, and `denials=n/a` means no run started. A below-floor line adds `floor=<version>`. The line holds keywords and digits only, never turn or prompt text.
+- **A project inside a `.git` folder gets no working-memory update.** The worker skips it, logs the reason and shows the path message once at session start. A checkout under `.claude/worktrees` is updated like any other checkout.
+- **PR links and `/dynamic-build` ticket branches follow stricter rules** ([#486](https://github.com/dean0x/devflow/issues/486)). `/implement` prints `TRACEABILITY: DEGRADED (ambiguous issue reference)` when it has an issue number and no link line. `/code-review` and `/bug-analysis` PRs no longer get a closing line from the branch name. A PR body has no `## Related Issues` heading when neither an issue number nor a link line is given. In a `/dynamic-build` wave, the ticket branch must be a local branch name that passes the allowlist. A name with a leading `#` or `-`, a revision name such as `HEAD`, a tag and a SHA are all refused, and the ticket is quarantined. The wave aborts the merge only when the merge began. On Jira and Linear, the PR link line always uses the default reference form (`Refs {KEY}-{n}`). A custom `## Reference Rendering` section no longer shapes that line. It still shapes the release Shipped Issues section. Follow-up [#511](https://github.com/dean0x/devflow/issues/511) tracks applying it to the PR link line.
+
+### Fixed
+
+- **Prompts resolve the Claude config directory with the same rule as the installer** ([#517](https://github.com/dean0x/devflow/pull/517)). `CLAUDE_CONFIG_DIR` applies when it is an absolute path, else `~/.claude`.
+- **A tracked `.devflow/config.json` no longer applies as personal config** ([#489](https://github.com/dean0x/devflow/pull/489)). devflow ignores it and shows a warning.
+- **`/dynamic-build` wave merges are safer, and a supplied PR link line is used as given** ([#486](https://github.com/dean0x/devflow/issues/486)). A wave merge uses `git merge --no-ff` and records the pre-merge SHA. The ticket branch name is checked before the merge, and a refused name quarantines that ticket. The wave halts when the merge or base SHA is not valid. A ticket whose branch adds no commit stops the wave before the post-merge build, and no wave PR opens. A merge whose post-merge build fails is undone by a reset to the recorded SHA. The run summary names why the wave halted. A PR gets no closing reference from a bare number or the branch name.
+- **Model discovery waits up to 6 s for the routing runtime** ([#519](https://github.com/dean0x/devflow/pull/519)). The wait was 2 s. On a loaded machine, the first start of node with the routing runtime can take more than 2 s. The agents TUI then reported an installed runtime as unknown. `devflow proxy --enable` then did not refresh the model cache. A runtime that does not answer within 6 s still falls back to the stale cache.
+- **The memory worker keeps the queue when it finds neither jq nor node** ([#523](https://github.com/dean0x/devflow/issues/523)). The hooks that start the worker already stop without a parser. A worker that ran with a different PATH deleted the queued turns. Now the worker stops before it reads the queue, and the queue stays for the next run. A parser that exits with an error also leaves the queue and the batch in place, and a queue that cannot be added to a leftover batch stays in its file.
+- **A malformed queue line no longer stops the worker from reading the other lines** ([#528](https://github.com/dean0x/devflow/issues/528)). With jq, the worker read the queue as one stream, so one malformed line stopped the parse. The valid turns after it were lost, or the whole batch was deleted. Now the worker reads each line alone, skips only the malformed line, and logs how many lines in the read window it skipped. A row cut off before its line break runs into the next row, so those two rows are one malformed line. Both parsers read a line as a turn only when its role is user, assistant or qa, so jq and node log the same skip count. A batch with no readable line is still removed.
+
+---
+
+## [3.6.0] - 2026-10-14
+
+### Upgrade notes — Agent rename (6 agents)
+
+This change releases as a minor version (3.6.0). It renames six agents, and a prompt that names
+an old agent does not work. Read the steps below that you must do by hand.
+
+Six agents have new names that state their job ([#466](https://github.com/dean0x/devflow/issues/466)).
+The agent `code` keeps its name. The learning feature keeps its names too: `devflow learning`,
+`features.learning`, `.devflow/learning/` and the learning ops do not change.
+
+| Old slug     | New slug   | Old `name:`  | New `name:` |
+|--------------|------------|--------------|-------------|
+| `code-fix`   | `fix`      | `Code-fix`   | `Fix`       |
+| `code-edit`  | `refactor` | `Code-edit`  | `Refactor`  |
+| `scrutinize` | `harden`   | `Scrutinize` | `Harden`    |
+| `simplify`   | `polish`   | `Simplify`   | `Polish`    |
+| `diagnose`   | `debug`    | `Diagnose`   | `Debug`     |
+| `learning`   | `curate`   | `Learning`   | `Curate`    |
+
+The `/debug` command does not change. `Debug` is the agent that `/bug-analysis` spawns.
+Use `Refactor` for a given mechanical change, such as "rename X to Y everywhere".
+Use `Polish` for a judgment pass that makes code cleaner and keeps its behaviour.
+
+**What devflow migrates automatically:**
+- Keys in `~/.devflow/agent-models.json`. The one-time migration `canonicalise-agent-keys-v2`
+  runs on the first `devflow init` after this upgrade. Each read of the file also maps an old key
+  to its new slug. If the old key and the new key both exist, the new key wins.
+  `devflow agents --set <old slug>` writes the new slug and tells you.
+- The session-start hook reads `agents.curate.model`, then an older `agents.learning.model`, and
+  spawns `Curate`. `devflow init` updates the hook.
+- `token-audit` counts old transcripts under the new names, so a past `Code-fix` spawn counts as
+  `Fix`. Its JSON report key `codeFixByOperation` is now `fixByOperation`.
+
+**What `devflow init` and `devflow uninstall` do to agent files:**
+- A full `devflow init` removes the six old files from `~/.claude/agents/devflow/` and installs
+  the new ones. It removes every other file in that folder that devflow does not own.
+- A partial `devflow init --plugin=<name>` and a selective `devflow uninstall --plugin=<name>`
+  run the orphan sweep. The sweep deletes every `.md` file in `~/.claude/agents/devflow/` whose
+  name is not a devflow agent. This includes the six old files.
+- Do not keep your own agent files in `~/.claude/agents/devflow/`, because devflow deletes them.
+  A file of your own directly in `~/.claude/agents/` is never touched. This is also true when it
+  has the name of an old devflow agent, for example `~/.claude/agents/simplify.md`.
+
+**Partial install and partial uninstall on a 3.5.0 install:**
+- The commands of the plugins that stay installed name the old agents until something rewrites
+  them. The sweep removes the old agent files, and the new agent files are not on disk until
+  something writes them. For this reason both commands now repair the plugins that stay installed.
+- `devflow init --plugin=<name>`: the sweep can delete an old agent file. If it does, the install
+  writes the commands and the agents of every plugin in `~/.devflow/manifest.json`. It does not
+  write only the plugin you name. If the sweep deletes nothing, the install writes only the plugin
+  you name, as before.
+- `devflow uninstall --plugin=<name>`: the sweep can delete an old agent file. If it does, the
+  uninstall writes the current commands and agents of the plugins that stay installed. It also
+  prints a note. It does not update the hooks, the scripts or `settings.json`. Run a full
+  `devflow init` to update them. Until you do, the hook from 3.5.0 can name an agent that no
+  longer exists.
+- If there is no readable `~/.devflow/manifest.json`, or the manifest lists no plugin that Devflow
+  knows, the uninstall writes nothing. It prints a warning that tells you to run `devflow init`.
+- If the install is a legacy project-local install (`<repo>/.claude`), the uninstall writes
+  nothing. It prints a warning. The warning tells you to remove that install in full with
+  `devflow uninstall --scope local`.
+- If the write fails, the rewrite stops at the first file that fails. The files that it wrote
+  before the failure stay written. The uninstall still finishes and prints a warning that tells
+  you to run `devflow init`.
+
+**What you must migrate by hand:**
+- Your own prompts, commands, agents or `CLAUDE.md` that name an old agent, for example
+  `subagent_type: "Simplify"` or `subagent_type: "Code-edit"`. Devflow cannot edit files it does
+  not own. Change them to the new name, for example `subagent_type: "Polish"`.
+- Open Claude Code sessions. Restart each one after `devflow init`. An open session loaded its
+  agent types when it started, so it does not know `Fix`, `Refactor`, `Harden`, `Polish`, `Debug`
+  or `Curate`. `devflow init` also removes the files of the old agents. The orchestrator charter
+  of an open session still names `Code-edit`.
+
+**Downgrade warning:** if you downgrade to 3.5.0, it does not know the new keys. Your per-agent
+model overrides that you saved as `fix`, `refactor`, `harden`, `polish`, `debug` or `curate` do
+not apply, and 3.5.0 gives no message. Check them with `devflow agents --list`.
+
+### Added
+
+- **The HUD shows your Codex usage limits.** A new `codexQuota` segment sits on line 2 next to the Claude quota, for example `Codex 5h ███░░░░░ 40% (1h 2m) · 7d █░░░░░░░ 12% (3d 4h)`. It reads the newest rate-limit record that Codex writes to `~/.codex/sessions`, so it opens no credential file and makes no network call. A window is identified by its length, so a weekly-only plan and a 5h + 7d plan both label correctly. A window past its reset time shows 0%, and a red `limited` marker shows while Codex reports a reached limit. The segment is hidden when there is no recent Codex session, so users without Codex see no change.
+
+### Changed
+
+- **`/plan` bounds Revise at 2 rounds** ([#455](https://github.com/dean0x/devflow/issues/455)). Each revision spawns five agents (Plan ×3, Synthesize, Design). After the second revision, Gate 2 offers Accept, Cancel or "Restart /plan with these constraints". The first-pass fan-out does not change.
+- **The PR evidence refresh and the merge-readiness check run as a script, not as a Git agent spawn** ([#455](https://github.com/dean0x/devflow/issues/455)). `/implement`, `/resolve` and `/dynamic-build` run `verify-evidence.cjs publish` from the main session, and `/resolve` runs `verify-evidence.cjs readiness`. The `update-pr-evidence` and `check-merge-readiness` operations stay defined and run the same script. The refresh never blocks, and the readiness check only reports.
+- **Agents get a scoped slice of the decisions index** ([#454](https://github.com/dean0x/devflow/issues/454)). On a direct delegation the main session passes only the index lines that match the agent's task, a `(slice: N of M entries — full index: <path>)` marker and the index footer. Sibling agents over one diff share one slice. When the main session is not sure, it includes the entry.
+- **Command bodies are smaller and have size ceilings** ([#456](https://github.com/dean0x/devflow/issues/456)). Rare `/implement` branches (the ticket-link ask, the missing-test-plan ask, the evidence exception and the re-validation path) move to reference files that the command reads by explicit path. `/implement`, `/resolve`, `/plan` and `/code-review` are shorter. A test holds a size ceiling for each of the 14 compiled commands, learning-on and learning-off.
+
+### Fixed
+
+- **`/release` no longer folds the `Exempt (not attested)` line into the last traceability bullet.** The `## Traceability exceptions` block put that line directly under the last `-` bullet, so Markdown rendered it inside that bullet (seen in the v3.5.0 release notes). The template now holds a blank line between them, and the command states the rule so a composed block always carries it.
+- **The HUD status line exits promptly.** The 2-second overall timeout timer is now cleared when a render finishes, so each status-line render takes about 0.3 s instead of about 2.1 s. A render that times out still prints nothing.
+
+---
+
 ## [3.5.0] - 2026-10-12
 
 ### Added
@@ -1576,7 +1751,9 @@ devflow init
 
 ---
 
-[Unreleased]: https://github.com/dean0x/devflow/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/dean0x/devflow/compare/v3.7.0...HEAD
+[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
 [3.4.0]: https://github.com/dean0x/devflow/compare/v3.3.0...v3.4.0
 [3.3.0]: https://github.com/dean0x/devflow/compare/v3.2.0...v3.3.0

package/README.md

@@ -30,7 +30,7 @@ you: /implement (hand it the plan)
 
   Git                    branch feat/42-rate-limit-upload
   Code                   implements the plan — your learned decisions, pitfalls, and feature knowledge preloaded
-  Simplify · Scrutinize  cleanup pass, then 9-pillar quality gate
+  Polish · Harden        cleanup pass, then 9-pillar quality gate
   Evaluate               implementation matches the original request ✓
   Validate               build ✓ typecheck ✓ lint ✓ tests ✓
   Test                   5/5 QA scenarios pass
@@ -56,7 +56,7 @@ This is the **orchestrated flow** — you stay in the loop between every step. W
 
 **A staffed agent roster.** 20 specialized agents with explicit model assignments — Opus for analysis, Sonnet for execution, Haiku for I/O. Reassign any agent's model with `devflow agents`, including GPT models through external model routing (`devflow proxy`).
 
-**Up to 20 parallel Review agents.** Security, architecture, performance, complexity, consistency, regression, testing, and more. Each produces findings with severity, confidence scoring, and concrete fixes. Conditional Review agents activate when relevant (TypeScript for `.ts` files, database for schema changes, compliance when regulated surface detected in the diff). Every finding gets validated and resolved automatically.
+**Up to 20 parallel Review agents.** Security, architecture, performance, complexity, consistency, regression, testing, and more. Each produces findings with severity, confidence scoring, and concrete fixes. Conditional Review agents activate when relevant (language focuses such as TypeScript for `.ts` files, database for schema changes, compliance when regulated surface detected in the diff). The gate level narrows these sets: the default `standard` level drops the TypeScript focus, and `lean` runs fewer focuses still. Every finding gets validated and resolved automatically.
 
 **Memory that persists.** Session context survives restarts, `/clear`, and context compaction. Your agent picks up exactly where it left off.
 
@@ -76,11 +76,11 @@ This is the **orchestrated flow** — you stay in the loop between every step. W
 
 **Your issue tracker, not just GitHub.** Pick the tracker your team actually uses — GitHub, Jira, or Linear — at `devflow init`, with `devflow init --tracker <id>`, or later with `devflow tracker --set <id>`; that sets your machine's default. A repository can select its own in `.devflow/project.json`, and devflow follows it there automatically — one machine can work on a Jira repository and a GitHub one side by side. Every install carries every provider's mechanics (48 generated reference files, the tool-call contract among them) and the background agent, because pull requests stay on GitHub whatever your tracker and any repository may pick any provider. On a non-GitHub tracker that agent learns your conventions once per provider (project key, issue types, required fields, workflow transitions, how a reference renders) and writes them to `~/.devflow/tracker/{provider}.md`, so traceability speaks your tracker's vocabulary instead of assuming `#123`. Each provider's conventions are learned from the first repository that uses it. Those files are yours: hand-editable, kept across an uninstall, and refused rather than silently trusted if one no longer names its own provider. The Git and Tracker agents reach a tracker only through the servers you allow (Atlassian, Jira and Linear by default); `devflow tracker --servers` names others. **GitHub is the default** and needs no configuration: no background run and no conventions file.
 
-**Full lifecycle.** Beyond the core flow: `/explore` maps a codebase into knowledge bases, `/research` runs multi-type research with trust-aware synthesis, `/debug` investigates with competing hypotheses in parallel, `/bug-analysis` hunts bugs before review, `/self-review` runs Simplify + Scrutinize quality passes, and `/release` ships with learned configuration.
+**Full lifecycle.** Beyond the core flow: `/explore` maps a codebase into knowledge bases, `/research` runs multi-type research with trust-aware synthesis, `/debug` investigates with competing hypotheses in parallel, `/bug-analysis` hunts bugs before review, `/self-review` runs Polish + Harden quality passes, and `/release` ships with learned configuration.
 
 **Everything is composable.** 21 plugins (12 core + 9 optional). Install only what you need.
 
-**HUD.** A persistent status line updates on every prompt — project, branch, diff stats, context usage, model, cost with weekly/monthly totals, quota reset timers, and configuration counts at a glance.
+**HUD.** A persistent status line updates on every prompt — project, branch, diff stats, context usage, model, cost with weekly/monthly totals, quota reset timers (Claude and Codex), and configuration counts at a glance.
 
 ```
 ~/devflow · main · +2 -1 · v2.0.0+3
@@ -166,7 +166,7 @@ To keep the knowledge bases or conventions local, add `.devflow/features/` or `.
 | `/research` | Multi-type research with trust-aware synthesis |
 | `/plan` | Full design pipeline: explore → gap analysis → design → PR-ready plan document |
 | `/implement` | Execute plan: accepts plan documents from `/plan`, issues, or task descriptions → PR |
-| `/self-review` | Simplify + Scrutinize quality pass |
+| `/self-review` | Polish + Harden quality pass |
 | `/code-review` | Multi-perspective parallel code review |
 | `/resolve` | Validate and fix all review issues |
 | `/debug` | Competing hypothesis investigation |
@@ -200,7 +200,9 @@ A repository can commit `.devflow/project.json` to settle team-wide choices. Eve
 
 Each key is checked on its own, so one bad value never disables the rest: a bad `evidence` resolves to `required`, a bad `reviewPublication` to `off`, a bad `compliance` list to the generic lens. A `project.json` or `config.json` that exists but is not a JSON object is never read as absent: the settings fail closed (publication off, knowledge write-back off, the tracker reported as invalid). The compliance lens is the exception, because it only adds scrutiny: it keeps every framework a readable layer declares, and an unreadable `project.json` counts as the generic lens. Memory and learning capture fail open instead: the hooks read an unreadable file as narrowing nothing, so capture runs as your machine's switch says.
 
-`config.json` is personal, so it must not be committed. A `config.json` that git tracks is ignored as if it were absent — otherwise a branch could commit `"reviewPublication":"full"` for whoever reviews it — and `devflow tracker|memory|learning|knowledge --status` say so, with the fix: `git rm --cached .devflow/config.json`. Commands never read the file themselves — one local resolver folds it with your `config.json` and the machine settings, without touching the network.
+`config.json` is personal, so it must not be committed. A `config.json` that git tracks is ignored as if it were absent — otherwise a branch could commit `"reviewPublication":"full"` for whoever reviews it — and `devflow tracker|memory|learning|knowledge|gates --status` say so, with the fix: untrack the tracked entry with `git rm --cached`, then check or delete the file, because untracking leaves the committed bytes on disk as your personal file. Commands never read the file themselves — one local resolver folds it with your `config.json` and the machine settings, without touching the network.
+
+**Gate level.** The gate level (`full`, `standard` or `lean`) is not a narrow-only switch: your personal `.devflow/config.json` may carry a top-level `"gateLevel"` key that raises or lowers the machine default, `devflow gates --set <level>` sets the machine default in `~/.devflow/manifest.json`, and `standard` applies when neither is set. A `gateLevel` in `project.json` is ignored, and no command writes the personal key. A malformed value reads as `full`. `/code-review` and `/plan` read the level: `standard` and `lean` run fewer review focuses and fewer planning agents. The security checks and, in `/plan`, the design review run at every level. The compliance gap agent runs on its own trigger at every level. Run `devflow gates --set full` to keep the full `/plan` shape; issue #480 adds more readers. After updating, run `devflow init`. See the [CLI reference](https://github.com/dean0x/devflow/blob/main/docs/cli-reference.md#gate-level).
 
 ## Evidence policy
 
@@ -286,6 +288,8 @@ npx devflow-kit compliance --status     # Show compliance state and this repo's
 npx devflow-kit tracker --set jira       # Pick the machine's default tracker (github | jira | linear)
 npx devflow-kit tracker --status         # Show provider, this repo's effective one, learned conventions, mechanics
 npx devflow-kit tracker --servers default # Tracker servers the agents may call (comma-separated names, or default)
+npx devflow-kit gates --set lean         # Set the machine's default gate level (full | standard | lean)
+npx devflow-kit gates --status          # Show the gate level in effect here and which layer decided it
 npx devflow-kit rules --status          # Show installed rules
 npx devflow-kit security --status       # Show / manage the security deny list
 npx devflow-kit safe-delete --enable    # Install rm -> trash safe-delete

package/dist/agents/code.md

@@ -67,7 +67,7 @@ You receive from orchestrator:
    - Read those relevant files to understand interfaces, types, naming conventions, error handling, and testing patterns established by prior work
    - If PRIOR_PHASE_SUMMARY is provided, use it to validate your understanding — actual code is authoritative, summaries are supplementary
    - If `DECISIONS_CONTEXT` is provided, follow `devflow:apply-decisions` on it. An absent key or `(none)` means no decisions context. State every decision or pitfall you apply in words in code, comments, tests and commit messages, never by its ID.
-   - If `HANDOFF_FILE` is provided, read only the `## Phase {N} Implementation Summary` section of the phase immediately before yours — list its `##` headings with `command grep -n '^## ' "$HANDOFF_FILE"`, then Read that range with `offset` and `limit` — never the whole file. Cross-reference against actual code — code is authoritative, handoff is supplementary.
+   - If `HANDOFF_FILE` is provided, read only the `## Phase {N} Implementation Summary` section of the phase immediately before yours — list its `##` headings with `command grep -n '^## ' "$HANDOFF_FILE"`, then Read that range with `offset` and `limit` — never the whole file.
 
 2. **Implement the plan**: Work through execution steps systematically, creating and modifying files. Follow existing patterns. Type everything. Use Result types if codebase uses them.
 
@@ -93,7 +93,6 @@ When `OPERATION: issue-fix`, you are fixing pre-classified issues assigned FIX_N
    - **Standard scope**: Fix directly following existing patterns
    - **Careful scope**: systematic protocol — understand (50+ lines context, callers/consumers) → plan → write failing regression test → implement → verify tests pass → commit
 3. **Regression test rule**: A regression fix without a failing-then-passing regression test is INCOMPLETE. Report BLOCKED rather than commit an unverified fix.
-4. **Self-verification scope**: Run compile + the fix's regression test only. The orchestrator's final validation gate is the single authoritative full build/test run — do not re-run the full suite here.
 
 **Return report** (a Return block in the spawn replaces this shape):
 - Status: COMPLETE | PARTIAL | BLOCKED
@@ -120,9 +119,7 @@ When `OPERATION: issue-fix`, you are fixing pre-classified issues assigned FIX_N
 - {Decision with rationale}
 
 ### Integration Points for Next Phase
-- {Interfaces to implement against}
-- {Functions to call}
-- {Types to import}
+- `path:line` of each interface, function or type the next phase builds on
 ```
 
 ## Running commands
@@ -140,11 +137,11 @@ Run builds, typechecks, lints and tests in the foreground, each with an explicit
 
 ## Principles
 
-1. **Work on feature branch** - All operations happen on the current feature branch
-2. **Orient, then match patterns** - Before writing code, orient on branch state and find similar implementations; match their conventions, don't invent new ones
-3. **Be decisive** - Make confident implementation choices. Don't present alternatives or ask permission for tactical decisions
-4. **Small, focused changes** - Don't scope creep beyond the plan
-5. **Fail honestly** - If blocked, report clearly with what was completed
+1. **Read once** - Never re-read an unchanged file. For a file over 400 lines, or a second look, `grep -n` first, then Read only that range (`offset`, `limit`)
+2. **Small, focused changes** - Don't scope creep beyond the plan
+3. **Fail honestly** - If blocked, report clearly with what was completed
+
+- Never print a large file whole; page it with offset and limit, and cap any output you print. Before printing search matches, list or count them.
 
 ## Output
 
@@ -184,4 +181,3 @@ Report cap: final message at most about 1,500 tokens; longer material goes to a
 - Switch branches during implementation
 - Push to branches other than your feature branch
 - Merge PRs (orchestrator handles this)
-- Trust handoff summaries without reading actual code

package/dist/agents/{diagnose.md → debug.md}

@@ -1,6 +1,6 @@
 ---
-name: Diagnose
-description: Proactive bug finding agent with static+semantic analysis. Focus-specific analysis across security, functional, integration, and usability categories.
+name: Debug
+description: Proactive bug finding agent with static+semantic analysis. Focus-specific analysis across security, functional, integration, and usability categories. The /bug-analysis command spawns it. It is not the /debug command.
 model: opus
 effort: medium
 skills:
@@ -16,7 +16,7 @@ tools:
   - Skill
 ---
 
-# Diagnose Agent
+# Debug Agent
 
 You are a proactive bug finding agent. Your focus area is specified in the prompt. You hunt for real bugs — not style issues — using a 5-step methodology that combines static analysis findings with semantic code understanding.
 
@@ -117,7 +117,7 @@ Assign to each verified finding:
 
 **Category mapping** (for `/resolve` compatibility — severity-based approximation):
 
-> **Trade-off**: The Review agent uses location-based categories (lines you added / lines you touched / unchanged lines). The Diagnose agent focuses on diff-changed code and lacks per-line location context, so it approximates using severity as a proxy. This means a LOW-severity bug in newly-added code is placed in Pre-existing — not because it predates the change, but to signal lower urgency. The resolve pipeline should treat Pre-existing findings from the Diagnose agent as low-urgency, not as assertions about code origin.
+> **Trade-off**: The Review agent uses location-based categories (lines you added / lines you touched / unchanged lines). The Debug agent focuses on diff-changed code and lacks per-line location context, so it approximates using severity as a proxy. This means a LOW-severity bug in newly-added code is placed in Pre-existing — not because it predates the change, but to signal lower urgency. The resolve pipeline should treat Pre-existing findings from the Debug agent as low-urgency, not as assertions about code origin.
 
 - CRITICAL / HIGH severity → `## Issues in Your Changes (BLOCKING)` — must fix before merge
 - MEDIUM severity → `## Issues in Code You Touched (Should Fix)` — fix while here

package/dist/agents/{code-fix.md → fix.md}

@@ -1,5 +1,5 @@
 ---
-name: Code-fix
+name: Fix
 description: Autonomous gate-failure repair on feature branch. Fixes the listed validation, alignment, QA or CI failures, verifies, and commits.
 model: sonnet
 effort: high
@@ -28,7 +28,7 @@ disallowedTools:
   - DesignSync
 ---
 
-# Code-fix Agent
+# Fix Agent
 
 You are an autonomous repair specialist working on a feature branch. A quality gate (validation, alignment, QA or CI) reported failures. You fix exactly the failures you are given, verify the fix and commit it. You operate independently, making implementation decisions without requiring approval for each step.
 
@@ -118,11 +118,11 @@ Run builds, typechecks, lints and tests in the foreground, each with an explicit
 
 ## Principles
 
-1. **Work on feature branch** - All operations happen on the current feature branch
-2. **Orient, then match patterns** - Before writing code, orient on branch state and find similar implementations; match their conventions, don't invent new ones
-3. **Be decisive** - Make confident implementation choices. Don't present alternatives or ask permission for tactical decisions
-4. **Small, focused changes** - Don't scope creep beyond the plan
-5. **Fail honestly** - If blocked, report clearly with what was completed
+1. **Read once** - Never re-read an unchanged file. For a file over 400 lines, or a second look, `grep -n` first, then Read only that range (`offset`, `limit`)
+2. **Small, focused changes** - Don't scope creep beyond the plan
+3. **Fail honestly** - If blocked, report clearly with what was completed
+
+- Never print a large file whole; page it with offset and limit, and cap any output you print. Before printing search matches, list or count them.
 
 ## Output
 
@@ -162,4 +162,3 @@ Report cap: final message at most about 1,500 tokens; longer material goes to a
 - Switch branches during implementation
 - Push to branches other than your feature branch
 - Merge PRs (orchestrator handles this)
-- Trust handoff summaries without reading actual code

package/dist/agents/{scrutinize.md → harden.md}

@@ -1,5 +1,5 @@
 ---
-name: Scrutinize
+name: Harden
 description: Self-review agent that evaluates and fixes implementation issues using 9-pillar framework. Runs in fresh context after Code agent completes.
 model: opus
 effort: medium
@@ -31,9 +31,9 @@ disallowedTools:
   - mcp__*
 ---
 
-# Scrutinize Agent
+# Harden Agent
 
-You are a meticulous self-review specialist. You evaluate implementations against the 9-pillar quality framework and fix the issues you find. You run in a fresh context after the Code and Simplify agents complete, ensuring adequate resources for thorough review and fixes.
+You are a meticulous self-review specialist. You evaluate implementations against the 9-pillar quality framework and fix the issues you find. You run in a fresh context after the Code and Polish agents complete, ensuring adequate resources for thorough review and fixes.
 
 ## Input Context
 
@@ -59,7 +59,7 @@ Follow the `devflow:apply-decisions` skill to scan the index, Read full bodies o
 
 4. **Evaluate P1 pillars** (Complexity, Error Handling, Tests): These SHOULD pass. Fix all issues found.
 
-5. **Evaluate P2** (Documentation): Fix if straightforward. Naming and Consistency belong to the Simplify agent: report them as SKIP.
+5. **Evaluate P2** (Documentation): Fix if straightforward. Naming and Consistency belong to the Polish agent: report them as SKIP.
 
 6. **Commit fixes**: If any changes were made, create a commit with message "fix: address self-review issues".
 
@@ -97,8 +97,8 @@ Return structured completion status:
 - Tests: PASS | FIXED (description)
 
 ### P2 Pillars
-- Naming: SKIP (Simplify agent)
-- Consistency: SKIP (Simplify agent)
+- Naming: SKIP (Polish agent)
+- Consistency: SKIP (Polish agent)
 - Documentation: PASS | FIXED (description)
 
 ### Files Modified

package/dist/agents/{code-edit.md → refactor.md}

@@ -1,6 +1,6 @@
 ---
-name: Code-edit
-description: Autonomous mechanical edit on feature branch. Applies a rename, move or boilerplate that adds no behaviour, and commits.
+name: Refactor
+description: Autonomous mechanical edit on feature branch. Makes a given rename, move or boilerplate change and commits. For judgment-based cleanup use Polish.
 model: sonnet
 effort: high
 skills:
@@ -27,7 +27,7 @@ disallowedTools:
   - DesignSync
 ---
 
-# Code-edit Agent
+# Refactor Agent
 
 You are an autonomous editing specialist working on a feature branch. You apply one mechanical change, run the tests of the touched modules once and commit. You operate independently, making implementation decisions without requiring approval for each step.
 
@@ -86,11 +86,11 @@ Run builds, typechecks, lints and tests in the foreground, each with an explicit
 
 ## Principles
 
-1. **Work on feature branch** - All operations happen on the current feature branch
-2. **Orient, then match patterns** - Before writing code, orient on branch state and find similar implementations; match their conventions, don't invent new ones
-3. **Be decisive** - Make confident implementation choices. Don't present alternatives or ask permission for tactical decisions
-4. **Small, focused changes** - Don't scope creep beyond the plan
-5. **Fail honestly** - If blocked, report clearly with what was completed
+1. **Read once** - Never re-read an unchanged file. For a file over 400 lines, or a second look, `grep -n` first, then Read only that range (`offset`, `limit`)
+2. **Small, focused changes** - Don't scope creep beyond the plan
+3. **Fail honestly** - If blocked, report clearly with what was completed
+
+- Never print a large file whole; page it with offset and limit, and cap any output you print. Before printing search matches, list or count them.
 
 ## Output
 
@@ -130,4 +130,3 @@ Report cap: final message at most about 1,500 tokens; longer material goes to a
 - Switch branches during implementation
 - Push to branches other than your feature branch
 - Merge PRs (orchestrator handles this)
-- Trust handoff summaries without reading actual code

package/dist/agents/review.md

@@ -229,3 +229,5 @@ use the same prefix so values are not double-masked.
 | java | If .java files changed |
 | python | If .py files changed |
 | rust | If .rs files changed |
+
+The gate level (`GATE_LEVEL`, `/code-review` Step 1.2b) removes focuses from this table at `standard` and `lean`.

package/dist/cli/agents-view/render.js

@@ -26,7 +26,7 @@
  * fits whole inside the cursor's "‹ … ›" wrapper with the dirty marker
  * ("‹ default (medium) ● ›", 22) — the shipped effort (D-SHIPPED-EFFORT) and the
  * unsaved mark are never clipped on the cursor row. The agent names the registry
- * holds are at most 10 characters ("Scrutinize"); longer orphan keys are
+ * holds are at most 10 characters ("Synthesize"); longer orphan keys are
  * truncated by truncateVisible.
  *
  * MODEL has no such slack for a worker row, whose shipped default is a full