devflow-kit 3.6.0 → 3.7.0

package/dist/commands/plan.md

@@ -5,8 +5,6 @@ description: Unified design planning - combines requirements discovery, gap anal
 
 Orchestrate design planning from requirements discovery through gap analysis to implementation design. Produces a machine-readable design artifact consumed by `/implement`.
 
-The orchestrator only spawns agents and gates — all analytical work is done by agents.
-
 ## Usage
 
 ```
@@ -38,8 +36,6 @@ Note: a bare digit run is a reference **only** under `github`, and that adjudica
 
 ## Clarification Gates
 
-**MANDATORY**: Three gates that must complete before proceeding.
-
 | Gate | Phase | Purpose |
 |------|-------|---------|
 | Gate 0 | Phase 1 | Requirements discovery before exploration |
@@ -109,7 +105,7 @@ If the user says "skip" or "just proceed" — skip remaining questions, present
 
 #### Phase 2: Orient + Load Decisions
 
-**Produces:** SKIM_CONTEXT, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES
+**Produces:** SKIM_CONTEXT, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES, GATE_LEVEL
 **Requires:** CONFIRMED_SCOPE
 
 **Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for — the repository root when the run has one worktree:
@@ -118,9 +114,9 @@ If the user says "skip" or "just proceed" — skip remaining questions, present
 node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off GATE_LEVEL=full` instead.
 
-The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+The accepted line is the only source of these values.
 
 Spawn Skim agent for codebase context:
 
@@ -238,10 +234,16 @@ A KB with no Rules section labels its entries `Rules ({section name}):` and give
 
 Pass `FEATURE_KNOWLEDGE` to Explore and Design agents. Pass `DECISIONS_CONTEXT` to Design agents only.
 
+**Gate level.** At `standard` or `lean`, once per run, run `d="${CLAUDE_CONFIG_DIR:-}"; case "$d" in /*) ;; *) d="$HOME/.claude" ;; esac; printf '%s\n' "$d"` in Bash and Read `<that directory>/skills/devflow:agent-references/references/commands/plan-levels.md` with the Read tool, and apply it to Phases 3-14.
+
+- No row or rule overrides the next two lines.
+- If the Read fails, or a row is missing or malformed, set `GATE_LEVEL` to `full` and say `level reference unreadable: full applied`.
+- Security runs as its own Design spawn, and the design review runs, at every level and on every Revise pass.
+
 #### Phase 3: Explore Requirements (Parallel)
 
 **Produces:** EXPLORE_OUTPUTS
-**Requires:** SKIM_CONTEXT
+**Requires:** SKIM_CONTEXT, GATE_LEVEL
 
 Spawn 4 `Agent(subagent_type="Explore")` agents **in a single message**, each with Skim agent context and `FEATURE_KNOWLEDGE: {feature_knowledge}` (from Phase 2). Include the instruction: "The FEATURE_KNOWLEDGE is a baseline — VALIDATE, EXTEND, and CORRECT it. For anything it already covers, cite its KB IDs (`{slug} KB-AP-n`) instead of restating the text. Focus on areas the feature knowledge doesn't cover and changes since it was last updated." Ask each agent for a final report of at most about 1,500 tokens: findings with file:line references, not file dumps.
 
@@ -257,8 +259,6 @@ Spawn 4 `Agent(subagent_type="Explore")` agents **in a single message**, each wi
 **Produces:** EXPLORATION_SYNTHESIS
 **Requires:** EXPLORE_OUTPUTS
 
