devflow-kit 3.9.0 → 3.11.0

package/CHANGELOG.md

@@ -5,6 +5,146 @@ 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.11.0] - 2026-10-31
+
+### Upgrade notes — Files that devflow moves to a backup folder
+
+**What you must do:**
+- Nothing. If `devflow init` moves a file of yours, the output names the file and its new path.
+- To restore a moved file, copy it from the backup folder, `~/.devflow/install-backups/<UTC stamp>-<8 hex>/`, to one of its stable homes. Skills: `~/.devflow/skills/<name>/`. Rules: `~/.devflow/rules/`. Commands and agents: the top-level `commands/` and `agents/` folders of the Claude directory, outside the `devflow/` subfolders. A file that you put back into a devflow folder moves again on the next `devflow init`.
+
+**What to know:**
+- The backup is not encrypted. Devflow never prunes it. It stays until you delete it or run a full uninstall.
+- A file of yours with the same name as a shipped file is overwritten without a report.
+- Relative links in a moved folder can break.
+- Concurrent devflow runs are not supported.
+
+### Behaviour change
+
+- **Devflow now names the retired files that it removes, and it moves bare legacy skill folders instead of deleting them** ([#688](https://github.com/dean0x/devflow/issues/688)).
+  - `devflow init` and the toggles print each retired devflow file that they remove. Before, most of these removals printed nothing.
+  - A bare legacy skill folder, such as `skills/python` (a name from releases before v2), is now moved whole to the backup folder and named, but only when its `SKILL.md` is a copy that a release of devflow installed. Before, `devflow init` deleted every such folder. A skill of your own with such a name stays where it is. A folder that devflow cannot judge (no `SKILL.md`, or a link) also stays, and the output names it.
+  - A full `devflow uninstall` now removes a bare legacy skill folder, such as `skills/python`, only when its `SKILL.md` is a copy that a release of devflow installed. Before, it deleted every folder with such a name, without a backup, so a skill of your own with that name was lost. A skill of your own stays where it is. A folder that devflow cannot judge (no `SKILL.md`, or a link) also stays. The output names each folder that stays, and `--dry-run` lists the same folders. A `devflow:`-prefixed skill folder is removed as before.
+  - An interactive `devflow uninstall` where the install backups are the only user content in `~/.devflow` now asks before the full wipe. The prompt lists the backup folder, and a decline keeps the backups.
+
+### Fixed
+
+- **`devflow init` and the curation, compliance and rules toggles no longer delete files that devflow did not ship** ([#688](https://github.com/dean0x/devflow/issues/688)).
+  - A file that you keep in `commands/devflow/`, `agents/devflow/`, `rules/devflow/`, a `skills/devflow:*` folder or its `references/` folders is now moved to `~/.devflow/install-backups/<UTC stamp>-<8 hex>/`, and the output names it. Before, these commands deleted it. This holds for a full install, for a partial install (`--plugin`) and for the three toggles.
+  - A file that cannot move stays in place with its folder, and the output names it.
+
+---
+
+## [3.10.0] - 2026-10-30
+
+### Upgrade notes — Shadowed rules and skills
+
+**What you must do:**
+- A quality rule that you keep at `~/.devflow/rules/quality.md` replaces the shipped one, so you do not get its two new bullets. Add them to your copy. Or run `devflow rules unshadow quality`, which deletes your copy, and then run `devflow init`.
+- A testing skill that you keep at `~/.devflow/skills/testing/` replaces the shipped one, so you do not get its new Quality Gates item or its cuts. Add the item to your copy. Or run `devflow skills unshadow testing`, which deletes your copy, and then run `devflow init`.
+- A review-methodology or agent-references skill that you keep under `~/.devflow/skills/` replaces the shipped one, so you do not get the new follow-up text of #690. Add it to your copy. Or run `devflow skills unshadow <name>`, which deletes your copy, and then run `devflow init`.
+
+**Stale-install window:**
+- Until you run `devflow init`, the installed quality rule, testing, review-methodology and agent-references skills lack the new text.
+
+### Behaviour change
+
+- **With compliance off, devflow installs no step or reference that posts to GitHub or a tracker** ([#648](https://github.com/dean0x/devflow/issues/648)).
+  - With compliance off (the default for new installs and upgrades), devflow installs no step and no reference that posts test-plan evidence, review or resolution summaries, backlog entries, review-thread replies, wave reports, plan artifacts, or release back-links to GitHub or a tracker. Results stay in local files under `.devflow/docs/`.
+  - The change covers the `/implement`, `/resolve`, `/code-review`, `/bug-analysis`, `/dynamic-build`, `/dynamic-tickets`, `/plan` and `/release` commands, the Git and Triage agents, and the reference files that the Git agent reads. Each command names its local result files and marks them `(local; not posted)`. The commands still open pull requests, link issues and file tickets.
+  - The Git agent reads one reference file for each operation. With compliance off, devflow installs none of the files for the operations that post: the review summary, the resolution summary, the test-plan evidence, the backlog entry, the review-thread reply, the wave report and the two release back-link operations. This holds for the pull-request host and for each tracker. Devflow also installs neither the publication-gate document nor the `/implement` reference for the evidence questions. The other operation files stay.
+  - The GitHub posting recipes moved out of the GitHub API reference into a separate reference, `github-posting.md`. The recipes are the pull-request comments, the review, and the replies to review threads. That reference installs only with compliance on. The GitHub API reference keeps the rate-limit, fetch and release text.
+  - With compliance off, devflow no longer adds a link comment to an existing issue. It still creates a new issue when the task has none.
+  - The evidence publish script refuses to post unless the machine setting has compliance on. It reads only the machine install record. It ignores the devflow directory setting in the environment, and it reads no repository file. When compliance is off, it prints `TRACEABILITY: DEGRADED (compliance off)`. When it cannot read the record, it prints `TRACEABILITY: DEGRADED (compliance state unreadable)`. In both cases it exits with code 2 and makes no GitHub call.
+  - Where the repository requires evidence, each command prints one line: `TRACEABILITY: DEGRADED (compliance off on this machine; the repository requires evidence)`.
+  - Only the machine switch picks the installed build. A repository `compliance` key keeps the review lens on, locally, and never brings a posting step back.
+  - `devflow init`, `devflow curation` and `devflow compliance` use one converge. Every change of the compliance switch converges the installed commands, agents and references at once. The result equals a fresh install with the same switches, apart from stamps. With compliance off, the converge removes the omitted references. When compliance is on again, it puts each one back with the same bytes. If `devflow compliance` turns compliance on but cannot refresh an installed reference, it records the switch as on, names the cause, and exits 1. If `devflow compliance --disable` cannot show that no installed file still posts, it records the switch as off, lists the files that still post, and exits 1. A listed file can be a command, an agent or a reference. It also exits 1, with no success line, when it cannot remove the compliance rule. The command writes the switch under the install manifest lock. If it cannot take the lock, it writes nothing and exits 1.
+  - `devflow init` prints a one-time notice that names this effect. `devflow compliance --status` has a new `Posting:` line.
+  - The wave block that `/dynamic-build` writes on such a machine lists links only: `Refs` lines, never `Closes`. It admits `KEY-N` references as well as `#N` references. This corrects the earlier links-only rule, which admitted only `#N` references.
+  - Run `devflow init` after you update to install the new commands and references.
+
+### Changed
+
+- **Plan and code review list follow-up work, and file fewer tickets by default** ([#690](https://github.com/dean0x/devflow/issues/690)).
+  - At the `standard` and `lean` levels, `/plan` lists a sibling finding on the plan's deferred list, with no proposed ticket title, and files no ticket for it. You file one only if you want it. The `full` level does not change. The rest of the scope rule does not change.
+  - The review-methodology skill lists pre-existing problems and does not suggest separate issues for them. Its report template recommends an issue only for data loss, a false pass or a broken install.
+  - The plan levels reference is 47 bytes smaller (4,056 to 4,009), and its ceiling falls with it. The review-methodology skill is 24 bytes smaller, and its report template is 26 bytes larger.
+
+- **The quality rule and the testing skill target doc drift, duplicated code and vacuous tests** ([#476](https://github.com/dean0x/devflow/issues/476)).
+  - The quality rule has two new bullets. When a change alters a name, path or behavior, the agent updates the current tracked docs that state the old fact, and not released changelog entries. It describes a security fix by its effect only. Before it adds new code, the agent finds the existing owner and extends it when the new code shares its job. A trust-boundary or fail-closed check is not a copy.
+  - The Quality Gates of the testing skill have a new item: each new assertion would fail, not error, with the change reverted. The RED run counts; else a bad input or a temporary, uncommitted revert of your own edit shows it, never a stash. Three items that repeated other parts of the skill are cut, and a repeated parenthetical is cut from the flaky-pattern item. The skill is 25 bytes smaller, so the Code and Fix preload totals fall by 25 bytes each (Code 25,514 to 25,489, Fix 14,875 to 14,850). The quality rule is not in the preload and loads in every session: it grows by 326 bytes.
+  - A guard pins each new line once, with its limits, and pins a byte ceiling for the two bullets.
+
+### Fixed
+
+- **A partial install no longer writes through a linked devflow folder** ([#648](https://github.com/dean0x/devflow/issues/648)).
+  - If a folder that a partial install writes (commands, rules, agents, a skill folder or its references folder) is a link, the install now writes nothing there. It reports the folder, and you replace it with a real folder and run the install again.
+- **A full install no longer changes files outside its own folder when a skill folder is a link** ([#648](https://github.com/dean0x/devflow/issues/648)).
+  - If an installed skill folder is a link, a full install now removes the link and leaves the linked folder as it is. It then installs the skill into a real folder and reports the link.
+- **devflow no longer writes through a linked folder inside its own install folders; it refuses or replaces the link and reports it** ([#648](https://github.com/dean0x/devflow/issues/648)).
+  - This applies to the install, to `uninstall --plugin` and to every converge, for example `devflow curation`, `devflow compliance` and `devflow behavior`.
+- **The `/implement` self-review (Harden) states that it never reviews a deleted file or the old path of a rename** ([#571](https://github.com/dean0x/devflow/issues/571)).
+  - The file list that Harden gets leaves out deleted files and the old path of a rename. The command now says so.
+  - When the prompt lists no file, Harden reports `### Status: PASS` with the line `no files reviewed`. An empty list no longer reads as a completed review, because the final report of `/implement` shows the line, at every gate level. When the prompt has no file list at all, Harden finds the branch changes and reviews them, as before.
+  - The docs describe the same rule.
+- **The `/implement` command states that alignment-fix commits get no self-review** ([#572](https://github.com/dean0x/devflow/issues/572)).
+  - Phase 4 runs before the alignment fix, so Harden does not review the commits of that fix. The command now says that Phase 6 Validate and `/code-review` check them.
+  - The docs describe the same rule.
+- **At `lean`, `/implement` runs the lint pack again after a QA fix** ([#535](https://github.com/dean0x/devflow/issues/535)).
+  - The re-validation after a QA fix now gets the gate level and the branch base, as Phase 6 does. A pack match that a QA fix adds is now reported, and the re-validation fails on it, as it does on any other failure.
+  - At `lean`, the re-validation labels passed-alone files, and its `Lint pack:` line replaces the one from Phase 6. The pack scans the branch a second time, so a run with QA fixes does that work twice.
+  - A pack error after a QA fix reads `UNVERIFIED`, never a pass. So does a re-validation that prints no `Lint pack:` line: it never reads clean, and it never drops an `UNVERIFIED` result from the first validation.
+  - At `full` and `standard`, the re-validation prompt does not change.
+- **`/implement` re-validation now follows your compliance, review-publication and PR-title settings, and always runs self-review** ([#544](https://github.com/dean0x/devflow/issues/544)).
+  - With compliance on, the fix agents in a re-validation get the compliance guidance, as in a full run. With compliance off, re-validation gives them none, as before.
+  - Re-validation now follows your review-publication setting, as a full run does.
+  - Re-validation now applies your team's PR-title convention, as a full run does.
+  - Re-validation always runs the self-review (Harden) step, at every gate level.
+- **The gate-level step of `devflow init` fits an 80-column terminal** ([#658](https://github.com/dean0x/devflow/issues/658)).
+  - Each level hint is now one short line, and no line of the step note is longer than 72 characters.
+  - The step note names `/resolve` with the other commands that read the level.
+  - The full effect of each level stays in `devflow gates` and in the docs.
+- **`/bug-analysis` no longer reports "no findings" when static analysis could not run** ([#649](https://github.com/dean0x/devflow/issues/649)).
+  - When no scanner is installed, it says that static analysis did not run. It no longer reports "no findings" for a run that scanned nothing.
+  - A scanner that fails, does not finish or exits with an error is named in the report with its exit status, or says that it had none.
+  - File names with spaces or other unusual characters reach the scanners whole.
+  - Semgrep and Snyk now run one after the other.
+- **`/bug-analysis` keeps its head marker when static analysis did not cover the commits, and a long scanner result no longer hides findings** ([#652](https://github.com/dean0x/devflow/issues/652), [#661](https://github.com/dean0x/devflow/issues/661)).
+  - The marker moves only when every tool that was to run completed, or `--no-static` is set. Otherwise the report keeps the marker and names the way out: fix the tool, or run with `--no-static`. The next run then covers the same commits again.
+  - The report shows a status for each tool: completed, not installed, not needed (CodeQL only), no supported language (CodeQL, or Snyk when it finds no supported file), or did not complete with the reason. The summary takes this status from the command, not from the text of a file.
+  - Each scanner writes its SARIF to a file, and the session reads counts and a table of the top 50 findings. A long result no longer hides a finding or the exit line. Every finding is saved to a table in the run folder.
+  - Snyk keeps each result for a changed file. If its filter fails, the report says so and uses the unfiltered result.
+  - CodeQL scans one language, chosen from the changed files: JavaScript or TypeScript, Python, or Ruby. With none of them, the report says that CodeQL had no supported language.
+  - Each Semgrep, Snyk and CodeQL call has its Bash timeout at the ceiling: 600000 ms, or `BASH_MAX_TIMEOUT_MS` when set. Devflow sets no time limit of its own on a scanner. A call that reaches the Bash limit counts as not complete.
+- **The orchestrator charter names only installed workflows and routes to more agents.**
+  - The charter now names only the workflows that you installed, and it names the Fix agent only when it is installed.
+  - It routes to the Test, Evaluate, Harden and Synthesize agents. It routes to the Knowledge agent only when you ask for a new knowledge base. It names the `devflow:bug-analysis` workflow.
+  - For debug work, it names `devflow:debug` when that workflow is installed. Otherwise it sends the work to Explore, then Code. It never routes to the Debug agent.
+  - A plan handoff no longer points to `devflow:implement` when it is not installed. The prompt gets a generic reminder instead.
+  - `devflow ambient --enable` now warns when the ambient agents are not installed. It still registers the hooks.
+  - `devflow uninstall --plugin` removes the plan-handoff marker when it removes implement. It does this also when the manifest has no record of the install.
+  - `devflow uninstall --plugin` also drops a manifest record that holds the old name of the removed plugin.
+  - Run `devflow init` after you update to refresh the charter.
+- **The CI wait and the Validate re-runs no longer stop too early** ([#664](https://github.com/dean0x/devflow/issues/664)). The CI wait waits for CI to start until its 570 s limit, not only 90 s, so a repository with no CI now waits 570 s before the wait reports no CI. When a pull request has only external checks and the repository has no workflow file, the wait ends at once. The CI gates of `/implement` and `/resolve` do not wait again after a full 570 s wait that ends with a head mismatch or no workflow check, so one gate waits at most about 3 x 570 s (28.5 minutes), and only when CI keeps running or its status stays unknown for another cause. Validate no longer stops the re-run of a failed test file alone after 120 s.
+- **Validate waits for a long one-file re-run and reads its result** ([#666](https://github.com/dean0x/devflow/issues/666)). When the re-run of one failed test file runs past its Bash timeout, Validate now waits for it to end and reads its result, so the file gets its label from the real result and no test process stays running with nobody to read it. After one such re-run, Validate re-runs no more files, and the other failed files are REAL.
+- **A run that reaches its Bash timeout is waited for and read, and only the last exit line of the output file that the end notice names sets the result** ([#677](https://github.com/dean0x/devflow/issues/677)).
+  - The Code, Fix, Refactor, Validate and Test agents no longer report BLOCKED for a build, test or lint run that passes its Bash timeout. The run moves to the background. The agent makes no tool call, not even a read, until the end notice. Then it reads the last `EXIT=` line of the file that the move names, not the capture log, because a read of the wrong file could report a pass. That line alone sets the result: the end notice and the log do not.
+  - A run is BLOCKED only when no `EXIT=` line is read, with its duration and log path. A failed run that is read after the wait gets its re-runs like any failed run. A `LINT_PACK:` line that is read after the wait counts like a line read in time.
+  - Splitting a long run into parts is optional. The `bash-max-timeout-ms` flag is optional too, and the agents no longer name it.
+  - The one-file re-run in Validate is waited for and read in the same way.
+  - `/bug-analysis` waits for a scanner call that reaches the Bash limit, with no tool call until the end notice, and then reads the last `exit=` line of the output file that the notice names, never a scanner file. A scanner call with no `exit=` line read still counts as not complete. Semgrep writes its result to `semgrep.part` and renames it to `semgrep.sarif` when its scan ends, so the SARIF file appears only when the scan ends. The warning for a missing scanner no longer names an install command.
+  - `/implement` reports and halts when the Validate report has a Status other than PASS or FAIL, or none. This includes a BLOCKED report, in the validation and in the re-validation. `/resolve` records FAILED and ends its validation loop in the same case. Neither reads it as a pass.
+  - Accepted cost: devflow stops no run, so a run that never ends holds its agent until you stop it (Esc). Parallel agents in one wave each wait for their own run.
+- **A test or validation run that gives no result never reads as a pass** ([#679](https://github.com/dean0x/devflow/issues/679), [#680](https://github.com/dean0x/devflow/issues/680), [#681](https://github.com/dean0x/devflow/issues/681)).
+  - The Test agent can report `BLOCKED`: no blocking scenario failed, and the command of a blocking scenario gave no result (it could not start, or no `EXIT=` line was read). The report lists each such scenario under `### Blockers`, with its cause, its duration and its log path. A scenario that is skipped because a tool is missing never makes the run BLOCKED. When a blocking scenario is skipped and every blocking scenario that ran passed, the Status line stays `PASS` and names each skip, for example `PASS (1 BLOCKING scenario skipped: no browser tools)`, or `PASS (0 of 3 BLOCKING scenarios ran: all skipped, no browser tools)` when none ran. `/implement`, `/resolve` and the acceptance gate of `/dynamic-build` read that line by its first word, `PASS`; the gate returns the verdict `PASS` without the note. Each test-plan line still gets `PASS`, `FAIL` or `SKIP`, and a line is `PASS` only when at least one scenario covers it and every one passed.
+  - `/implement` gives the cause and the log path when it stops on a BLOCKED Validate or Test report. It also stops on a Test report with any other Status or none. It starts no fix agent, and it still records the test-plan claims of that Test report.
+  - `/resolve` records a BLOCKED validation as `Final gate: FAILED (Validate blocked)`, with a blocking callout, and starts no fix agent. It still pushes, and the later phases still run. The cause and the log path go only to the report that you see, never to the posted summary. A stale test-plan re-check that is BLOCKED records `Test plan: DEGRADED (Test run blocked)`.
+  - In `/dynamic-build`, a BLOCKED, missing or unknown Test result in the acceptance gate keeps the ticket from `PASS`: the run reports `UNVERIFIED`, or `PARTIAL` when the review leaves findings. It starts no fix agent and raises no error. In wave mode such a ticket merges as `UNVERIFIED`, never as `PASS`, and the wave table shows `—` in its Test column. This includes a ticket whose Test reply is missing or empty.
+  - The build rules of `/dynamic-build` name all five agents that carry the shared rules for running commands: Code, Fix, Refactor, Validate and Test.
+- **`/self-review` stops when its validation does not pass** ([#695](https://github.com/dean0x/devflow/issues/695)). A Validate report with a Status other than PASS or FAIL, or with no Status, stops the command. This includes a BLOCKED report. The command reports the status, or "none", with its cause and, when the report gives one, its log path. It shows no completion summary. Before, it had steps only for PASS and FAIL, so the summary could read as if validation passed.
+
+---
+
 ## [3.9.0] - 2026-10-22
 
 ### Upgrade notes — Evaluate by level
@@ -2228,6 +2368,8 @@ devflow init
 ---
 
 [Unreleased]: https://github.com/dean0x/devflow/compare/v3.8.0...HEAD
+[3.11.0]: https://github.com/dean0x/devflow/compare/v3.10.0...v3.11.0
+[3.10.0]: https://github.com/dean0x/devflow/compare/v3.9.0...v3.10.0
 [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

package/README.md

@@ -52,7 +52,7 @@ This is the **orchestrated flow** — you stay in the loop between every step. W
 
 ## What you get
 
-**Ambient orchestration.** Your main session becomes the tech lead: a charter injected at session start turns it into an orchestrator that delegates work to specialized agents and keeps judgment mainline, with one bounded inline exception for a single short git, gh or script command. Plan-mode handoffs auto-run `/implement`. Init and forget.
+**Ambient orchestration.** Your main session becomes the tech lead: a charter injected at session start turns it into an orchestrator that delegates work to specialized agents and keeps judgment mainline, with one bounded inline exception for a single short git, gh or script command. Plan-mode handoffs run `/implement` when it is installed. Init and forget.
 
 **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`).
 

package/dist/agents/code.md

@@ -126,13 +126,13 @@ When `OPERATION: issue-fix`, you are fixing pre-classified issues assigned FIX_N
 
 Run builds, typechecks, lints and tests in the foreground, each with an explicit Bash `timeout` above its expected run time. The ceiling is 600000 ms, or `BASH_MAX_TIMEOUT_MS` when set (`echo ${BASH_MAX_TIMEOUT_MS:-600000}`).
 
-- Capture, then tail, in one Bash call (shell state does not persist): `LOG=$(mktemp); echo "LOG=$LOG"; <command> >"$LOG" 2>&1; rc=$?; tail -n 40 "$LOG"; echo "EXIT=$rc"`. The printed `EXIT=` value is the result; never decide one from a grep count.
-- Never background a command and wait on it, and never poll across turns: no `sleep` or `true` turns, no sentinel-file checks, no Monitor.
-- Prefer the scoped command for the change (a package, a path or a test file); for the whole set, one workspace-level command over a per-package loop.
-- A run that exceeds its timeout is BLOCKED: report its duration and log path. Do not wait on it, poll it or re-run it.
-- A run expected to exceed the ceiling is split into parts, each under about 90% of it, run in sequence. If it cannot be split, report BLOCKED with the remedy `devflow flags --set bash-max-timeout-ms=<ms>`.
+- Capture, then tail, in one Bash call: `LOG=$(mktemp); echo "LOG=$LOG"; <command> >"$LOG" 2>&1; rc=$?; tail -n 40 "$LOG"; printf '\nEXIT=%s\n' "$rc"`. The last `EXIT=` line is the result; never decide one from a grep count.
+- Never background a build or test, and never poll across turns: no `sleep` or `true` turns, no sentinel-file checks, no Monitor.
+- Prefer the scoped command for the change; for the whole set, one workspace command over per-package loops.
+- A run past its timeout moves to the background: no tool call, even a Read, until its end notice, then Read the last `EXIT=` line of the file the move names, not `$LOG`; it alone sets the label, not the notice. With none read it is BLOCKED: report its duration and log path. Report only after the end notice.
+- A run expected to exceed the ceiling may be split into parts, run in sequence.
 - Never re-run a command when nothing it reads has changed.
-- Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they would allow directly.
+- Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they allow directly.
 - The same rules hold inside a dynamic Workflow sub-agent.
 
 ## Principles

package/dist/agents/fix.md

@@ -108,13 +108,13 @@ When `OPERATION: ci-fix`, you are fixing the CI checks the ci-status gate report
 
 Run builds, typechecks, lints and tests in the foreground, each with an explicit Bash `timeout` above its expected run time. The ceiling is 600000 ms, or `BASH_MAX_TIMEOUT_MS` when set (`echo ${BASH_MAX_TIMEOUT_MS:-600000}`).
 
-- Capture, then tail, in one Bash call (shell state does not persist): `LOG=$(mktemp); echo "LOG=$LOG"; <command> >"$LOG" 2>&1; rc=$?; tail -n 40 "$LOG"; echo "EXIT=$rc"`. The printed `EXIT=` value is the result; never decide one from a grep count.
-- Never background a command and wait on it, and never poll across turns: no `sleep` or `true` turns, no sentinel-file checks, no Monitor.
-- Prefer the scoped command for the change (a package, a path or a test file); for the whole set, one workspace-level command over a per-package loop.
-- A run that exceeds its timeout is BLOCKED: report its duration and log path. Do not wait on it, poll it or re-run it.
-- A run expected to exceed the ceiling is split into parts, each under about 90% of it, run in sequence. If it cannot be split, report BLOCKED with the remedy `devflow flags --set bash-max-timeout-ms=<ms>`.
+- Capture, then tail, in one Bash call: `LOG=$(mktemp); echo "LOG=$LOG"; <command> >"$LOG" 2>&1; rc=$?; tail -n 40 "$LOG"; printf '\nEXIT=%s\n' "$rc"`. The last `EXIT=` line is the result; never decide one from a grep count.
+- Never background a build or test, and never poll across turns: no `sleep` or `true` turns, no sentinel-file checks, no Monitor.
+- Prefer the scoped command for the change; for the whole set, one workspace command over per-package loops.
+- A run past its timeout moves to the background: no tool call, even a Read, until its end notice, then Read the last `EXIT=` line of the file the move names, not `$LOG`; it alone sets the label, not the notice. With none read it is BLOCKED: report its duration and log path. Report only after the end notice.
+- A run expected to exceed the ceiling may be split into parts, run in sequence.
 - Never re-run a command when nothing it reads has changed.
-- Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they would allow directly.
+- Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they allow directly.
 - The same rules hold inside a dynamic Workflow sub-agent.
 
 ## Principles

package/dist/agents/harden.md

@@ -33,16 +33,18 @@ disallowedTools:
 
 # 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 Polish 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.
 
 ## Input Context
 
 You receive from orchestrator:
 - **TASK_DESCRIPTION**: What was implemented
-- **FILES_CHANGED**: List of modified files from Code agent output
+- **FILES_CHANGED** (optional): The branch diff's file list, with no deleted file or old rename path
 - **DECISIONS_CONTEXT** (optional): Compact index of active ADR/PF entries for this repository (pre-rendered to `.devflow/curation/index.md` in its main worktree). `(none)` when absent. Use `devflow:apply-decisions` to Read full bodies on demand.
 - **FEATURE_KNOWLEDGE** (optional): Per KB, the Rules bullets and the KB path, with no heading index, for pattern compliance checking. Check implementation against each bullet's anti-pattern, gotcha or invariant; Read a KB section from its path for more. Follow `devflow:apply-feature-knowledge`.
 
+**Empty FILES_CHANGED**: If the prompt has a `FILES_CHANGED` line that lists no file, report `### Status: PASS` with the line `no files reviewed`, and review nothing; with no `FILES_CHANGED` line, find the branch changes and review them.
+
 **Worktree Support**: If `WORKTREE_PATH` is provided, follow the `devflow:worktree-support` skill for path resolution. If omitted, use cwd.
 
 ## Apply Decisions
@@ -72,10 +74,9 @@ Code-scanning runs in the Code agent; do not scan here.
 ## Principles
 
 1. **Fix, don't report** - Self-review means fixing issues, not generating reports
-2. **Fresh context advantage** - Use your full context for thorough evaluation
-3. **Pillar priority** - P0 issues block, P1 issues should be fixed, P2 covers Documentation only
-4. **Minimal changes** - Fix the issue, don't refactor surrounding code
-5. **Honest assessment** - If P0 issue is unfixable, report BLOCKED immediately
+2. **Pillar priority** - P0 issues block, P1 issues should be fixed, P2 covers Documentation only
+3. **Minimal changes** - Fix the issue, don't refactor surrounding code
+4. **Honest assessment** - If P0 issue is unfixable, report BLOCKED immediately
 
 ## Output
 

package/dist/agents/refactor.md

@@ -75,13 +75,13 @@ When `OPERATION: edit`, you apply a mechanical change: a rename, a move or boile
 
 Run builds, typechecks, lints and tests in the foreground, each with an explicit Bash `timeout` above its expected run time. The ceiling is 600000 ms, or `BASH_MAX_TIMEOUT_MS` when set (`echo ${BASH_MAX_TIMEOUT_MS:-600000}`).
 
-- Capture, then tail, in one Bash call (shell state does not persist): `LOG=$(mktemp); echo "LOG=$LOG"; <command> >"$LOG" 2>&1; rc=$?; tail -n 40 "$LOG"; echo "EXIT=$rc"`. The printed `EXIT=` value is the result; never decide one from a grep count.
-- Never background a command and wait on it, and never poll across turns: no `sleep` or `true` turns, no sentinel-file checks, no Monitor.
-- Prefer the scoped command for the change (a package, a path or a test file); for the whole set, one workspace-level command over a per-package loop.
-- A run that exceeds its timeout is BLOCKED: report its duration and log path. Do not wait on it, poll it or re-run it.
-- A run expected to exceed the ceiling is split into parts, each under about 90% of it, run in sequence. If it cannot be split, report BLOCKED with the remedy `devflow flags --set bash-max-timeout-ms=<ms>`.
+- Capture, then tail, in one Bash call: `LOG=$(mktemp); echo "LOG=$LOG"; <command> >"$LOG" 2>&1; rc=$?; tail -n 40 "$LOG"; printf '\nEXIT=%s\n' "$rc"`. The last `EXIT=` line is the result; never decide one from a grep count.
+- Never background a build or test, and never poll across turns: no `sleep` or `true` turns, no sentinel-file checks, no Monitor.
+- Prefer the scoped command for the change; for the whole set, one workspace command over per-package loops.
+- A run past its timeout moves to the background: no tool call, even a Read, until its end notice, then Read the last `EXIT=` line of the file the move names, not `$LOG`; it alone sets the label, not the notice. With none read it is BLOCKED: report its duration and log path. Report only after the end notice.
+- A run expected to exceed the ceiling may be split into parts, run in sequence.
 - Never re-run a command when nothing it reads has changed.
-- Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they would allow directly.
+- Never wrap a build or test command in `sh -c`, `bash -c`, `python3 -c` or `node -e`: permission rules deny wrapped commands they allow directly.
 - The same rules hold inside a dynamic Workflow sub-agent.
 
 ## Principles

package/dist/cli/commands/ambient.js

@@ -4,7 +4,7 @@ import * as path from 'path';
 import * as p from '@clack/prompts';
 import color from 'picocolors';
 import { getClaudeDirectory, getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
-import { syncManifestFeature } from '../../core/manifest.js';
+import { readManifestPlugins, syncManifestFeature } from '../../core/manifest.js';
 import { writeSettingsFileAtomic } from '../../core/fs-atomic.js';
 import { HOOKS_DIR_SUFFIX, endsWithAny, ensureHook, hasHook, removeHooks, runHookCommand, runHookSuffix, } from '../../targets/claude-code/hooks.js';
 const PREAMBLE_HOOK_MARKER = 'preamble';
@@ -219,6 +219,14 @@ export function createAmbientCommand() {
         // exist, so every prompt would fail.
         const devflowDir = getDevFlowDirectory();
         if (options.enable) {
+            // The hooks route to the ambient agents and the rendered charter that `devflow init` installs.
+            // The manifest is the record of that install. readManifestPlugins is read-only: unlike
+            // readManifest it never heals or rewrites the file. The check runs before the already-enabled
+            // return so a repeat run still reports it, and it never blocks the registration below.
+            const recordedPlugins = await readManifestPlugins(devflowDir);
+            if (recordedPlugins === null || !recordedPlugins.includes('devflow-ambient')) {
+                p.log.warn('Ambient agents are not installed. Run `devflow init` to install them.');
+            }
             const updated = await addAmbientHook(settingsContent, devflowDir);
             if (updated === settingsContent) {
                 // Both hooks already present — addAmbientHook purges any legacy rule anyway
@@ -228,7 +236,7 @@ export function createAmbientCommand() {
             await writeSettingsFileAtomic(settingsPath, updated);
             await syncManifestFeature(devflowDir, 'ambient', true);
             p.log.success('Ambient mode enabled — orchestrator hooks registered');
-            p.log.info(color.dim('Charter at session start, reminder per prompt, plan handoffs auto-run devflow:implement (git repos only)'));
+            p.log.info(color.dim('Charter at session start, reminder per prompt, plan handoffs run devflow:implement when it is installed (git repos only)'));
         }
         if (options.disable) {
             const updated = await removeAmbientHook(settingsContent);

package/dist/cli/commands/backup-session.js

@@ -0,0 +1,131 @@
+/**
+ * The backup session of one command run: made once, before the command changes anything, and its
+ * record printed once when the command ends.
+ *
+ * `devflow init`, `devflow curation`, `devflow compliance` and `devflow rules` each make one
+ * session with {@link openBackupSession} and wrap the steps that may move or remove files in
+ * {@link runWithBackupReport}. The wrapper prints the record after the steps return or throw, so a
+ * run that moved a file and then failed still names where the file went.
+ */
+import { randomBytes } from 'crypto';
+import * as p from '@clack/prompts';
+import { WORKFLOW_FOLDERS } from '../../core/mds-variants.js';
+import { getPackageRoot } from '../../core/paths.js';
+import { retiredPathSet } from '../../core/retired-shipped-names.js';
+import { createBackupSession } from '../../targets/claude-code/install-backup.js';
+import { loadShippedSet } from '../../targets/claude-code/shipped-set.js';
+import { formatBackupSummary } from './install-report.js';
+/**
+ * Log each summary line at the severity it carries — the one dispatch every
+ * `SummaryLine[]` renderer shares.
+ *
+ * Exhaustive over `SummaryLine['level']` rather than an `if/else`: a level added
+ * to the interface has to be routed here, at compile time, instead of silently
+ * degrading to `info` at every call site.
+ */
+export function logSummaryLines(lines) {
+    for (const line of lines) {
+        switch (line.level) {
+            case 'success':
+                p.log.success(line.message);
+                break;
+            case 'info':
+                p.log.info(line.message);
+                break;
+            case 'warn':
+                p.log.warn(line.message);
+                break;
+            default: {
+                const _exhaustive = line.level;
+                void _exhaustive;
+                break;
+            }
+        }
+    }
+}
+/**
+ * Make the backup session of a command run, before the command changes anything.
+ *
+ * The shipped set comes from the full registries and the package source, never from what an
+ * earlier install left on disk. When it cannot be built the answer is a message and no session:
+ * a session with a smaller set would move devflow's own files aside. The caller prints the
+ * message, exits non-zero and changes nothing.
+ */
+export async function openBackupSession(options) {
+    const loaded = await loadShippedSet({
+        devflowDir: options.devflowDir,
+        packageRoot: options.packageRoot ?? getPackageRoot(),
+        workflowFolders: WORKFLOW_FOLDERS,
+    });
+    if (!loaded.ok) {
+        return {
+            ok: false,
+            message: `Could not list the files devflow ships, so nothing was changed: ${loaded.reason}`,
+        };
+    }
+    const session = createBackupSession({
+        shipped: loaded.shipped,
+        retired: retiredPathSet(),
+        claudeDir: options.claudeDir,
+        devflowDir: options.devflowDir,
+        now: () => new Date(),
+        bytes: size => randomBytes(size),
+    });
+    return { ok: true, session };
+}
+/**
+ * The session of a command that reports its failures through the exit code: the session, or null
+ * after one error line and exit code 1. The caller then returns without a change.
+ */
+export async function openBackupSessionOrFail(options) {
+    const opened = await openBackupSession(options);
+    if (opened.ok)
+        return opened.session;
+    p.log.error(opened.message);
+    process.exitCode = 1;
+    return null;
+}
+/**
+ * Run `fn`, which makes its session part-way through (it calls `begin`), and print the record of
+ * that session once: at its own `print` call, or else after `fn` returns or throws and before the
+ * caller returns or rethrows. A step that ends the process (`process.exit`) calls `print` first,
+ * since nothing after an exit runs. A throw from `fn` passes on unchanged, and a run that never
+ * calls `begin` prints nothing.
+ *
+ * @param emit - Where the lines go. Defaults to the clack log.
+ */
+export async function runWithLateBackupReport(fn, emit = logSummaryLines) {
+    let session = null;
+    let printed = false;
+    const report = {
+        begin: (opened) => { session = opened; },
+        print: () => {
+            if (printed || session === null)
+                return;
+            printed = true;
+            emit(formatBackupSummary(session.snapshot()));
+        },
+    };
+    try {
+        return await fn(report);
+    }
+    finally {
+        report.print();
+    }
+}
+/**
+ * Run `fn` and print the record of `session` once, after `fn` returns or throws and before the
+ * caller returns, rethrows or exits. A throw from `fn` passes on unchanged.
+ *
+ * `fn` receives `printBackups`, which prints the record at once and is a no-op afterwards: a step
+ * that ends the process (`process.exit`) calls it first, since nothing after an exit runs.
+ *
+ * @param emit - Where the lines go. Defaults to the clack log.
+ */
+export function runWithBackupReport(session, fn, emit = logSummaryLines) {
+    return runWithLateBackupReport(async (report) => {
+        report.begin(session);
+        return fn(report.print);
+    }, emit);
+}
+//# sourceMappingURL=backup-session.js.map

package/dist/cli/commands/compliance-prompts.js

@@ -126,12 +126,17 @@ export async function runComplianceStep(opts) {
         'Stamps the compliance rule with active framework labels and installs\n' +
         'framework reference files into the compliance skill. Only the\n' +
         'frameworks you select are included — zero selection = generic controls.\n\n' +
+        'Compliance on also installs the steps that post test-plan evidence, review\n' +
+        'and resolution summaries, backlog entries, review-thread replies, wave\n' +
+        'reports, plan artifacts and release back-links to GitHub or a tracker.\n' +
+        'Compliance off installs none of them; results stay in local files under\n' +
+        '.devflow/docs/.\n\n' +
         formatFrameworkCatalogue(), 'Compliance');
     const enableOutcome = await prompts.select({
         message: 'Enable compliance?',
         options: [
-            { value: true, label: 'Yes', hint: 'stamps frameworks into the compliance rule and skill' },
-            { value: false, label: 'No', hint: 'enable later with devflow compliance --enable' },
+            { value: true, label: 'Yes', hint: 'stamps frameworks into the rule and skill; installs the steps that post to GitHub or a tracker' },
+            { value: false, label: 'No', hint: 'no step that posts is installed; enable later with devflow compliance --enable' },
         ],
         initialValue: seed.enabled,
     });
@@ -145,7 +150,7 @@ export async function runComplianceStep(opts) {
             state: { enabled: false, frameworks: [...seed.frameworks] },
             messages: [{
                     level: 'info',
-                    text: 'Compliance: disabled — enable later with devflow compliance --enable',
+                    text: 'Compliance: disabled — no step that posts is installed; enable later with devflow compliance --enable',
                 }],
         };
     }
@@ -164,7 +169,7 @@ export async function runComplianceStep(opts) {
     return {
         kind: 'resolved',
         state: { enabled: true, frameworks },
-        messages: [{ level: 'success', text: `Compliance: enabled (${fwLabel})` }],
+        messages: [{ level: 'success', text: `Compliance: enabled (${fwLabel}) — the steps that post are installed` }],
     };
 }
 //# sourceMappingURL=compliance-prompts.js.map