devflow-kit 3.8.0 → 3.10.0

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');
         }

package/dist/cli/commands/curation.js

@@ -9,8 +9,10 @@ import { loadShippedAgentDefaults } from '../../core/agent-models.js';
 import { readMachineFeature, writeMachineFeature } from '../../core/feature-switch.js';
 import { loadSettingsModule, narrowedSwitchLabel, personalConfigTrackedWarning } from '../../core/evidence-policy.js';
 import { getClaudeDirectory, getDevFlowDirectory } from '../../targets/claude-code/claude-paths.js';
-import { applyCurationToggle, describeCurationConverge, installedScriptsSkew, readRunningVersion, } from '../../targets/claude-code/curation-install.js';
+import { applyVariantToggle, describeCurationConverge, describePostingLeft, installedScriptsSkew, readRunningVersion, } from '../../targets/claude-code/curation-install.js';
 import { getLedgerRoot } from '../../core/ledger-root.js';
+import { AREA_PAUSE_NOTICE } from '../../core/area-pause-notice.js';
+import { probeTrackedArea } from '../../core/tracked-areas.js';
 import { drainCurationQueue, drainDisabledCurationQueue, formatCurationNotDrained } from '../../core/curation-queue-cleanup.js';
 import { firstSymbolicLink } from '../../core/linked-path.js';
 import { describeMoveText, describeOutcome } from './curation-move-step.js';
@@ -74,10 +76,34 @@ function requireStore() {
     process.exitCode = 1;
     return null;
 }