-**WAIT** for Phase 3 to complete.
-
 ```
 Agent(subagent_type="Synthesize"):
 "Synthesize EXPLORATION outputs for: {feature/issues}
@@ -319,7 +319,7 @@ Focus: {completeness|architecture|security|performance|compliance|consistency|de
 DECISIONS_CONTEXT: {decisions_context}
 FEATURE_KNOWLEDGE: {feature_knowledge}
 {COMPLIANCE_FOCUS_DIRECTIVE}  (compliance focus only)
-Resolve `${CLAUDE_CONFIG_DIR:-$HOME/.claude}` in Bash, then Read `<that directory>/skills/devflow:gap-analysis/references/compliance.md` with the Read tool and apply it as your focus patterns.  (compliance focus only)
+Run `d="${CLAUDE_CONFIG_DIR:-}"; case "$d" in /*) ;; *) d="$HOME/.claude" ;; esac; printf '%s\n' "$d"` in Bash, then Read `<that directory>/skills/devflow:gap-analysis/references/compliance.md` with the Read tool and apply it as your focus patterns.  (compliance focus only)
 Artifacts:
   Feature/Issues: {feature description or issue bodies}
   Exploration synthesis: {Phase 4 output}
@@ -333,8 +333,6 @@ Cite evidence from provided artifacts."
 **Produces:** GAP_SYNTHESIS
 **Requires:** GAP_OUTPUTS
 
-**WAIT** for Phase 5 to complete.
-
 ```
 Agent(subagent_type="Synthesize"):
 "Synthesize GAP ANALYSIS outputs for: {feature/issues}
@@ -395,8 +393,6 @@ Spawn 4 `Agent(subagent_type="Explore")` agents **in a single message**, each wi
 **Produces:** IMPL_EXPLORATION_SYNTHESIS
 **Requires:** IMPL_EXPLORE_OUTPUTS
 
-**WAIT** for Phase 8 to complete.
-
 ```
 Agent(subagent_type="Synthesize"):
 "Synthesize IMPLEMENTATION EXPLORATION outputs for: {feature/issues}
@@ -410,7 +406,7 @@ Combine into: patterns to follow, integration points, reusable code, edge cases"
 **Produces:** PLAN_OUTPUTS
 **Requires:** IMPL_EXPLORATION_SYNTHESIS, GAP_SYNTHESIS
 
-Spawn 3 Plan agents **in a single message**, each with implementation exploration synthesis. Ask each agent for a final report of at most about 1,500 tokens: the plan itself, not a restatement of the exploration.
+Spawn 3 `Agent(subagent_type="Plan")` agents **in a single message**, each with implementation exploration synthesis. Ask each agent for a final report of at most about 1,500 tokens: the plan itself, not a restatement of the exploration.
 
 | Focus | Output |
 |-------|--------|
@@ -425,8 +421,6 @@ Implementation steps planner: include explicit gap mitigations (from Phase 6) in
 **Produces:** PLANNING_SYNTHESIS
 **Requires:** PLAN_OUTPUTS
 
-**WAIT** for Phase 10 to complete.
-
 ```
 Agent(subagent_type="Synthesize"):
 "Synthesize PLANNING outputs for: {feature/issues}
@@ -627,6 +621,7 @@ Display completion summary:
 - Issue URL (if created or enriched) — and any `TRACEABILITY: DEGRADED ({reason})` lines from the Git agent
 - Gap analysis summary (N blocking, M should-address)
 - Design review summary (N anti-patterns found, M mitigated in plan)
+- Gate level: {GATE_LEVEL}, with any level note
 - Suggested next step: `/implement {artifact-path}` or `/implement #{issue-number}`
 
 ---
@@ -670,13 +665,8 @@ Display completion summary:
 
 ## Principles
 
-1. **Orchestration only** — Command spawns agents, never does agent work itself
-2. **Three mandatory gates** — Gate 0 (understand), Gate 1 (scope+gaps), Gate 2 (plan+review); none may be skipped
-3. **Parallel execution** — Explore phases and gap analysis run in parallel; synthesis phases wait
-4. **Evidence-based gaps** — Every gap cites specific text; no speculation
-5. **Scope ruthlessly** — Small, focused plans ship faster; gate 1 enforces scope discipline
-6. **Strict delegation** — Never synthesize, analyze, or plan in main session; always spawn agents
-7. **Design artifacts are machine-readable** — `/implement` can consume the YAML frontmatter directly
+1. **Scope ruthlessly** — Small, focused plans ship faster; gate 1 enforces scope discipline
+2. **Strict delegation** — Never synthesize, analyze, or plan in main session; always spawn agents
 
 ## Error Handling
 

package/dist/commands/release.md

@@ -58,9 +58,9 @@ Read `.release/RELEASE-FLOW.md`:
 node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off GATE_LEVEL=full` instead.
 
-The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+The accepted line is the only source of these values.
 
 When the settings line says `LEARNING=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
 

package/dist/commands/research.md

@@ -47,9 +47,9 @@ and using its one-line output. If the command fails (outside a git repository),
 node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off GATE_LEVEL=full` instead.
 
-The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+The accepted line is the only source of these values.
 
 ### Load DECISIONS_CONTEXT
 

package/dist/commands/resolve.md

@@ -94,9 +94,9 @@ Set `TARGET_DIR` to the selected review or bug-analysis directory path, and `TAR
 node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off GATE_LEVEL=full` instead.
 
-The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+The accepted line is the only source of these values.
 
 ### Load DECISIONS_CONTEXT
 

package/dist/commands/self-review.md

@@ -30,9 +30,9 @@ Detect changed files and build context:
 node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
 ```
 
-Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off` instead.
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> LEARNING=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=on LEARNING=on KNOWLEDGE=off GATE_LEVEL=full` instead.
 
-The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+The accepted line is the only source of these values.
 
 ### Load DECISIONS_CONTEXT
 

package/dist/core/echo-value.js

@@ -0,0 +1,42 @@
+/**
+ * Render an untrusted value for a terminal message.
+ *
+ * A neutral home for the sanitizer that every parser echoing a rejected value
+ * shares (the tracker provider and the gate level today), so no parser imports
+ * another feature's module just to reach it.
+ */
+/** Longest rejected value echoed back to the terminal, in CODE POINTS. */
+const MAX_ECHOED_VALUE = 40;
+/**
+ * Render an untrusted token for a terminal message.
+ *
+ * Rejected values are echoed so the user can see what they typed, so they are
+ * third-party input at a display sink: control characters (terminal escapes,
+ * BEL, newlines) are replaced and the value is truncated.
+ *
+ * Takes `unknown`, and a non-string renders as its TYPE: the never-throws
+ * contract of the callers has to hold for what reaches this sink, not
+ * only for what the signature says — a caller reads hand-editable
+ * files, and a caller-side guard is one edit from being gone. Naming the type
+ * also keeps the render total, where `String()` would hand control to a
+ * caller-supplied `toString` — itself both a throw path and an echo path this
+ * function exists to close.
+ */
+export function describeEchoedValue(raw) {
+    if (typeof raw !== 'string')
+        return `<${raw === null ? 'null' : typeof raw}>`;
+    // The class is written with ESCAPES, never literal control bytes. A raw NUL
+    // makes grep classify this whole file as binary — it prints "Binary file
+    // matches" and skips the lines — so every grep-based sweep over src/core/
+    // silently stops covering the file while still exiting 0. Pinned by
+    // tests/guards/no-control-bytes.test.ts.
+    // eslint-disable-next-line no-control-regex
+    const stripped = raw.replace(/[\x00-\x1f\x7f]/g, '?');
+    // Cut by CODE POINT. `slice` cuts UTF-16 code units, so a cut landing inside an
+    // astral character (emoji, CJK ext-B) emits the lone surrogate half of it.
+    const points = [...stripped];
+    return points.length > MAX_ECHOED_VALUE
+        ? `${points.slice(0, MAX_ECHOED_VALUE).join('')}…`
+        : stripped;
+}
+//# sourceMappingURL=echo-value.js.map

