devflow-kit 3.6.0 → 3.7.0

package/CHANGELOG.md

@@ -5,6 +5,84 @@ All notable changes to Devflow will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.7.0] - 2026-10-16
+
+### Upgrade notes — Gate level
+
+The settings line has a new last field for the gate level ([#472](https://github.com/dean0x/devflow/issues/472)).
+Do the step below after you update.
+
+**What you must do:**
+- Run `devflow init` after you update. A full init installs the commands that accept the new settings line.
+- After `devflow init`, a user with no level gets `standard` in `/code-review`: no TypeScript focus, and no Dependencies focus on a code diff that changes no dependency manifest. Run `devflow gates --set full` to keep today's set.
+- A user with no level also gets the lean `/plan`: fewer agents, while the security gap analysis and the design review still run. Run `devflow gates --set full` to keep the full `/plan`.
+
+**Stale-install window:**
+- The settings line now ends with `GATE_LEVEL=<full|standard|lean>`. An installed command from an
+  older version accepts only the old fields, so it does not accept the longer line.
+- `devflow init --hud-only` and a plugin-only update refresh the resolver script. They do not
+  refresh the installed prompts.
+- Until you run a full `devflow init`, every installed command uses its fail-closed settings value.
+- Until you run `devflow init`, the installed `/code-review` and `/plan` ignore the level.
+
+**Known limits:**
+- A corrupt manifest, or one over 1 MiB, reads as the `standard` level. `devflow gates --status`
+  warns that `devflow init` will replace the file.
+- `devflow init` still overwrites a corrupt or rejected manifest. The stored level is lost with it.
+- Two commands that write the manifest at the same moment can lose one update.
+- There is no team floor. A repository that declares compliance can run a lower personal level.
+  `/code-review` and `/plan` read the level, so a personal `lean` level narrows the review and the
+  planning run even where compliance is declared. The Compliance focus still runs on its trigger,
+  and in `/plan` the security gap focus and the design review run at every level.
+  Issue [#488](https://github.com/dean0x/devflow/issues/488) (the compliance lens as a floor on
+  the level) is open.
+
+### Upgrade notes — Working memory
+
+The memory worker's write is limited to its staged file. Read the items below after you update.
+
+**What you must do:**
+- Update Claude Code to 2.1.269 or newer. On an older version, working memory does not update and Claude Code shows no message. The worker log has one line that says why.
+- If a worker `env` value lives only in your project or local Claude Code settings, move it to your user settings file. The worker loads only the user settings.
+
+**Your own settings:**
+- Allow rules in your own Claude Code settings also apply to the worker's run. A user-level Edit allow rule that covers other paths covers the worker too.
+
+**Known limits:**
+- A project path that contains any of `* ? [ ] \ " { }` or a control character gets no working-memory updates. The permission rule carries the path without quoting. The worker skips the project, logs the reason and shows one message at session start. Parentheses and spaces in the path are carried as they are.
+
+### Added
+
+- **A gate level on the settings line, and the `devflow gates` command** ([#472](https://github.com/dean0x/devflow/issues/472)). The settings line ends with `GATE_LEVEL=<full|standard|lean>`. The level comes from a personal `gateLevel` key in `.devflow/config.json`, then from the machine default `features.gateLevel` in `~/.devflow/manifest.json`, then from `standard`. The personal key may raise or lower the level. It is not a narrow-only switch, and a later change can make it narrow-only. A `gateLevel` in `project.json` is ignored, and no command writes the personal key. A malformed value reads as `full`. `devflow gates --set <level>` writes the machine default and nothing else. `devflow gates --status` shows the level in effect, the layer that decided it and the machine default. `/code-review` reads the level ([#474](https://github.com/dean0x/devflow/issues/474)) and so does `/plan` ([#473](https://github.com/dean0x/devflow/issues/473)); [#480](https://github.com/dean0x/devflow/issues/480) adds more readers.
+- **`devflow init --hud-only` prints a line when the installed prompts come from another devflow version** ([#472](https://github.com/dean0x/devflow/issues/472)). It tells you to run `devflow init`.
+- **A message at session start when working memory stops for a cause you can fix.** If the worker cannot write its staged file at the project path (for example, a path with a character the permission rule cannot carry), or Claude Code refuses the worker's write in two runs with no successful update between them, the next session start shows one message that points to the log. Each cause is shown once.
+
+### Changed
+
+- **`/code-review` picks its focus set by gate level** ([#474](https://github.com/dean0x/devflow/issues/474)). `full` runs every focus, as before. `standard`, the default, drops TypeScript, and drops Dependencies on a code diff that changes no dependency manifest (a lockfile alone does not count). `lean` runs Security, Testing and Reliability on a code diff. The Compliance focus keeps its own trigger at every level. A docs-only, tests-only or lockfile-only diff keeps its reduced set, and at `lean` a tests-only diff drops Consistency. A mixed non-code diff runs the union of its classes' sets. Security runs at every level and in every class. `/code-review` reads a new level reference only at `standard` or `lean`. If it cannot read the reference, it says so and runs the full sets. The review summary now shows the gate level and the focuses, and a review with no security report gives CHANGES REQUESTED.
+- **`/plan` runs a lean shape at `standard` and `lean`** ([#473](https://github.com/dean0x/devflow/issues/473)). `full` runs the phases as before. `standard`, the default, and `lean` run one Explore round of two agents (three for several issues), or none when a `/research` report from the same conversation covers the scope; no Synthesize step; two gap-analysis agents, one for security and one for completeness, architecture and performance (plus consistency and dependencies for several issues); one Plan agent; and the design review. The security gap agent and the design review run at every level, the Compliance agent keeps its own trigger, and Gates 0, 1 and 2 run at every level. Every agent spawn in `/plan` names its agent type; the planning spawns use Claude Code's built-in `Plan` agent. If `/plan` cannot read its level reference, it says so and runs the full shape. The run report names the gate level. Run `devflow gates --set full` to keep the full shape.
+- **`/implement` splits long plans into sequential Code phases; a run with no plan stays single** ([#452](https://github.com/dean0x/devflow/issues/452)).
+- **Code agents read large files once, by range, and cap printed output** ([#452](https://github.com/dean0x/devflow/issues/452)).
+- **Polish, Harden, Evaluate and Test get the full branch diff as `FILES_CHANGED`** ([#452](https://github.com/dean0x/devflow/issues/452)).
+- **`/implement` stops when the base branch name has a character outside ASCII letters, digits and `._/+@,#-`, or is longer than 200** ([#452](https://github.com/dean0x/devflow/issues/452)). The check also covers the re-validation path. Git accepts some refused names, such as `café`. For them, `/implement` stops and tells the user which characters are allowed.
+- **The token audit counts files written through Bash** ([#442](https://github.com/dean0x/devflow/issues/442)).
+- **The memory worker's write is limited to its staged file.** The `claude -p` run loads only your own Claude Code settings plus two permission rules, an allow rule for `.devflow/memory/WORKING-MEMORY.md.new` and a deny rule for every path under it, and a permission mode that refuses every call that no allow rule covers. Allow rules in your own Claude Code settings also apply to the run, so a user-level Edit allow rule that covers other paths covers the worker too. A folder or a link at the staged path is removed by one guarded delete of exactly that path; when it cannot be removed, the run fails and removes nothing. The worker ignores a project's or a local Claude Code settings file.
+- **Working memory needs Claude Code 2.1.269 or newer.** `devflow init` states the version at its working-memory step. On an older Claude Code the worker does not run, keeps the queue and writes one log line that says why, so working memory does not update until you update Claude Code.
+- **The memory log gets one `Run:` line for each worker run.** `.background-memory-update.log` under `~/.devflow/logs/`, in the folder for the session that ran the worker (`<session-directory-slug>`), ends every run with `Run: cli=<version|unknown> argv=<lean|legacy|none> result=<updated|conflict|failed|skip|below-floor> denials=<count|unknown|n/a> removed=<none|dir|link>`. `cli=unknown` means the worker read no version, `denials=unknown` means the result reported no count, and `denials=n/a` means no run started. A below-floor line adds `floor=<version>`. The line holds keywords and digits only, never turn or prompt text.
+- **A project inside a `.git` folder gets no working-memory update.** The worker skips it, logs the reason and shows the path message once at session start. A checkout under `.claude/worktrees` is updated like any other checkout.
+- **PR links and `/dynamic-build` ticket branches follow stricter rules** ([#486](https://github.com/dean0x/devflow/issues/486)). `/implement` prints `TRACEABILITY: DEGRADED (ambiguous issue reference)` when it has an issue number and no link line. `/code-review` and `/bug-analysis` PRs no longer get a closing line from the branch name. A PR body has no `## Related Issues` heading when neither an issue number nor a link line is given. In a `/dynamic-build` wave, the ticket branch must be a local branch name that passes the allowlist. A name with a leading `#` or `-`, a revision name such as `HEAD`, a tag and a SHA are all refused, and the ticket is quarantined. The wave aborts the merge only when the merge began. On Jira and Linear, the PR link line always uses the default reference form (`Refs {KEY}-{n}`). A custom `## Reference Rendering` section no longer shapes that line. It still shapes the release Shipped Issues section. Follow-up [#511](https://github.com/dean0x/devflow/issues/511) tracks applying it to the PR link line.
+
+### Fixed
+
+- **Prompts resolve the Claude config directory with the same rule as the installer** ([#517](https://github.com/dean0x/devflow/pull/517)). `CLAUDE_CONFIG_DIR` applies when it is an absolute path, else `~/.claude`.
+- **A tracked `.devflow/config.json` no longer applies as personal config** ([#489](https://github.com/dean0x/devflow/pull/489)). devflow ignores it and shows a warning.
+- **`/dynamic-build` wave merges are safer, and a supplied PR link line is used as given** ([#486](https://github.com/dean0x/devflow/issues/486)). A wave merge uses `git merge --no-ff` and records the pre-merge SHA. The ticket branch name is checked before the merge, and a refused name quarantines that ticket. The wave halts when the merge or base SHA is not valid. A ticket whose branch adds no commit stops the wave before the post-merge build, and no wave PR opens. A merge whose post-merge build fails is undone by a reset to the recorded SHA. The run summary names why the wave halted. A PR gets no closing reference from a bare number or the branch name.
+- **Model discovery waits up to 6 s for the routing runtime** ([#519](https://github.com/dean0x/devflow/pull/519)). The wait was 2 s. On a loaded machine, the first start of node with the routing runtime can take more than 2 s. The agents TUI then reported an installed runtime as unknown. `devflow proxy --enable` then did not refresh the model cache. A runtime that does not answer within 6 s still falls back to the stale cache.
+- **The memory worker keeps the queue when it finds neither jq nor node** ([#523](https://github.com/dean0x/devflow/issues/523)). The hooks that start the worker already stop without a parser. A worker that ran with a different PATH deleted the queued turns. Now the worker stops before it reads the queue, and the queue stays for the next run. A parser that exits with an error also leaves the queue and the batch in place, and a queue that cannot be added to a leftover batch stays in its file.
+- **A malformed queue line no longer stops the worker from reading the other lines** ([#528](https://github.com/dean0x/devflow/issues/528)). With jq, the worker read the queue as one stream, so one malformed line stopped the parse. The valid turns after it were lost, or the whole batch was deleted. Now the worker reads each line alone, skips only the malformed line, and logs how many lines in the read window it skipped. A row cut off before its line break runs into the next row, so those two rows are one malformed line. Both parsers read a line as a turn only when its role is user, assistant or qa, so jq and node log the same skip count. A batch with no readable line is still removed.
+
+---
+
 ## [3.6.0] - 2026-10-14
 
 ### Upgrade notes — Agent rename (6 agents)
@@ -1673,7 +1751,8 @@ devflow init
 
 ---
 
-[Unreleased]: https://github.com/dean0x/devflow/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/dean0x/devflow/compare/v3.7.0...HEAD
+[3.7.0]: https://github.com/dean0x/devflow/compare/v3.6.0...v3.7.0
 [3.6.0]: https://github.com/dean0x/devflow/compare/v3.5.0...v3.6.0
 [3.5.0]: https://github.com/dean0x/devflow/compare/v3.4.0...v3.5.0
 [3.4.0]: https://github.com/dean0x/devflow/compare/v3.3.0...v3.4.0

package/README.md

@@ -56,7 +56,7 @@ This is the **orchestrated flow** — you stay in the loop between every step. W
 
 **A staffed agent roster.** 20 specialized agents with explicit model assignments — Opus for analysis, Sonnet for execution, Haiku for I/O. Reassign any agent's model with `devflow agents`, including GPT models through external model routing (`devflow proxy`).
 
-**Up to 20 parallel Review agents.** Security, architecture, performance, complexity, consistency, regression, testing, and more. Each produces findings with severity, confidence scoring, and concrete fixes. Conditional Review agents activate when relevant (TypeScript for `.ts` files, database for schema changes, compliance when regulated surface detected in the diff). Every finding gets validated and resolved automatically.
+**Up to 20 parallel Review agents.** Security, architecture, performance, complexity, consistency, regression, testing, and more. Each produces findings with severity, confidence scoring, and concrete fixes. Conditional Review agents activate when relevant (language focuses such as TypeScript for `.ts` files, database for schema changes, compliance when regulated surface detected in the diff). The gate level narrows these sets: the default `standard` level drops the TypeScript focus, and `lean` runs fewer focuses still. Every finding gets validated and resolved automatically.
 
 **Memory that persists.** Session context survives restarts, `/clear`, and context compaction. Your agent picks up exactly where it left off.
 
@@ -200,7 +200,9 @@ A repository can commit `.devflow/project.json` to settle team-wide choices. Eve
 
 Each key is checked on its own, so one bad value never disables the rest: a bad `evidence` resolves to `required`, a bad `reviewPublication` to `off`, a bad `compliance` list to the generic lens. A `project.json` or `config.json` that exists but is not a JSON object is never read as absent: the settings fail closed (publication off, knowledge write-back off, the tracker reported as invalid). The compliance lens is the exception, because it only adds scrutiny: it keeps every framework a readable layer declares, and an unreadable `project.json` counts as the generic lens. Memory and learning capture fail open instead: the hooks read an unreadable file as narrowing nothing, so capture runs as your machine's switch says.
 
-`config.json` is personal, so it must not be committed. A `config.json` that git tracks is ignored as if it were absent — otherwise a branch could commit `"reviewPublication":"full"` for whoever reviews it — and `devflow tracker|memory|learning|knowledge --status` say so, with the fix: `git rm --cached .devflow/config.json`. Commands never read the file themselves — one local resolver folds it with your `config.json` and the machine settings, without touching the network.
+`config.json` is personal, so it must not be committed. A `config.json` that git tracks is ignored as if it were absent — otherwise a branch could commit `"reviewPublication":"full"` for whoever reviews it — and `devflow tracker|memory|learning|knowledge|gates --status` say so, with the fix: untrack the tracked entry with `git rm --cached`, then check or delete the file, because untracking leaves the committed bytes on disk as your personal file. Commands never read the file themselves — one local resolver folds it with your `config.json` and the machine settings, without touching the network.
+
+**Gate level.** The gate level (`full`, `standard` or `lean`) is not a narrow-only switch: your personal `.devflow/config.json` may carry a top-level `"gateLevel"` key that raises or lowers the machine default, `devflow gates --set <level>` sets the machine default in `~/.devflow/manifest.json`, and `standard` applies when neither is set. A `gateLevel` in `project.json` is ignored, and no command writes the personal key. A malformed value reads as `full`. `/code-review` and `/plan` read the level: `standard` and `lean` run fewer review focuses and fewer planning agents. The security checks and, in `/plan`, the design review run at every level. The compliance gap agent runs on its own trigger at every level. Run `devflow gates --set full` to keep the full `/plan` shape; issue #480 adds more readers. After updating, run `devflow init`. See the [CLI reference](https://github.com/dean0x/devflow/blob/main/docs/cli-reference.md#gate-level).
 
 ## Evidence policy
 
@@ -286,6 +288,8 @@ npx devflow-kit compliance --status     # Show compliance state and this repo's
 npx devflow-kit tracker --set jira       # Pick the machine's default tracker (github | jira | linear)
 npx devflow-kit tracker --status         # Show provider, this repo's effective one, learned conventions, mechanics
 npx devflow-kit tracker --servers default # Tracker servers the agents may call (comma-separated names, or default)
+npx devflow-kit gates --set lean         # Set the machine's default gate level (full | standard | lean)
+npx devflow-kit gates --status          # Show the gate level in effect here and which layer decided it
 npx devflow-kit rules --status          # Show installed rules
 npx devflow-kit security --status       # Show / manage the security deny list
 npx devflow-kit safe-delete --enable    # Install rm -> trash safe-delete

package/dist/agents/code.md

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

package/dist/agents/fix.md

@@ -118,11 +118,11 @@ Run builds, typechecks, lints and tests in the foreground, each with an explicit
 
 ## Principles
 
-1. **Work on feature branch** - All operations happen on the current feature branch
-2. **Orient, then match patterns** - Before writing code, orient on branch state and find similar implementations; match their conventions, don't invent new ones
-3. **Be decisive** - Make confident implementation choices. Don't present alternatives or ask permission for tactical decisions
-4. **Small, focused changes** - Don't scope creep beyond the plan
-5. **Fail honestly** - If blocked, report clearly with what was completed
+1. **Read once** - Never re-read an unchanged file. For a file over 400 lines, or a second look, `grep -n` first, then Read only that range (`offset`, `limit`)
+2. **Small, focused changes** - Don't scope creep beyond the plan
+3. **Fail honestly** - If blocked, report clearly with what was completed
+
+- Never print a large file whole; page it with offset and limit, and cap any output you print. Before printing search matches, list or count them.
 
 ## Output
 
@@ -162,4 +162,3 @@ Report cap: final message at most about 1,500 tokens; longer material goes to a
 - Switch branches during implementation
 - Push to branches other than your feature branch
 - Merge PRs (orchestrator handles this)
-- Trust handoff summaries without reading actual code

package/dist/agents/refactor.md

@@ -86,11 +86,11 @@ Run builds, typechecks, lints and tests in the foreground, each with an explicit
 
 ## Principles
 
-1. **Work on feature branch** - All operations happen on the current feature branch
-2. **Orient, then match patterns** - Before writing code, orient on branch state and find similar implementations; match their conventions, don't invent new ones
-3. **Be decisive** - Make confident implementation choices. Don't present alternatives or ask permission for tactical decisions
-4. **Small, focused changes** - Don't scope creep beyond the plan
-5. **Fail honestly** - If blocked, report clearly with what was completed
+1. **Read once** - Never re-read an unchanged file. For a file over 400 lines, or a second look, `grep -n` first, then Read only that range (`offset`, `limit`)
+2. **Small, focused changes** - Don't scope creep beyond the plan
+3. **Fail honestly** - If blocked, report clearly with what was completed
+
+- Never print a large file whole; page it with offset and limit, and cap any output you print. Before printing search matches, list or count them.
 
 ## Output
 
@@ -130,4 +130,3 @@ Report cap: final message at most about 1,500 tokens; longer material goes to a
 - Switch branches during implementation
 - Push to branches other than your feature branch
 - Merge PRs (orchestrator handles this)
-- Trust handoff summaries without reading actual code

package/dist/agents/review.md

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

package/dist/cli/commands/gates.js

@@ -0,0 +1,276 @@
+/**
+ * devflow gates — Show or set the machine's default gate level.
+ *
+ * The gate level is one of `full`, `standard` or `lean`. `--set` writes the MACHINE
+ * default, `features.gateLevel` in `~/.devflow/manifest.json`, and nothing else: not
+ * the repository's `project.json`, not the personal `.devflow/config.json` (no
+ * command writes that key), and no sentinel, re-arm or install step. `--status` shows
+ * the level that applies in the current directory, which layer decided it and what
+ * the machine records; it writes nothing.
+ *
+ * Three parts, so no business logic throws or prints:
+ *   gatherGateStatus   resolves the settings ONCE and reads the manifest raw, and
+ *                      returns a {@link GateStatus} that is a discriminated union
+ *   renderGateStatus   pure: one {@link GateStatus} to lines and warnings
+ *   gatesCommand       the thin shell: parse, call, print, set the exit code
+ *
+ * No code here chooses a level from a task or a diff: the level comes from the
+ * resolver (personal key, machine key, default) or from the word typed after `--set`.
+ */
+import { Command } from 'commander';
+import * as path from 'path';
+import * as p from '@clack/prompts';
+import color from 'picocolors';
+import { DEFAULT_GATE_LEVEL, GATE_LEVELS, machineGateLevel, parseGateLevel, readGateManifest, writeMachineGateLevel, } from '../../core/gate-level.js';
+import { describeEchoedValue } from '../../core/echo-value.js';
+import { loadSettingsModule, settingsSourceFile, trackedConfigWarning, } from '../../core/evidence-policy.js';
+import { getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
+// ── Wording ────────────────────────────────────────────────────────────────────
+/**
+ * What each level means, in one line. Each line says what the word stands for and
+ * not what a command does with it.
+ */
+export const GATE_LEVEL_MEANINGS = Object.freeze({
+    full: 'the most checking; any value that is not a level also reads as full',
+    standard: 'the default when no level is set',
+    lean: 'the least checking',
+});
+/** What reads the level today; each later reader updates this text. */
+export const GATE_LEVEL_EFFECT = '/code-review and /plan read the level: standard and lean run fewer review focuses and fewer planning agents. Other commands read it once issue #480 lands.';
+const MACHINE_MANIFEST_NAME = 'manifest.json';
+const MACHINE_INVALID_LINE = `invalid (${MACHINE_MANIFEST_NAME}; reads as full)`;
+const VALID_LEVELS = GATE_LEVELS.join(', ');
+const VALID_LEVELS_OR = `${GATE_LEVELS.slice(0, -1).join(', ')}, or ${GATE_LEVELS[GATE_LEVELS.length - 1]}`;
+/** The resolved settings, or null when the resolver is unusable or throws despite its contract. */
+function resolveOnce(module, dir) {
+    try {
+        return module.resolveSettings({ dir });
+    }
+    catch {
+        return null;
+    }
+}
+function manifestState(read) {
+    switch (read.kind) {
+        case 'absent': return 'absent';
+        case 'object': return 'readable';
+        case 'corrupt':
+        case 'rejected': return 'unreadable';
+        default: {
+            const exhaustive = read;
+            return exhaustive;
+        }
+    }
+}
+/** Why a fail-closed result failed, or null when the resolver names no reason. */
+function failClosedReason(settings) {
+    return settings.unreadable === null ? null : `${settingsSourceFile(settings.unreadable)} is unreadable`;
+}
+/**
+ * Gather one {@link GateStatus}. Never throws, never writes.
+ *
+ * The settings resolve ONCE, and that one result feeds the level, the machine value
+ * and the tracked-config warning. The manifest is read with the gate reader, never
+ * with `readManifest()`, which heal-writes and returns null for a manifest it
+ * rejects: a read-only status must do neither. The manifest is read twice, once by
+ * the gate reader here and once by the resolver; a write between the two reads can
+ * mix two versions, which is acceptable because the result is display only and no
+ * action follows it.
+ */
+export async function gatherGateStatus(deps) {
+    const manifestPath = path.join(deps.devflowDir, MACHINE_MANIFEST_NAME);
+    const read = await deps.readManifest(deps.devflowDir);
+    const base = { manifest: manifestState(read), manifestPath };
+    // The TypeScript reader's machine value, for a result that carries none of its own.
+    const stored = read.kind === 'object' || read.kind === 'rejected' ? machineGateLevel(read.raw) : null;
+    const loaded = deps.loadSettings();
+    const settings = loaded.ok ? resolveOnce(loaded.value, deps.dir) : null;
+    if (settings === null) {
+        return { ...base, kind: 'unloadable', machine: stored };
+    }
+    const trackedWarning = trackedConfigWarning(settings);
+    if (!settings.ok || settings.gateLevelSource === null) {
+        // Only a result that names an unreadable file carries the manifest's value; a
+        // fail-closed result without one (git did not answer) never read the manifest.
+        const machine = settings.unreadable !== null ? settings.gateLevelMachine : stored;
+        return { ...base, kind: 'fail-closed', reason: failClosedReason(settings), machine, trackedWarning };
+    }
+    return {
+        ...base,
+        kind: 'resolved',
+        level: settings.gateLevel,
+        source: settings.gateLevelSource,
+        invalid: settings.gateLevelInvalid,
+        machine: settings.gateLevelMachine,
+        trackedWarning,
+    };
+}
+/** The machine line: `none` when the manifest records no level or cannot be read (its own warning says which). */
+function machineLine(machine) {
+    if (machine === 'invalid')
+        return `Machine:   ${MACHINE_INVALID_LINE}`;
+    if (machine === null)
+        return 'Machine:   none';
+    return `Machine:   ${machine}`;
+}
+function manifestWarning(status) {
+    if (status.manifest !== 'unreadable')
+        return null;
+    return `Manifest at ${status.manifestPath} cannot be read as a manifest; devflow init will replace this file.`;
+}
+/**
+ * Render a {@link GateStatus}. Pure and total over every `kind`.
+ *
+ * A malformed level is reported by the layer that holds it and its state, never by
+ * its value: a raw config value never reaches a terminal.
+ */
+export function renderGateStatus(status) {
+    const warnings = [];
+    const lines = [];
+    switch (status.kind) {
+        case 'resolved': {
+            lines.push(`Effective: ${status.level} (${status.source}${status.invalid ? ', invalid' : ''})`);
+            lines.push(machineLine(status.machine));
+            if (status.invalid && status.source === 'personal') {
+                warnings.push(`gateLevel in ${settingsSourceFile('personal')} is not one of ${VALID_LEVELS}, so ${status.level} is in effect. ` +
+                    'The value is not shown.');
+            }
+            if (status.trackedWarning !== null)
+                warnings.push(status.trackedWarning);
+            break;
+        }
+        case 'fail-closed': {
+            lines.push(`Effective: full (fail-closed: ${status.reason ?? 'reason unknown'})`);
+            lines.push(machineLine(status.machine));
+            if (status.trackedWarning !== null)
+                warnings.push(status.trackedWarning);
+            break;
+        }
+        case 'unloadable': {
+            lines.push('Effective: level unknown');
+            lines.push(machineLine(status.machine));
+            warnings.push('The settings resolver could not be loaded, so the level that applies is unknown.');
+            break;
+        }
+        default: {
+            const exhaustive = status;
+            return exhaustive;
+        }
+    }
+    const fromManifest = manifestWarning(status);
+    if (fromManifest !== null)
+        warnings.push(fromManifest);
+    return { lines, warnings };
+}
+/**
+ * Map the writer's result to a message and an exit code. Pure and total. Every
+ * refusal exits 1 and says nothing was written, except a failed write, which names
+ * the path and the error code.
+ */
+export function describeGateWrite(result, level, manifestPath) {
+    switch (result.kind) {
+        case 'written':
+            return { kind: 'success', message: `Gate level: ${level}`, exitCode: 0 };
+        case 'unchanged':
+            return { kind: 'info', message: `Gate level: ${level} (unchanged)`, exitCode: 0 };
+        case 'not-installed':
+            return { kind: 'error', message: `No manifest found at ${manifestPath}. Run devflow init first.`, exitCode: 1 };
+        case 'unreadable':
+            return {
+                kind: 'error',
+                message: `Manifest at ${result.path} exists but cannot be read; nothing changed. Move it aside, then run devflow init.`,
+                exitCode: 1,
+            };
+        case 'write-failed':
+            return {
+                kind: 'error',
+                message: `Could not write the manifest at ${result.path} (${result.reason}); nothing changed.`,
+                exitCode: 1,
+            };
+        case 'invalid-level':
+            return {
+                kind: 'error',
+                message: `Unknown gate level: "${describeEchoedValue(level)}"; nothing changed. Valid levels: ${VALID_LEVELS}`,
+                exitCode: 1,
+            };
+        default: {
+            const exhaustive = result;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * Write the machine default and describe the result. Never throws. `now` is injected
+ * so a test fixes the `updatedAt` stamp.
+ */
+export async function runGatesSet(devflowDir, level, now = () => new Date().toISOString()) {
+    const result = await writeMachineGateLevel(devflowDir, level, now);
+    return describeGateWrite(result, level, path.join(devflowDir, MACHINE_MANIFEST_NAME));
+}
+function printOutcome(outcome) {
+    switch (outcome.kind) {
+        case 'success':
+            p.log.success(outcome.message);
+            break;
+        case 'info':
+            p.log.info(outcome.message);
+            break;
+        case 'error':
+            p.log.error(outcome.message);
+            break;
+        default: {
+            const exhaustive = outcome.kind;
+            return exhaustive;
+        }
+    }
+}
+function levelsHelp() {
+    const width = Math.max(...GATE_LEVELS.map(level => level.length));
+    return GATE_LEVELS.map(level => `  ${level.padEnd(width)}  ${GATE_LEVEL_MEANINGS[level]}`).join('\n');
+}
+export const gatesCommand = new Command('gates')
+    .description('Show or set the machine\'s default gate level')
+    .option('--status', 'Show the gate level in effect here, which layer decided it, and the machine default')
+    .option('--set <level>', `Set the machine's default gate level: ${VALID_LEVELS_OR}`)
+    .addHelpText('after', `\nGate levels:\n${levelsHelp()}\n\n` +
+    `The default is ${DEFAULT_GATE_LEVEL}. --set writes only the machine default. A personal .devflow/config.json ` +
+    '"gateLevel" overrides it in one repository; no command writes that key.\n' +
+    GATE_LEVEL_EFFECT)
+    .action(async (options) => {
+    const devflowDir = getDevFlowDirectory();
+    if (!options.status && options.set === undefined) {
+        p.intro(color.bgCyan(color.white(' Gates ')));
+        p.note(`${color.cyan('devflow gates --status')}       Show the gate level in effect here and the machine default\n` +
+            `${color.cyan('devflow gates --set <level>')}  Set the machine default\n\n` +
+            `Valid levels:\n${levelsHelp()}`, 'Usage');
+        p.outro(color.dim(GATE_LEVEL_EFFECT));
+        return;
+    }
+    // Validate --set before any I/O, even beside --status: a bad word is rejected,
+    // never repaired, and exits 1 as it does in `devflow tracker` and `devflow compliance`.
+    const parsed = options.set === undefined ? undefined : parseGateLevel(options.set);
+    if (parsed !== undefined && !parsed.ok) {
+        p.log.error(parsed.error);
+        process.exitCode = 1;
+        return;
+    }
+    // --status wins over a valid --set and writes nothing, mirroring `devflow tracker`.
+    // With neither flag the usage printed above, so no --set here means --status alone.
+    if (options.status || parsed === undefined) {
+        const status = await gatherGateStatus({
+            devflowDir,
+            dir: process.cwd(),
+            loadSettings: loadSettingsModule,
+            readManifest: readGateManifest,
+        });
+        const rendered = renderGateStatus(status);
+        p.note(rendered.lines.join('\n'), 'Gate Level Status');
+        for (const warning of rendered.warnings)
+            p.log.warn(warning);
+        return;
+    }
+    const outcome = await runGatesSet(devflowDir, parsed.value);
+    printOutcome(outcome);
+    process.exitCode = outcome.exitCode;
+});
+//# sourceMappingURL=gates.js.map

package/dist/cli/commands/init-seed.js

@@ -27,6 +27,7 @@ export const FEATURE_DEFAULTS = {
     behavior: false,
     compliance: { enabled: false, frameworks: [] },
     tracker: { provider: DEFAULT_TRACKER_PROVIDER },
+    gateLevel: undefined,
 };
 // ── Helpers ───────────────────────────────────────────────────────────────────
 /**
@@ -60,7 +61,11 @@ export function resolveSeedFeatures(manifest) {
     const memory = manifest?.features.memory ?? FEATURE_DEFAULTS.memory;
     const knowledge = manifest?.features.knowledge ?? FEATURE_DEFAULTS.knowledge;
     const learning = manifest?.features.learning ?? FEATURE_DEFAULTS.learning;
-    return { ambient, memory, hud, knowledge, learning, rules, proxy, behavior, compliance, tracker };
+    // The raw stored level, with no default operator: `??` would turn a stored `null`
+    // into the default, and init would then write the default over a value the
+    // fold reads as the strictest level.
+    const gateLevel = manifest?.features.gateLevel;
+    return { ambient, memory, hud, knowledge, learning, rules, proxy, behavior, compliance, tracker, gateLevel };
 }
 /**
  * Resolve the flag record for the init seed.
@@ -318,6 +323,9 @@ export function applyCliToggles(base, toggles) {
         behavior: toggles.behavior ?? base.behavior,
         compliance: toggles.compliance ?? base.compliance,
         tracker: toggles.tracker ?? base.tracker,
+        // No command-line flag names the gate level, so the seed's raw value passes
+        // through. Only `undefined` means "not specified": `null` is a value, not a gap.
+        gateLevel: toggles.gateLevel !== undefined ? toggles.gateLevel : base.gateLevel,
     };
 }
 //# sourceMappingURL=init-seed.js.map