devflow-kit 3.9.0 → 3.10.0

package/CHANGELOG.md

@@ -5,6 +5,116 @@ 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.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 +2338,7 @@ devflow init
 ---
 
 [Unreleased]: https://github.com/dean0x/devflow/compare/v3.8.0...HEAD
+[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/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

package/dist/cli/commands/compliance.js

@@ -2,11 +2,14 @@
  * devflow compliance — Enable, disable, set, and check status of the compliance feature.
  *
  * CLI-layer module; pure helpers in src/core/compliance.ts,
- *   I/O orchestration in src/targets/claude-code/compliance-install.ts.
+ *   I/O orchestration in src/targets/claude-code/curation-install.ts (the one converge
+ *   for both axes) and compliance-install.ts (the compliance artifacts it composes).
  * Compliance is manifest-group (like proxy), not config.json-gated.
  * Per-artifact failures are warn-not-throw, so one failed artifact never aborts the rest.
- * Enable/disable each converge BOTH artifacts unconditionally, so neither is left
- *   half-converged.
+ * Every change of the switch (enable, disable, --set, interactive enable) writes the switch,
+ *   runs the one converge, and only after a clean converge records which variants are installed.
+ * With compliance off the command fails closed (AC-28): it exits non-zero when an installed
+ *   prompt may still post, and prints no success line.
  * The evidence-policy lines (--status, and the --enable/--set suggestion) come
  *   from src/core/evidence-policy.ts, the seam onto the package's own resolvers;
  *   the CLI prints the keys to add to .devflow/project.json and never writes it
@@ -21,7 +24,10 @@ import { COMPLIANCE_FRAMEWORKS, normalizeFrameworks, parseFrameworkList, } from
 import { frameworkChoices, FRAMEWORK_SELECT_MESSAGE } from './compliance-prompts.js';
 import { COMPLIANCE_SKILL_TOKENS } from '../../core/compliance-compose.js';
 import { evidencePolicyStatusLine, evidencePolicySuggestion, formatEvidencePolicyUnavailable, loadEvidencePolicyModule, loadSettingsModule, repoComplianceStatusLines, } from '../../core/evidence-policy.js';
+import { postingStatus, readInstalledVariants } from '../../core/installed-variants.js';
+import { withManifestLock } from '../../core/manifest-lock.js';
 import { readManifest, writeManifest } from '../../core/manifest.js';
+import { applyVariantToggle, describePostingLeft, describeVariantConverge, readRunningVersion, } from '../../targets/claude-code/curation-install.js';
 import { convergeFromManifest } from '../../targets/claude-code/compliance-install.js';
 import { validateRuleShadow, validateSkillShadow } from '../../targets/claude-code/installer.js';
 import { getClaudeDirectory, getDevFlowDirectory, } from '../../targets/claude-code/claude-paths.js';
@@ -67,7 +73,7 @@ export function resolveComplianceCliAction(current, action, setFrameworks) {
                 messages: [
                     {
                         level: 'success',
-                        text: 'Compliance disabled — rule removed, frameworks remembered for re-enable',
+                        text: 'Compliance disabled — the rule and every posting step removed, frameworks remembered for re-enable',
                     },
                 ],
             };
@@ -118,10 +124,12 @@ async function skillInstalled(claudeDir) {
         return false;
     }
 }