+/**
+ * Which fixed notice a store refusal of kind `tracked` takes: the reason the store names
+ * on the refusal. A refusal that names none is `unknown`, the notice that claims least.
+ */
+function pauseReasonOf(error) {
+    return error.reason ?? 'unknown';
+}
+/**
+ * The fixed line of a paused curation area at `ledgerRoot`, or null when git tracks
+ * nothing in the curation folders there. The area is paused when git tracks files in the
+ * curation folder, the old ledger folder or a backup folder, or when a `.git` entry stands
+ * and git did not answer; a root with no `.git` entry makes no git call. Every command
+ * asks first, before it reads a ledger file, takes a lock or prompts.
+ */
+async function pausedCurationLine(ledgerRoot) {
+    const { answer } = await probeTrackedArea(ledgerRoot, 'curation');
+    return answer === 'untracked' ? null : AREA_PAUSE_NOTICE.curation[answer];
+}
+/** Say that a command changed nothing because the curation area is paused: the fixed `line`, exit code 1. */
+function refusePaused(line) {
+    p.log.error(line);
+    process.exitCode = 1;
+}
 /** What a writer says when the store refused; `undone` completes "Nothing was …". */
 function storeRefusal(error, undone) {
     switch (error.kind) {
         case 'no-curation-dir': return NO_CURATION_DATA;
+        case 'tracked': return AREA_PAUSE_NOTICE.curation[pauseReasonOf(error)];
         case 'busy': return `The curation store is busy: another run holds its lock. Nothing was ${undone}; try again in a moment.`;
         default: return error.message;
     }
@@ -143,15 +169,21 @@ async function moveReadNotice(ledgerRoot) {
 }
 /**
  * The gate every writing subcommand passes first (--restore, --clear, --reset and the
- * project scope of --configure). Installed scripts of another version read and create
- * another ledger folder, so they refuse with the skew line. Then, where the old folder
- * is present, the shared move runs with no wait: a busy lock prints a retry message,
- * a queue claim that holds the move prints its own message, a refused or failed move
- * prints its reason, and a skipped move (git tracks files in a data folder, or git did
- * not answer) prints the fixed notice; in each case nothing is written.
+ * project scope of --configure). A paused curation area (git tracks files in a data
+ * folder, or git did not answer) refuses with the fixed notice before anything else, so
+ * a clear or a reset never reaches its confirm prompt. Installed scripts of another
+ * version read and create another ledger folder, so they refuse with the skew line.
+ * Then, where the old folder is present, the shared move runs with no wait: a busy lock
+ * prints a retry message, a queue claim that holds the move prints its own message, and
+ * a refused or failed move prints its reason; in each case nothing is written.
  * `undone` completes "Nothing was …". Answers true when the caller may write.
  */
 async function prepareToWrite(ledgerRoot, undone) {
+    const paused = await pausedCurationLine(ledgerRoot);
+    if (paused !== null) {
+        refusePaused(paused);
+        return false;
+    }
     const skew = await installedScriptsSkew(getDevFlowDirectory());
     if (skew !== null) {
         p.log.error(skew);
@@ -267,7 +299,8 @@ function backupLines(ledgerRoot) {
  * whose ledger still sits in the old folder gets the HUD's pointer (or refused line, or
  * the notice of a skipped move) in place of the counts; a project with both folders and
  * a skipped move gets the notice with the counts; a project with backup folders gets one
- * line for each.
+ * line for each. A paused area (git tracks files in a data folder, or did not answer)
+ * gets the fixed notice after the machine switch, nothing is read, and the exit code is 0.
  */
 async function handleStatus() {
     // D-FEATURES-NARROW-ONLY: the machine switch is the manifest's and reads the
@@ -282,6 +315,11 @@ async function handleStatus() {
     if (trackedWarning !== null)
         p.log.warn(trackedWarning);
     const ledgerRoot = await getLedgerRoot();
+    const paused = await pausedCurationLine(ledgerRoot ?? process.cwd());
+    if (paused !== null) {
+        p.log.info(`${stateLine}\n${paused}`);
+        return;
+    }
     if (!ledgerRoot) {
         p.log.info(`${stateLine}\nEntries: not in a git project`);
         return;
@@ -312,13 +350,19 @@ async function handleStatus() {
 }
 /**
  * `--list`: the store's listing — the same text json-helper's `list` op prints —
- * on stdout. Read-only. Outside a git project it reads the current directory. Where
- * the ledger still sits in the old folder it prints the pointer, the refused line or the
- * notice of a skipped move in place of the listing; with both folders and a skipped move
- * it prints the notice before the listing.
+ * on stdout. Read-only. Outside a git project it reads the current directory. A paused
+ * area prints the fixed notice and exits 1, and reads nothing. Where the ledger still
+ * sits in the old folder it prints the pointer, the refused line or the notice of a
+ * skipped move in place of the listing; with both folders and a skipped move it prints
+ * the notice before the listing.
  */
 async function handleList() {
     const root = (await getLedgerRoot()) ?? process.cwd();
+    const paused = await pausedCurationLine(root);
+    if (paused !== null) {
+        refusePaused(paused);
+        return;
+    }
     const notice = await moveReadNotice(root);
     if (notice !== null)
         p.log.info(notice.line);
@@ -342,12 +386,18 @@ async function handleList() {
 /**
  * `--show <id>`: one entry, by its anchor or its observation id, as the JSON
  * json-helper's `show` op prints, made terminal-safe. Read-only. Outside a git
- * project it reads the current directory. Where the ledger still sits in the old
- * folder it prints the pointer, the refused line or the notice of a skipped move as the
- * refusal; with both folders and a skipped move it prints the notice on stderr and goes on.
+ * project it reads the current directory. A paused area prints the fixed notice as the
+ * refusal and reads nothing. Where the ledger still sits in the old folder it prints the
+ * pointer, the refused line or the notice of a skipped move as the refusal; with both
+ * folders and a skipped move it prints the notice on stderr and goes on.
  */
 async function handleShow(key) {
     const root = (await getLedgerRoot()) ?? process.cwd();
+    const paused = await pausedCurationLine(root);
+    if (paused !== null) {
+        refusePaused(paused);
+        return;
+    }
     const notice = await moveReadNotice(root);
     if (notice?.kind === 'instead') {
         p.log.error(notice.line);
@@ -593,13 +643,15 @@ async function handleClear() {
 /**
  * Make the installed prompts match the switch just written
  * (D-LEARNING-VARIANT-INSTALL): the curation-on or curation-off commands and
- * agents, and the apply-decisions skill. The same convergence `devflow init` runs,
- * followed by reapplying the saved agent model mapping so `devflow agents`
- * overrides survive.
+ * agents, and the apply-decisions skill. The one converge for both axes that
+ * `devflow init` and `devflow compliance` run, followed by reapplying the saved
+ * agent model mapping so `devflow agents` overrides survive.
  *
  * Warn-not-fail: the switch itself is already recorded, and either mismatch is
  * safe (an on variant is still gated at run time, an off variant loads no
- * decisions), so a problem here never changes the exit code.
+ * decisions), so a problem here never changes the exit code. A compliance-off
+ * machine that still has a prompt that posts is a warning here too: the fail-closed
+ * exit belongs to `devflow compliance`, which changes that axis.
  *
  * Answers whether the converge ran, which means the installed files are the ones
  * this CLI writes. The toggle moves the ledger folder only then: under version skew
@@ -607,10 +659,11 @@ async function handleClear() {
  */
 async function convergeInstalledVariants(enabled) {
     try {
-        const outcome = await applyCurationToggle({
+        const outcome = await applyVariantToggle({
             claudeDir: getClaudeDirectory(),
             devflowDir: getDevFlowDirectory(),
-            curation: enabled,
+            axis: 'curation',
+            enabled,
             runningVersion: await readRunningVersion(),
             warn: (msg) => p.log.warn(msg),
         });
@@ -621,6 +674,8 @@ async function convergeInstalledVariants(enabled) {
         const changed = describeCurationConverge(outcome.result, enabled);
         if (changed !== null)
             p.log.info(color.dim(`Installed prompts: ${changed}`));
+        for (const line of describePostingLeft(outcome.result.posting))
+            p.log.warn(line);
         return 'converged';
     }
     catch (err) {
@@ -657,8 +712,9 @@ async function tryMoveForToggle(ledgerRoot) {
  * variants and skill (D-LEARNING-VARIANT-INSTALL), the current project's ledger
  * folder move, and on disable a drained queue in every ledger folder that exists and
  * in the backups a move left. The drain deletes no queue file, and prints the fixed
- * notice of a skipped move once, when git tracks any entry under a data folder or a
- * backup folder, or does not answer.
+ * pause notice of the curation area, when git tracks any entry under a data folder or a
+ * backup folder, or does not answer. A move that has just printed its own notice for the
+ * same reason leaves the drain's line short, so the cause is told once.
  * Never requires a git root: the switch is not a per-project setting.
  *
  * Under version skew the toggle records the switch and moves nothing; otherwise it

package/dist/cli/commands/gate-level-prompts.js

@@ -31,21 +31,18 @@ import { DEFAULT_GATE_LEVEL, GATE_LEVELS, MALFORMED_GATE_LEVEL_READS_AS, parseGa
 /** Message shown on the gate level select prompt. */
 export const GATE_LEVEL_SELECT_MESSAGE = 'Gate level for this machine';
 /**
- * The one-line effect of each level, as the select hint and the catalogue show it.
- * Each hint says what its level does. GATE_LEVEL_EFFECT in gates.ts says which commands
- * read the level. Change a hint when what a level does changes. A command that reads the
- * level and has no rule that changes a phase leaves the hints true, so it changes
- * GATE_LEVEL_EFFECT alone. One test pins the exact text of both tables, so a change to
- * either fails it until you check the other table and update the pin; further rows check
- * the clauses the two tables share (the lint pack level, the levels that run fewer review
- * focuses and the levels that skip Polish). The clause that lean skips Harden on a
- * docs-only diff has no facet row in `tests/gate-level-prompts.test.ts`: the docs guard
- * checks it at each doc site, against the row in the /implement level reference.
+ * One short line for each level, as the select hint and the catalogue show it.
+ * clack never wraps a note or a hint, so a hint stays within 60 characters and holds no line
+ * break (a guard in `tests/gate-level-prompts.test.ts` holds both). The full effects of each
+ * level live in GATE_LEVEL_EFFECT in gates.ts, in `devflow gates` and in the docs.
+ * Change a hint when the level it names changes how much it checks; then check
+ * GATE_LEVEL_EFFECT and update the pin. The comment on GATE_LEVEL_EFFECT holds the full
+ * update rule, the pin and the list of clauses that the two tables share.
  */
 export const GATE_LEVEL_HINTS = Object.freeze({
-    full: 'the most checking: every review focus, the full planning shape and Polish',
-    standard: 'fewer review focuses and planning agents, and no Polish in /implement and /resolve (the default)',
-    lean: 'the least checking, and no Polish in /implement and /resolve; /implement also has Validate run the project lint pack, and skips Harden on a docs-only diff',
+    full: 'the most checking: every review focus, and Polish',
+    standard: 'fewer review focuses, no Polish; the default',
+    lean: 'the least checking: no Polish, Validate runs the lint pack',
 });
 /** Build clack select options for the gate level list, most to least checking. */
 export function gateLevelChoices() {
@@ -53,12 +50,24 @@ export function gateLevelChoices() {
 }
 /**
  * Format a padded level catalogue suitable for a clack note body.
- * Produces: `  standard  fewer review focuses and planning agents, and no Polish in /implement and /resolve (the default)`
+ * Produces: `  standard  fewer review focuses, no Polish; the default`
  */
 export function formatGateLevelCatalogue() {
     const width = Math.max(...GATE_LEVELS.map(level => level.length));
     return 'Levels:\n' + GATE_LEVELS.map(level => `  ${level.padEnd(width)}  ${GATE_LEVEL_HINTS[level]}`).join('\n');
 }
+// ── Where the stored level was found ───────────────────────────────────────────
+/**
+ * Where init found the stored machine gate level:
+ *
+ *   manifest    in the manifest init reads (or nowhere, on a first install or after
+ *               --reset): the seed holds it
+ *   rejected    in a manifest that readManifest() refuses, read raw: init keeps the
+ *               level as stored while it replaces that manifest
+ *   unreadable  nowhere: the manifest cannot be read at all, or stores a level that cannot be
+ *               written back as JSON, so what it stored is unknown
+ */
+export const STORED_GATE_LEVEL_ORIGINS = Object.freeze(['manifest', 'rejected', 'unreadable']);
 /** `features.gateLevel` of a raw manifest, exactly as stored; `undefined` for an absent key. */
 function rawGateLevelOf(raw) {
     const features = raw.features;
@@ -226,17 +235,24 @@ export function describeGateLevel(stored) {
 export function gateLevelPromptSeed(stored, origin = 'manifest') {
     return appliedLevel(classifyGateLevel(stored, origin));
 }
-/** The "Current setting" lines of the prompt note, from the stored value and where it was found. */
+/** The "Current setting" lines of the prompt note, from the stored value and where it was found. Each line fits the 72 columns the note allows. */
 function currentSettingLines(stored, origin) {
     switch (origin) {
         case 'manifest':
             return `Current setting: ${describeGateLevel(stored)}`;
         case 'rejected':
-            return `Current setting: ${describeGateLevel(stored)}\n` +
-                'It comes from a manifest that devflow rejects. Init replaces that manifest and keeps this level unless you choose another.';
+            return [
+                `Current setting: ${describeGateLevel(stored)}`,
+                'It comes from a manifest that devflow rejects.',
+                'Init replaces that manifest and keeps this level',
+                'unless you choose another.',
+            ].join('\n');
         case 'unreadable':
-            return 'Current setting: unknown\n' +
-                `The stored gate level cannot be read, so ${DEFAULT_GATE_LEVEL} applies until you choose a level.`;
+            return [
+                'Current setting: unknown',
+                `The stored gate level cannot be read, so ${DEFAULT_GATE_LEVEL} applies`,
+                'until you choose a level.',
+            ].join('\n');
         default: {
             const exhaustive = origin;
             return exhaustive;
@@ -318,10 +334,10 @@ export function buildClackGateLevelPrompts() {
 export async function runGateLevelStep(opts) {
     const { stored, storedOrigin = 'manifest', prompts } = opts;
     prompts.note(`${currentSettingLines(stored, storedOrigin)}\n\n` +
-        'Sets how much checking /code-review, /plan and /implement apply on this\n' +
-        'machine. A personal "gateLevel" in a repository\'s .devflow/config.json\n' +
-        'overrides it in that repository. Change it later with\n' +
-        'devflow gates --set <level>.\n\n' +
+        'Sets how much checking /code-review, /plan, /implement and /resolve\n' +
+        'apply on this machine. A personal "gateLevel" in a repository\'s\n' +
+        '.devflow/config.json overrides it in that repository. Change it later\n' +
+        'with devflow gates --set <level>.\n\n' +
         formatGateLevelCatalogue(), 'Gate level');
     const outcome = await prompts.selectLevel({
         message: GATE_LEVEL_SELECT_MESSAGE,

package/dist/cli/commands/gates.js

@@ -39,17 +39,16 @@ export const GATE_LEVEL_MEANINGS = Object.freeze({
 /**
  * Which commands read the level today; each later command that reads it updates this text.
  *
- * The init prompt says what each level does in GATE_LEVEL_HINTS (gate-level-prompts.ts).
- * Change the hints too when what a level does changes. A command that reads the level and
- * has no rule that changes a phase leaves the hints true, so it changes this text alone.
+ * The init prompt gives each level one short line in GATE_LEVEL_HINTS (gate-level-prompts.ts);
+ * this text and the docs hold the full effects. Change the hints too when a level changes
+ * how much it checks. A command that reads the level and has no rule that changes a phase
+ * leaves the hints true, so it changes this text alone.
  * One test pins the exact text of both tables, so a change to either fails it until you
  * check the other table and update the pin; further rows check the clauses the two tables
  * share (the lint pack level, the levels that run fewer review focuses and the levels that
- * skip Polish). The clause that lean skips Harden on a docs-only diff has no facet row in
- * `tests/gate-level-prompts.test.ts`: the docs guard checks it at each doc site, against
- * the row in the /implement level reference.
+ * skip Polish).
  */
-export const GATE_LEVEL_EFFECT = '/code-review and /plan read the level: standard and lean run fewer review focuses and fewer planning agents. At lean, /implement has Validate run the project\'s lint pack. /implement and /resolve also read the level and name it in their report; at standard and lean they skip Polish, and full keeps it. At lean, /implement skips Harden on a docs-only diff.';
+export const GATE_LEVEL_EFFECT = '/code-review and /plan read the level: standard and lean run fewer review focuses and fewer planning agents. At lean, /implement has Validate run the project\'s lint pack. /implement and /resolve also read the level and name it in their report; at standard and lean they skip Polish, and full keeps it. At lean, /implement skips Harden on a docs-only diff. At standard and lean, /implement runs one Evaluate pass and at most one Fix round. At standard and lean, /resolve applies severity tiers: it fixes or escalates every security finding, fixes CRITICAL, HIGH and severe MEDIUM findings in the branch\'s own code, fixes prose-only MEDIUM findings with text edits alone, and sends lower findings and pre-existing non-security findings to one backlog issue.';
 const MACHINE_MANIFEST_NAME = 'manifest.json';
 const MACHINE_INVALID_LINE = `invalid (${MACHINE_MANIFEST_NAME}; reads as ${MALFORMED_GATE_LEVEL_READS_AS})`;
 const VALID_LEVELS = GATE_LEVELS.join(', ');