package/dist/core/evidence-policy.js

@@ -331,15 +331,27 @@ export function repoComplianceStatusLines(loaded, opts) {
  * tracked by git, or null (D-PERSONAL-UNTRACKED). The resolver ignores such a file
  * and says so on stderr, but prompts run it with stderr discarded, so a status
  * command is where the user sees why their personal settings have no effect.
+ *
+ * Takes the ONE resolved result, so a caller that already holds it adds no second
+ * resolve (each resolve forks git).
+ */
+export function trackedConfigWarning(settings) {
+    if (!settings.personalTracked)
+        return null;
+    const file = settingsSourceFile('personal');
+    return `Git tracks an entry at or under ${file}, so devflow ignores that file. It holds personal settings. ` +
+        'Find the entry in the output of: git ls-files. Untrack it with: git rm --cached <entry>. ' +
+        'Then check the file contents, or delete the file. ' +
+        'Untracking leaves the committed bytes on disk as your personal file.';
+}
+/**
+ * {@link trackedConfigWarning} for a caller that holds the loaded module and not a
+ * resolved result: it resolves once and returns null when the module is unusable.
  */
 export function personalConfigTrackedWarning(loaded, opts) {
     if (!loaded.ok)
         return null;
-    if (!loaded.value.resolveSettings(opts).personalTracked)
-        return null;
-    const file = settingsSourceFile('personal');
-    return `${file} is tracked by git, so devflow ignores it — it holds personal settings. ` +
-        `Untrack it with: git rm --cached ${file}`;
+    return trackedConfigWarning(loaded.value.resolveSettings(opts));
 }
 /** The policies the hint maps, in the order it prints them. */
 const HINT_POLICIES = ['standard', 'required'];

package/dist/core/gate-level.js

@@ -0,0 +1,213 @@
+import { promises as fs, constants as fsConstants } from 'fs';
+import * as path from 'path';
+import { writeFileAtomicExclusive } from './fs-atomic.js';
+import { hasRequiredManifestFields } from './manifest.js';
+import { describeEchoedValue } from './echo-value.js';
+/**
+ * The gate level: how much checking a command applies. One of three words, from
+ * most to least checking.
+ *
+ * `features.gateLevel` in `~/.devflow/manifest.json` is the MACHINE default, and
+ * `gateLevel` in a repository's personal `.devflow/config.json` overrides it.
+ * Neither is a feature switch: a switch can only be narrowed by a repository
+ * layer, but a level may be raised or lowered by the personal file. The settings
+ * resolver (`resolve-settings.cjs`) folds both into the `GATE_LEVEL=` field of its
+ * settings line; this module owns the closed set, the parser and the machine
+ * layer's raw reader and writer. No code here chooses a level from a task or a
+ * diff.
+ *
+ * A present value that is not one of the three words is MALFORMED. A reader reads
+ * it as `full` and leaves it on disk as written: no read and no unrelated write
+ * heals it to absent, which would lower the level without a word.
+ */
+export const GATE_LEVELS = Object.freeze(['full', 'standard', 'lean']);
+/** The level when neither the personal file nor the manifest records one. */
+export const DEFAULT_GATE_LEVEL = 'standard';
+/**
+ * Largest manifest read, in bytes. Pinned by a parity test to the resolver
+ * library's MAX_MANIFEST_BYTES, so the CLI and a prompt never disagree about a
+ * manifest that is too large to read.
+ */
+export const MAX_MANIFEST_BYTES = 1048576;
+const VALID_LEVELS_LIST = GATE_LEVELS.join(', ');
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isGateLevel(value) {
+    return typeof value === 'string' && GATE_LEVELS.includes(value);
+}
+/**
+ * Strict boundary parser for a gate level typed on the command line.
+ *
+ * REJECT, NEVER REPAIR: membership is byte-exact. No trim, no case folding, no
+ * alias. `Lean` and `lean ` are errors, not `lean`. The message names every valid
+ * level and echoes the offending value only in the sanitized form of
+ * {@link describeEchoedValue}.
+ */
+export function parseGateLevel(value) {
+    if (isGateLevel(value))
+        return { ok: true, value };
+    if (value === undefined || value === '') {
+        return { ok: false, error: `Missing gate level. Valid levels: ${VALID_LEVELS_LIST}` };
+    }
+    return {
+        ok: false,
+        error: `Unknown gate level: "${describeEchoedValue(value)}". Valid levels: ${VALID_LEVELS_LIST}`,
+    };
+}
+/**
+ * The machine layer's level in a RAW parsed manifest. Pure and total.
+ *
+ *   null       no level is recorded: not an object, `features` not an object, or
+ *              no own `gateLevel` key
+ *   'invalid'  a `gateLevel` key is present and is not one of the three words
+ *   a level    the recorded level
+ *
+ * Deliberately NOT built on readManifest(): that reader rejects a manifest
+ * missing a required field and heal-writes, and a read-only status must do
+ * neither. The resolver script's `machineGateLevel` is the CommonJS twin; a
+ * table test holds the two to the same rows.
+ */
+export function machineGateLevel(raw) {
+    if (!isPlainObject(raw))
+        return null;
+    const features = raw.features;
+    if (!isPlainObject(features))
+        return null;
+    if (!Object.hasOwn(features, 'gateLevel'))
+        return null;
+    const value = features.gateLevel;
+    return isGateLevel(value) ? value : 'invalid';
+}
+/**
+ * Set `features.gateLevel` in a RAW parsed manifest. Pure — returns a new object
+ * and never mutates its input. Null when the top level or `features` is not a
+ * plain object (there is no `features` record to write into).
+ *
+ * Only `features.gateLevel` and `updatedAt` change; every other key is carried
+ * verbatim, including keys this build does not model.
+ */
+export function setMachineGateLevel(raw, level, now) {
+    if (!isPlainObject(raw) || !isPlainObject(raw.features))
+        return null;
+    return {
+        ...raw,
+        features: { ...raw.features, gateLevel: level },
+        updatedAt: now,
+    };
+}
+const ABSENT = Object.freeze({ kind: 'absent' });
+const CORRUPT = Object.freeze({ kind: 'corrupt' });
+function startsWithBom(bytes) {
+    return bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf;
+}
+/** Bytes of the manifest, or why not: one bounded read of a regular file, followed through links. */
+async function readManifestBytes(manifestPath) {
+    try {
+        let st;
+        try {
+            st = await fs.stat(manifestPath);
+        }
+        catch (err) {
+            const code = err.code;
+            return code === 'ENOENT' || code === 'ENOTDIR' ? 'absent' : 'corrupt';
+        }
+        if (!st.isFile() || st.size > MAX_MANIFEST_BYTES)
+            return 'corrupt';
+        // O_NONBLOCK: a FIFO swapped in after the stat cannot block the open.
+        const handle = await fs.open(manifestPath, fsConstants.O_RDONLY | (fsConstants.O_NONBLOCK || 0));
+        try {
+            const opened = await handle.stat();
+            if (!opened.isFile() || opened.size > MAX_MANIFEST_BYTES)
+                return 'corrupt';
+            // One byte past the stat'd size: a file that grew between the stat and the
+            // read is refused rather than truncated into something that parses. Each
+            // pass reads at least one byte or stops, so the loop is bounded by the buffer.
+            const buf = Buffer.alloc(opened.size + 1);
+            let total = 0;
+            for (let pass = 0; pass < buf.length && total < buf.length; pass++) {
+                const { bytesRead } = await handle.read(buf, total, buf.length - total, null);
+                if (bytesRead === 0)
+                    break;
+                total += bytesRead;
+            }
+            return total > opened.size ? 'corrupt' : buf.subarray(0, total);
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+    }
+    catch {
+        return 'corrupt';
+    }
+}
+/**
+ * Read `<devflowDir>/manifest.json` raw, for the gate level. Never throws, never
+ * exits and never writes: unlike readManifest() it heals nothing, models no key
+ * and keeps every key it does not name.
+ *
+ * It follows the resolver library's rules, so the CLI and a prompt see the same
+ * file: the path is followed through links, a missing path is absent, and every
+ * other failure is corrupt. Bytes decode as UTF-8 with a fatal error, which also
+ * strips a leading BOM, and then parse as JSON, so the level is read past a BOM
+ * as it is in the resolver. A file with a BOM is still `rejected`, because
+ * readManifest() parses the text as read and refuses it.
+ */
+export async function readGateManifest(devflowDir) {
+    const bytes = await readManifestBytes(path.join(devflowDir, 'manifest.json'));
+    if (bytes === 'absent')
+        return ABSENT;
+    if (bytes === 'corrupt')
+        return CORRUPT;
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    catch {
+        return CORRUPT;
+    }
+    if (!isPlainObject(parsed) || !isPlainObject(parsed.features))
+        return CORRUPT;
+    const readable = !startsWithBom(bytes) && hasRequiredManifestFields(parsed);
+    return { kind: readable ? 'object' : 'rejected', raw: parsed };
+}
+/**
+ * Write the machine default to `<devflowDir>/manifest.json` (atomic temp +
+ * rename). Never throws. Refuses with `invalid-level`, before any I/O, a level
+ * that is not one of the three words, because the type is no check at run time.
+ * Refuses with `not-installed` when there is no manifest to write into — a
+ * manifest is created by `devflow init`, never by this write.
+ *
+ * Only `features.gateLevel` and `updatedAt` change. A write to the level the
+ * manifest already records changes nothing, `updatedAt` included, because that
+ * field means "the manifest's content last changed". A manifest that
+ * readManifest() would reject for another key gets the same write as one it
+ * accepts: its level is valid, and the fault is not this write's to fix.
+ *
+ * `now` is injected so a test fixes the timestamp.
+ */
+export async function writeMachineGateLevel(devflowDir, level, now) {
+    if (!isGateLevel(level))
+        return { kind: 'invalid-level' };
+    const manifestPath = path.join(devflowDir, 'manifest.json');
+    const read = await readGateManifest(devflowDir);
+    if (read.kind === 'absent')
+        return { kind: 'not-installed' };
+    if (read.kind === 'corrupt')
+        return { kind: 'unreadable', path: manifestPath };
+    const features = read.raw.features;
+    if (isPlainObject(features) && features.gateLevel === level)
+        return { kind: 'unchanged' };
+    try {
+        const next = setMachineGateLevel(read.raw, level, now());
+        if (next === null)
+            return { kind: 'unreadable', path: manifestPath };
+        await writeFileAtomicExclusive(manifestPath, JSON.stringify(next, null, 2) + '\n');
+        return { kind: 'written' };
+    }
+    catch (err) {
+        const code = err?.code;
+        return { kind: 'write-failed', path: manifestPath, reason: typeof code === 'string' ? code : 'unknown error' };
+    }
+}
+//# sourceMappingURL=gate-level.js.map

package/dist/core/manifest.js

@@ -51,6 +51,27 @@ function parseManifestFlags(features, knownFlags) {
     // Case C: missing/malformed → empty record
     return { flags: {}, legacy: false };
 }
+/**
+ * Whether a parsed manifest object carries every field {@link readManifest}
+ * requires: a version, a plugin list, a `features` object with boolean `ambient`
+ * and `memory`, and string `installedAt` and `updatedAt`. Pure. A manifest that
+ * fails it reads as "no prior install".
+ *
+ * Exported so a raw reader can tell a manifest this reader rejects from one it
+ * accepts without calling it: readManifest heal-writes, and a read-only status
+ * must not.
+ */
+export function hasRequiredManifestFields(data) {
+    const features = data.features;
+    return !(!data.version ||
+        !Array.isArray(data.plugins) ||
+        typeof features !== 'object' ||
+        features === null ||
+        typeof features.ambient !== 'boolean' ||
+        typeof features.memory !== 'boolean' ||
+        typeof data.installedAt !== 'string' ||
+        typeof data.updatedAt !== 'string');
+}
 /**
  * Read and parse the manifest file. Returns null if missing or corrupt.
  *
@@ -75,17 +96,9 @@ export async function readManifest(devflowDir, opts) {
     try {
         const content = await fs.readFile(manifestPath, 'utf-8');
         const data = JSON.parse(content);
-        const features = data.features;
-        if (!data.version ||
-            !Array.isArray(data.plugins) ||
-            typeof features !== 'object' ||
-            features === null ||
-            typeof features.ambient !== 'boolean' ||
-            typeof features.memory !== 'boolean' ||
-            typeof data.installedAt !== 'string' ||
-            typeof data.updatedAt !== 'string') {
+        if (!hasRequiredManifestFields(data))
             return null;
-        }
+        const features = data.features;
         // D-FEATURES-ABSENT-ON (a sub-decision of D-FEATURES-NARROW-ONLY,
         // src/core/feature-switch.ts): knowledge and learning are machine-wide
         // switches, and every runtime gate — queue_read_gates in the hooks,
@@ -172,6 +185,9 @@ export async function readManifest(devflowDir, opts) {
                 // self-heal behaviour, and a different condition from a per-repo config
                 // value outside the domain (which does emit `unknown tracker provider`).
                 tracker: normalizeTrackerFeature(features.tracker, opts?.onWarning),
+                // The machine gate level, raw (see the field's doc comment): kept when the
+                // key is present, a stored `null` included, and left out when it is absent.
+                ...(Object.hasOwn(features, 'gateLevel') ? { gateLevel: features.gateLevel } : {}),
             },
             installedAt: data.installedAt,
             updatedAt: data.updatedAt,

package/dist/core/model-discovery.js

@@ -61,9 +61,15 @@ const STDOUT_CAP = 262_144;
  * within this window receives SIGTERM followed by a SIGKILL escalation after
  * SIGKILL_GRACE_MS. Zero retries — the stale cache is the retry.
  *
+ * The window must outlast a cold start on a loaded machine: the first exec of
+ * node with the routing runtime took 1.0-5.4 s in measurement while the OS vetted
+ * the new process. A shorter window reports an installed runtime as unknown. The
+ * test harness bounds (tests/model-discovery.test.ts) use a wider margin than this
+ * measured range.
+ *
  * Exported so tests can derive timing bounds without mirroring the literal.
  */
-export const SPAWN_TIMEOUT_MS = 2_000;
+export const SPAWN_TIMEOUT_MS = 6_000;
 /**
  * Grace period (ms) between SIGTERM and SIGKILL escalation. Unreffed so the
  * timer never prevents the Node.js event loop from exiting on its own.

package/dist/core/tracker.js

@@ -28,6 +28,7 @@
  */
 import { promises as fs } from 'fs';
 import * as path from 'path';
+import { describeEchoedValue as describeTrackerValue } from './echo-value.js';
 /**
  * Canonical issue-tracker provider registry.
  *
@@ -193,8 +194,6 @@ export const TRACKER_ATTEMPTS_MAX = 5;
 // ---------------------------------------------------------------------------
 const REGISTRY_SET = new Set(TRACKER_PROVIDER_IDS);
 const VALID_IDS_LIST = TRACKER_PROVIDER_IDS.join(', ');
-/** Longest rejected value echoed back to the terminal, in CODE POINTS. */
-const MAX_ECHOED_VALUE = 40;
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -217,38 +216,11 @@ export function isTrackerProvider(value) {
     return typeof value === 'string' && REGISTRY_SET.has(value);
 }
 /**
- * Render an untrusted provider token for a terminal message.
- *
- * Rejected values are echoed so the user can see what they typed, so they are
- * third-party input at a display sink: control characters (terminal escapes,
- * BEL, newlines) are replaced and the value is truncated. Used by
- * `parseTrackerId`'s error text and by `devflow tracker --status`.
- *
- * Takes `unknown`, and a non-string renders as its TYPE: the module's
- * never-throws contract has to hold for what reaches this sink, not
- * only for what the signature says does — `devflow tracker --status` reads
- * a conventions file's hand-editable frontmatter, and a caller-side guard is one edit
- * from being gone. Naming the type also keeps the render total, where `String()`
- * would hand control to a caller-supplied `toString` — itself both a throw path
- * and an echo path this function exists to close.
+ * Render an untrusted provider token for a terminal message. Used by
+ * `parseTrackerId`'s error text and by `devflow tracker --status`. The sanitizer
+ * itself lives in `echo-value.ts`; this is its tracker-facing name.
  */
-export function describeTrackerValue(raw) {
-    if (typeof raw !== 'string')
-        return `<${raw === null ? 'null' : typeof raw}>`;
-    // The class is written with ESCAPES, never literal control bytes. A raw NUL
-    // makes grep classify this whole file as binary — it prints "Binary file
-    // matches" and skips the lines — so every grep-based sweep over src/core/
-    // silently stops covering tracker.ts while still exiting 0. Pinned by
-    // tests/guards/no-control-bytes.test.ts.
-    // eslint-disable-next-line no-control-regex
-    const stripped = raw.replace(/[\x00-\x1f\x7f]/g, '?');
-    // Cut by CODE POINT. `slice` cuts UTF-16 code units, so a cut landing inside an
-    // astral character (emoji, CJK ext-B) emits the lone surrogate half of it.
-    const points = [...stripped];
-    return points.length > MAX_ECHOED_VALUE
-        ? `${points.slice(0, MAX_ECHOED_VALUE).join('')}…`
-        : stripped;
-}
+export { describeTrackerValue };
 /**
  * Strict boundary parser for a provider token (`--tracker <id>`,
  * `devflow tracker --set <id>`).