+/** The installed compliance rule file. */
+const complianceRuleFile = (claudeDir) => path.join(claudeDir, 'rules', 'devflow', 'compliance.md');
 /** Returns true if the compliance rule file exists at the install target. */
 async function ruleInstalled(claudeDir) {
     try {
-        await fs.access(path.join(claudeDir, 'rules', 'devflow', 'compliance.md'));
+        await fs.access(complianceRuleFile(claudeDir));
         return true;
     }
     catch {
@@ -156,10 +164,146 @@ async function skillShadowState(devflowDir) {
         return 'none';
     }
 }
+/** The `Posting:` line of `--status`: the install record read against the machine's compliance switch (AC-31). */
+export function postingStatusLine(record, complianceEnabled) {
+    const status = postingStatus(readInstalledVariants(record), complianceEnabled);
+    const shown = status === 'installed' ? color.green(status) : status === 'not installed' ? color.dim(status) : color.yellow(status);
+    return `Posting:    ${shown}`;
+}
+/**
+ * Write the switch under the manifest lock, into the manifest read inside the lock, so a field
+ * that another devflow run wrote since this command first read the manifest is kept. A lock that
+ * cannot be taken, or is lost before the write, writes nothing. Null when the switch is on disk,
+ * otherwise the reason it is not. Never throws.
+ */
+async function recordComplianceSwitch(devflowDir, nextState) {
+    try {
+        const locked = await withManifestLock(devflowDir, {}, async (lock) => {
+            const current = await readManifest(devflowDir);
+            if (current === null)
+                return 'no readable install manifest';
+            if (!(await lock.stillHeld()))
+                return 'the install manifest lock was lost';
+            await writeManifest(devflowDir, {
+                ...current,
+                features: { ...current.features, compliance: nextState },
+                updatedAt: new Date().toISOString(),
+            });
+            return null;
+        });
+        return locked.ok ? locked.value : 'the install manifest lock could not be taken';
+    }
+    catch (err) {
+        return String(err);
+    }
+}
+/**
+ * Apply one change of the compliance switch: write the switch, run the one converge for both
+ * axes, and only after a clean converge record which variants are installed (the toggle helper
+ * does that last step). Every change of the enabled value converges, `--set` and interactive enable
+ * included, and a `--set` that only changes the frameworks converges too, so the stamp follows.
+ *
+ * Fail closed on the off side: with compliance off, a converge that cannot prove every installed
+ * compliance-armed prompt holds the compliance-off file is an error that lists the files, a
+ * toggle that cannot converge at all (a version skew, or no manifest) says that posting steps remain
+ * installed until `devflow init`, and a compliance rule that is still installed is an error that
+ * names the file. None of them prints the success text. A skipped prompt converge still converges
+ * the compliance skill and rule, which do not depend on the installed version. On the enable side
+ * the skip is a warning, and a rule that is wanted and still not installed is a second warning.
+ * A reference that the converge could not refresh, a linked folder for example, is an error that
+ * names it, with exit 1, and the switch stays recorded as on.
+ *
+ * Returns a result and never throws; the caller prints the messages and sets the exit code.
+ */
+export async function applyComplianceChange(opts) {
+    const { claudeDir, devflowDir, manifest, action, setFrameworks, runningVersion, packageRoot, warn } = opts;
+    const resolved = resolveComplianceCliAction(manifest.features.compliance, action, setFrameworks);
+    // normalizeFrameworks deduplicates (e.g. --set gdpr,GDPR → [gdpr]).
+    const nextState = {
+        enabled: resolved.nextState.enabled,
+        frameworks: normalizeFrameworks(resolved.nextState.frameworks),
+    };
+    // The switch comes first: whatever the converge does next, the machine's choice is on disk.
+    const notRecorded = await recordComplianceSwitch(devflowDir, nextState);
+    if (notRecorded !== null) {
+        return {
+            nextState: manifest.features.compliance,
+            messages: [{ level: 'error', text: `Could not record the compliance switch, so nothing was changed: ${notRecorded}` }],
+            exitCode: 1,
+        };
+    }
+    const outcome = await applyVariantToggle({
+        claudeDir,
+        devflowDir,
+        axis: 'compliance',
+        enabled: nextState.enabled,
+        runningVersion,
+        warn,
+        packageRoot,
+    });
+    if (outcome.kind === 'skipped') {
+        // The compliance skill and rule do not depend on the installed version, so they converge
+        // whatever the prompt converge did. The converge warns per item and never throws.
+        await convergeFromManifest({
+            claudeDir,
+            devflowDir,
+            manifest: { features: { compliance: nextState, rules: manifest.features.rules } },
+            warn,
+        });
+        if (!nextState.enabled) {
+            return { nextState, messages: [{ level: 'error', text: outcome.message }], exitCode: 1 };
+        }
+        const ruleNote = manifest.features.rules && !(await ruleInstalled(claudeDir))
+            ? [{ level: 'warn', text: 'The compliance rule was not installed. Run `devflow init`.' }]
+            : [];
+        return { nextState, messages: [...resolved.messages, ...ruleNote, { level: 'warn', text: outcome.message }], exitCode: 0 };
+    }
+    const { posting } = outcome.result;
+    if (!nextState.enabled && posting.kind !== 'clear') {
+        return {
+            nextState,
+            messages: [
+                { level: 'error', text: 'Compliance is recorded as off, but the install may still post to GitHub or a tracker.' },
+                ...describePostingLeft(posting).map((text) => ({ level: 'error', text })),
+            ],
+            exitCode: 1,
+        };
+    }
+    // A failed rule removal is only a warning inside the converge. The line that says the rule is
+    // removed prints only when it is gone.
+    if (!nextState.enabled && (await ruleInstalled(claudeDir))) {
+        return {
+            nextState,
+            messages: [{
+                    level: 'error',
+                    text: `Compliance is recorded as off, but the compliance rule could not be removed: ${complianceRuleFile(claudeDir)}. ` +
+                        'Fix the cause in the warning above, or delete the file. Then run `devflow compliance --disable` again.',
+                }],
+            exitCode: 1,
+        };
+    }
+    const referenceFailures = outcome.result.references.failures;
+    if (nextState.enabled && referenceFailures.length > 0) {
+        return {
+            nextState,
+            messages: [{
+                    level: 'error',
+                    text: 'Compliance is recorded as on, but some installed references were not refreshed: ' +
+                        `${referenceFailures.join('; ')}. Replace any link in the cause with a real folder. Then run the command again.`,
+                }],
+            exitCode: 1,
+        };
+    }
+    const messages = [...resolved.messages];
+    const changed = describeVariantConverge(outcome.result, 'compliance', nextState.enabled);
+    if (changed !== null)
+        messages.push({ level: 'info', text: `Installed prompts: ${changed}` });
+    return { nextState, messages, exitCode: 0 };
+}
 export const complianceCommand = new Command('compliance')
     .description('Enable, disable, or configure the compliance feature')
-    .option('--enable', 'Enable compliance (restores previously selected frameworks)')
-    .option('--disable', 'Disable compliance (rule removed; frameworks remembered for re-enable)')
+    .option('--enable', 'Enable compliance (restores previously selected frameworks and installs the steps that post evidence and summaries to GitHub or a tracker)')
+    .option('--disable', 'Disable compliance (rule and every step that posts evidence or summaries to GitHub or a tracker removed; frameworks remembered for re-enable)')
     .option('--status', 'Show compliance state: manifest, installed artifacts, shadow presence, and the evidence policy for the current repository')
     .option('--set <list>', 'Set active frameworks (comma-separated IDs); enables compliance. Use --set "" for zero frameworks (generic controls only)')
     .action(async (options) => {
@@ -169,8 +313,8 @@ export const complianceCommand = new Command('compliance')
     if (!hasFlag) {
         p.intro(color.bgCyan(color.white(' Compliance ')));
         const validIds = COMPLIANCE_FRAMEWORKS.map(fw => `${fw.id} — ${fw.hint}`).join('\n  ');
-        p.note(`${color.cyan('devflow compliance --enable')}   Enable compliance (restores prior frameworks)\n` +
-            `${color.cyan('devflow compliance --disable')}  Disable compliance (frameworks remembered)\n` +
+        p.note(`${color.cyan('devflow compliance --enable')}   Enable compliance (restores prior frameworks; installs the posting steps)\n` +
+            `${color.cyan('devflow compliance --disable')}  Disable compliance (removes the posting steps; frameworks remembered)\n` +
             `${color.cyan('devflow compliance --status')}   Show current state and installed artifacts\n` +
             `${color.cyan('devflow compliance --set <ids>')} Set active frameworks and enable\n\n` +
             `Valid framework IDs:\n  ${validIds}`, 'Usage');
@@ -228,6 +372,7 @@ export const complianceCommand = new Command('compliance')
                     ? color.yellow(' (withheld — rules disabled)')
                     : '') +
                 (isRuleShadowed ? color.green(' [shadowed]') : ''),
+            postingStatusLine(manifest.installedVariants, current.enabled),
             '',
             // The repository in cwd, resolved by the package's own resolver with the
             // compliance state already read above (D-POLICY-CJS-SEAM). Bounded: at most
@@ -277,23 +422,18 @@ export const complianceCommand = new Command('compliance')
     else {
         action = 'disable';
     }
-    const resolved = resolveComplianceCliAction(current, action, setFrameworks);
-    // Converge artifacts (always converge, never short-circuit)
-    await convergeFromManifest({
+    // Write the switch, converge both axes, record the installed variants (applyComplianceChange).
+    const applied = await applyComplianceChange({
         claudeDir,
         devflowDir,
-        manifest: { features: { compliance: resolved.nextState, rules: manifest.features.rules } },
+        manifest,
+        action,
+        setFrameworks,
+        runningVersion: await readRunningVersion(),
         warn: (msg) => p.log.warn(msg),
     });
-    // Persist to manifest — normalizeFrameworks deduplicates (e.g. --set gdpr,GDPR → [gdpr])
-    manifest.features.compliance = {
-        enabled: resolved.nextState.enabled,
-        frameworks: normalizeFrameworks(resolved.nextState.frameworks),
-    };
-    manifest.updatedAt = new Date().toISOString();
-    await writeManifest(devflowDir, manifest);
     // Emit messages
-    for (const msg of resolved.messages) {
+    for (const msg of applied.messages) {
         switch (msg.level) {
             case 'success':
                 p.log.success(msg.text);
@@ -301,18 +441,25 @@ export const complianceCommand = new Command('compliance')
             case 'warn':
                 p.log.warn(msg.text);
                 break;
+            case 'error':
+                p.log.error(msg.text);
+                break;
             default:
                 p.log.info(msg.text);
                 break;
         }
     }
-    if (resolved.nextState.enabled && !manifest.features.rules) {
+    if (applied.exitCode !== 0) {
+        process.exitCode = applied.exitCode;
+        return;
+    }
+    if (applied.nextState.enabled && !manifest.features.rules) {
         p.log.info(color.dim('Note: compliance rule withheld (rules disabled) — ' +
             'run `devflow rules --enable` to install the stamped rule'));
     }
     // Suggest the team file compliance now implies. Printed, never written:
     // .devflow/project.json is team-owned (D-POLICY-NO-WRITE).
-    if (resolved.nextState.enabled) {
+    if (applied.nextState.enabled) {
         const policyModule = loadEvidencePolicyModule();
         const settingsModule = loadSettingsModule();
         if (!policyModule.ok) {
@@ -322,7 +469,7 @@ export const complianceCommand = new Command('compliance')
             p.log.warn(formatEvidencePolicyUnavailable(settingsModule.error));
         }
         else {
-            const suggestion = evidencePolicySuggestion(resolved.nextState, policyModule.value, settingsModule.value);
+            const suggestion = evidencePolicySuggestion(applied.nextState, policyModule.value, settingsModule.value);
             if (suggestion !== null)
                 p.note(suggestion, 'Evidence policy');
         }