devflow-kit 3.3.0 → 3.5.0

package/dist/core/learning-variants.js

@@ -0,0 +1,213 @@
+/**
+ * Learning-variant splitter: one compiled prompt body in, its learning-on and
+ * learning-off variants out.
+ *
+ * Pure module, zero I/O. Every refusal is a Result; the exiting shell is
+ * scripts/build-mds.ts, which renders these errors into the build's single exit.
+ *
+ * D-LEARNING-VARIANTS: when learning is off on a machine, the decisions text is
+ * ABSENT from every prompt it would have reached, not merely gated at run time.
+ * The build therefore emits two variants of a prompt that carries learning text:
+ * the learning-on variant at today's path (dist/commands/x.md, dist/agents/x.md)
+ * and the learning-off variant at dist/learning-off/{commands,agents}/x.md, only
+ * for a host that has an arm. A prompt with no arm has one variant and no
+ * learning-off file.
+ *
+ * The arms are whole-line markers in the host or in a partial it expands:
+ *
+ *   <!-- learning:on -->     opens an arm that only the learning-on variant keeps
+ *   <!-- learning:off -->    opens an arm that only the learning-off variant keeps;
+ *                            directly after an on arm it is that arm's else
+ *   <!-- learning:end -->    closes the arm
+ *
+ * A marker line matches LEARNING_MARKER_RE. It may be indented and may sit inside
+ * a fenced block, a list, a define body or an agent's second frontmatter block,
+ * because MDS passes an HTML comment through untouched. The splitter runs on the
+ * COMPILED body, after the MDS compile, so it adds no compileFile call, no import
+ * into an MDS module and nothing against the per-module compile-time guard. A
+ * marker line is removed whole, with its newline. Every other line is kept byte
+ * for byte, so a blank line is content: put the blank line a paragraph needs
+ * inside the arm that owns the paragraph, and the other variant gets none of it.
+ *
+ * The markers are INTERIM. MDS 0.4.4 emits an `@if` inside a code fence or on an
+ * indented line as literal text (its lexer requires column 0), and the arms have
+ * to sit exactly there: inside fenced spawn blocks, scripts, list items and
+ * frontmatter. They are replaced by native conditionals once mdscript ships
+ * fence- and indent-aware `@if` (dean0x/mdscript#452). That swap, with the
+ * @mdscript/mds upgrade it rides on proven byte-identical in dist/ and this module
+ * deleted, is dean0x/devflow#439. The mapping is one to one: `on` becomes
+ * `@if learning:`, `off` becomes `@else:` and `end` becomes `@end`. A standalone
+ * `off` arm, with no on arm before it, becomes an `@if learning:` with an empty
+ * body followed by `@else:`.
+ *
+ * What the splitter refuses, each as a LearningSplitError with the source line:
+ *   - nesting: an `on` marker while an arm is open, or a second `off` in one arm;
+ *   - an `end` with no open arm;
+ *   - an arm still open at the end of the body;
+ *   - an empty arm (no line with content between its marker and the next);
+ *   - a stray marker: a line that names `<!-- learning:` but is not a whole-line
+ *     marker, which would otherwise ship as prompt text.
+ *
+ * Scope guarantee: this module answers one question (what are the two variants of
+ * this body?) and one cheap one for the build to ask of a body that must carry no
+ * arms (containsLearningMarker). It decides nothing about WHICH text belongs in an
+ * arm: that is authoring, and the guards over the built trees hold it.
+ */
+function Ok(value) {
+    return { ok: true, value };
+}
+function Err(error) {
+    return { ok: false, error };
+}
+/**
+ * Repo-relative root of the learning-off variants.
+ *
+ * Exported because the build's orphan prune names this directory even when no
+ * host carries an arm, which is exactly the case where every file in it is an
+ * orphan, so it cannot be derived from the plan.
+ */
+export const LEARNING_OFF_OUTPUT_DIR = 'dist/learning-off';
+/**
+ * POSIX repo-relative path of the learning-off variant of an output file.
+ *
+ * `fileName` is the already-validated basename the learning-on variant is written
+ * under (`implement.md`), so the two variants of one host always share a name.
+ */
+export function learningOffRelPath(kind, fileName) {
+    return `${LEARNING_OFF_OUTPUT_DIR}/${kind}/${fileName}`;
+}
+// ---------------------------------------------------------------------------
+// Markers
+// ---------------------------------------------------------------------------
+/**
+ * A whole-line learning marker. The group captures `on`, `off` or `end`.
+ *
+ * Anchored at both ends with no nested quantifier, so a match is linear in the
+ * line length. Leading and trailing space or tab is allowed; anything else on the
+ * line is not a marker.
+ */
+export const LEARNING_MARKER_RE = /^[ \t]*<!-- learning:(on|off|end) -->[ \t]*$/;
+/**
+ * The fragment that makes a line a marker ATTEMPT: loose on spacing and case so a
+ * malformed marker is caught rather than shipped. Every valid marker contains it.
+ */
+const MARKER_FRAGMENT_RE = /<!--\s*learning\s*:/i;
+/** True when the text names a learning marker anywhere, valid or not. */
+export function containsLearningMarker(text) {
+    return MARKER_FRAGMENT_RE.test(text);
+}
+function markerOf(line) {
+    // A CRLF body carries the carriage return on the line; it is not part of the marker.
+    const bare = line.endsWith('\r') ? line.slice(0, -1) : line;
+    const match = LEARNING_MARKER_RE.exec(bare);
+    return match === null ? null : match[1];
+}
+/** The longest stretch of a stray line a refusal quotes. */
+const STRAY_QUOTE_MAX = 80;
+/**
+ * Split a compiled body into its learning-on and learning-off variants.
+ *
+ * Total and pure: the same input gives the same output, and a refusal is a
+ * Result. The loop is one pass over the body's lines, so its bound is the body's
+ * own length.
+ *
+ * An arm needs a line with content in it. An arm that holds only blank lines is
+ * refused as empty, because it would add blank lines to one variant and nothing to
+ * the other, which is a mistake rather than a design.
+ */
+export function splitLearningVariants(body) {
+    const lines = body.split('\n');
+    const on = [];
+    const off = [];
+    let hasArms = false;
+    // The open arm, if any: which one, the line of the marker that opened it, and
+    // whether it has held a line with content yet.
+    let arm = null;
+    let armOpenedAt = 0;
+    let armHasContent = false;
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        const lineNo = index + 1;
+        const marker = markerOf(line);
+        if (marker === null) {
+            if (MARKER_FRAGMENT_RE.test(line)) {
+                return Err({ kind: 'stray-marker', line: lineNo, text: line.trim().slice(0, STRAY_QUOTE_MAX) });
+            }
+            if (arm !== 'off')
+                on.push(line);
+            if (arm !== 'on')
+                off.push(line);
+            if (arm !== null && line.trim() !== '')
+                armHasContent = true;
+            continue;
+        }
+        hasArms = true;
+        switch (marker) {
+            case 'on':
+                if (arm !== null)
+                    return Err({ kind: 'nested-arm', line: lineNo, arm, openedAt: armOpenedAt });
+                arm = 'on';
+                armOpenedAt = lineNo;
+                armHasContent = false;
+                break;
+            case 'off':
+                if (arm === 'off')
+                    return Err({ kind: 'repeated-off', line: lineNo, openedAt: armOpenedAt });
+                // Directly after an on arm this is its else: the on arm ends here.
+                if (arm === 'on' && !armHasContent) {
+                    return Err({ kind: 'empty-arm', arm, openedAt: armOpenedAt, closedAt: lineNo });
+                }
+                arm = 'off';
+                armOpenedAt = lineNo;
+                armHasContent = false;
+                break;
+            case 'end':
+                if (arm === null)
+                    return Err({ kind: 'unopened-end', line: lineNo });
+                if (!armHasContent) {
+                    return Err({ kind: 'empty-arm', arm, openedAt: armOpenedAt, closedAt: lineNo });
+                }
+                arm = null;
+                break;
+            default: {
+                const unhandled = marker;
+                return Err({ kind: 'stray-marker', line: lineNo, text: String(unhandled) });
+            }
+        }
+    }
+    if (arm !== null)
+        return Err({ kind: 'unclosed-arm', arm, openedAt: armOpenedAt });
+    return Ok({ on: on.join('\n'), off: off.join('\n'), hasArms });
+}
+/**
+ * Render a refusal as one line a person can act on.
+ *
+ * One arm per kind with a `never` default, so a kind added to the union cannot
+ * fall through into a message that does not describe it. Shared by the build and
+ * the tests, so the text asserted is the text shipped.
+ */
+export function describeLearningSplitError(error) {
+    switch (error.kind) {
+        case 'nested-arm':
+            return (`line ${error.line}: a learning:on marker inside the ${error.arm} arm opened at line ` +
+                `${error.openedAt} — arms do not nest; close it with learning:end first`);
+        case 'repeated-off':
+            return (`line ${error.line}: a second learning:off marker inside the off arm opened at line ` +
+                `${error.openedAt} — an arm has at most one else`);
+        case 'unopened-end':
+            return `line ${error.line}: a learning:end marker with no open arm`;
+        case 'unclosed-arm':
+            return `the ${error.arm} arm opened at line ${error.openedAt} is never closed with learning:end`;
+        case 'empty-arm':
+            return (`lines ${error.openedAt}-${error.closedAt}: the ${error.arm} arm holds no line with content — ` +
+                `delete the arm or put its text inside it`);
+        case 'stray-marker':
+            return (`line ${error.line}: "${error.text}" names a learning marker but is not one — a marker ` +
+                `is a whole line, exactly <!-- learning:on -->, <!-- learning:off --> or <!-- learning:end -->`);
+        default: {
+            const unhandled = error;
+            return `unhandled learning split error ${JSON.stringify(unhandled)}`;
+        }
+    }
+}
+//# sourceMappingURL=learning-variants.js.map

package/dist/core/manifest.js

@@ -62,12 +62,15 @@ function parseManifestFlags(features, knownFlags) {
  * - features.knownFlags stripped from result (folded into FlagsRecord key-presence)
  * - features.proxy absent → false
  * - features.compliance absent/malformed → {enabled:false, frameworks:[]}
+ * - features.behavior absent → false; malformed → false, healed on disk (D-BEHAVIOR-OPT-IN)
  * - features.tracker absent/malformed → {provider:'github'}
+ * - features.tracker.servers absent → the default list; invalid → the default list, reported
+ *   through `opts.onWarning` when the caller supplies one (this reader has no output channel)
  *
  * D39: heal-write failure returns the migrated in-memory manifest (not null).
  * The on-disk format remains unhealed; next read triggers another attempt.
  */
-export async function readManifest(devflowDir) {
+export async function readManifest(devflowDir, opts) {
     const manifestPath = path.join(devflowDir, 'manifest.json');
     try {
         const content = await fs.readFile(manifestPath, 'utf-8');
@@ -129,7 +132,10 @@ export async function readManifest(devflowDir) {
             features.decisions !== undefined ||
             flagsWereLegacy ||
             features.knownFlags !== undefined ||
-            features.viewMode !== undefined;
+            features.viewMode !== undefined ||
+            // D-BEHAVIOR-OPT-IN: a malformed switch (present, not a boolean) is rewritten as
+            // the false it reads as; an absent one is not a defect and owes no write.
+            (features.behavior !== undefined && typeof features.behavior !== 'boolean');
         const SECURITY_MODES = ['none', 'user', 'managed'];
         const manifest = {
             version: data.version,
@@ -158,12 +164,14 @@ export async function readManifest(devflowDir) {
                 proxy: typeof features.proxy === 'boolean' ? features.proxy : false,
                 // Self-heal: absent/malformed compliance → {enabled:false, frameworks:[]}
                 compliance: normalizeComplianceFeature(features.compliance),
+                // D-BEHAVIOR-OPT-IN: absent/malformed → false (opt-in; the inverse of knowledge/learning).
+                behavior: features.behavior === true,
                 // Self-heal: absent/malformed/unknown tracker → {provider:'github'} (AC-3.21).
                 // Deliberately NOT in the hard-null set above — see the field's doc comment.
                 // Healing here is silent and emits no DEGRADED: that is the correct
                 // 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),
+                tracker: normalizeTrackerFeature(features.tracker, opts?.onWarning),
             },
             installedAt: data.installedAt,
             updatedAt: data.updatedAt,
@@ -213,6 +221,68 @@ export async function syncManifestFeature(devflowDir, key, value) {
     manifest.updatedAt = new Date().toISOString();
     await writeManifest(devflowDir, manifest);
 }
+/**
+ * Drop `names` from a RAW parsed manifest's `plugins` list. Pure — returns a new
+ * object and never mutates its input. Null when there is nothing to write: the
+ * value is not a manifest-shaped object, or none of `names` is listed.
+ *
+ * Only `plugins` and `updatedAt` change; every other key is carried verbatim,
+ * `knownPlugins` included. That snapshot records which registry plugins the last
+ * install knew, and init adopts a registry plugin that is in neither list as new
+ * (`resolveSeedPlugins`), so dropping a removed plugin from it would make the next
+ * re-init install it again. Going through readManifest()/writeManifest() instead
+ * would drop every key ManifestData does not model (one a newer devflow wrote,
+ * say) and persist that reader's unrelated heals as a side effect of a removal.
+ * Entries that are not strings are neither matched nor dropped.
+ */
+export function withoutManifestPlugins(rawManifest, names, now) {
+    if (typeof rawManifest !== 'object' || rawManifest === null || Array.isArray(rawManifest))
+        return null;
+    const record = rawManifest;
+    if (!Array.isArray(record.plugins))
+        return null;
+    const doomed = new Set(names);
+    const kept = record.plugins.filter(entry => !(typeof entry === 'string' && doomed.has(entry)));
+    if (kept.length === record.plugins.length)
+        return null;
+    return { ...record, plugins: kept, updatedAt: now };
+}
+/**
+ * D-UNINSTALL-DROPS-PLUGIN: record a selective uninstall in `<devflowDir>/manifest.json`.
+ *
+ * The manifest is the install record init seeds from (a re-init keeps the prior
+ * selection), so a plugin `devflow uninstall --plugin` removed but the manifest
+ * still lists would come back on the next plain `devflow init`. This is the one
+ * writer that takes a name off that list (atomic temp + rename).
+ *
+ * A quiet no-op, not an error, when there is nothing to record: no manifest (a
+ * pre-manifest install), one that is not valid JSON or not manifest-shaped, or
+ * none of `names` listed — the file is left byte-identical. Never throws: a failed
+ * write comes back as `{ ok: false }` for the caller to report.
+ */
+export async function removeManifestPlugins(devflowDir, names) {
+    const manifestPath = path.join(devflowDir, 'manifest.json');
+    let raw;
+    try {
+        raw = JSON.parse(await fs.readFile(manifestPath, 'utf-8'));
+    }
+    catch {
+        // ENOENT, EACCES or SyntaxError — no usable manifest, so nothing to record.
+        return { ok: true, removed: [] };
+    }
+    const next = withoutManifestPlugins(raw, names, new Date().toISOString());
+    if (next === null)
+        return { ok: true, removed: [] };
+    try {
+        await writeFileAtomicExclusive(manifestPath, JSON.stringify(next, null, 2) + '\n');
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    const doomed = new Set(names);
+    const before = raw.plugins;
+    return { ok: true, removed: before.filter((entry) => typeof entry === 'string' && doomed.has(entry)) };
+}
 /**
  * Merge new plugins into existing plugin list (union, no duplicates).
  * Preserves order: existing plugins first, then new ones appended.

package/dist/core/mds-variants.js

@@ -120,6 +120,13 @@ export function validateContractOutputName(name) {
  * from here keeps the table below the only place a destination is spelled.
  */
 export const AGENTS_OUTPUT_DIR = 'dist/agents';
+/**
+ * Repo-relative destination for `commands` hosts.
+ *
+ * Exported for the same reason as AGENTS_OUTPUT_DIR: the orphan prune names the
+ * directory even when no command host is planned.
+ */
+export const COMMANDS_OUTPUT_DIR = 'dist/commands';
 /**
  * The bare (unprefixed) skill that OWNS the generated references.
  *
@@ -153,7 +160,7 @@ export const SKILL_REFS_SKILL_NAME = 'git';
  */
 export const SKILL_REFS_OUTPUT_DIR = `dist/skills/${SKILL_REFS_SKILL_NAME}/references`;
 const ALLOWED_OUTPUT_DIRS = [
-    { dir: 'dist/commands', variant: 'commands' },
+    { dir: COMMANDS_OUTPUT_DIR, variant: 'commands' },
     { dir: AGENTS_OUTPUT_DIR, variant: 'agents' },
     { dir: SKILL_REFS_OUTPUT_DIR, variant: 'skill-refs' },
 ];
@@ -264,32 +271,38 @@ export const TRACKER_OPS = [
  */
 export const TRACKER_GITHUB_OPS = TRACKER_OPS;
 /**
- * The 9 PR/review operations whose mechanics are generated once, for every
+ * The 8 PR/review operations whose references are generated once, for every
  * provider, under `pr/`.
  *
  * A PR-HOST roster, not a tracker roster, and the distinction is the whole
  * reason this list exists separately from {@link TRACKER_OPS}: pull requests, PR
  * reviews and PR checks stay on GitHub under every issue-tracker provider, so
- * these steps are the SAME file whatever `TRACKER_PROVIDER` resolves to. Filing
- * them under `tracker/github/` would make a jira user's PR mechanics read as
- * their tracker's, and fanning them across the three provider directories would
- * ship three identical trees.
- *
- * `ensure-pr-ready` is a member of BOTH rosters by design, and the two halves do
- * not overlap: the PR skeleton (branch/commit/push, create, retitle, and step
- * 4b's open-PR lookup and body edit) is a PR-host fact and lives here; step 4b
- * itself — the issue-number lookup and the link line it renders — is a tracker
- * fact and lives in `tracker/{provider}/ensure-pr-ready.md`. The operation
- * carries one pointer to each.
- *
- * 9 entries, one above {@link MIN_VARIANT_PAIRS}, which is a floor and not a
+ * these operations are the SAME file whatever `TRACKER_PROVIDER` resolves to.
+ * Filing them under `tracker/github/` would make a jira user's PR mechanics read
+ * as their tracker's, and fanning them across the three provider directories
+ * would ship three identical trees.
+ *
+ * D-OP-ONE-REF. Each file is the WHOLE operation: its contract (description,
+ * `**Input:**`, degradation notes, `**Output:**` template, written once in
+ * `src/assets/mds/git/_ops.mds`) and then its steps. The operation loads this one
+ * file and no other operation reference.
+ *
+ * `ensure-pr-ready` is deliberately NOT a member. It is a tracker operation: step
+ * 4b, the issue-number lookup and the link line it renders, is a tracker fact and
+ * differs per provider, so the operation is one file per provider under
+ * `tracker/{provider}/ensure-pr-ready.md`. That file carries the PR skeleton
+ * (branch/commit/push, create, retitle, and step 4b's open-PR lookup and body edit)
+ * as well, written once in `_ops.mds` and expanded into all three, so the PR-host
+ * half is the same bytes under every provider and the operation still loads one
+ * file.
+ *
+ * 8 entries, exactly {@link MIN_VARIANT_PAIRS}, which is a floor and not a
  * target: a shorter roster makes every parity assertion over it vacuous (GAP-42)
- * and `expandVariants` refuses the build, so the roster can grow
- * but never drop below 8. `update-pr-evidence` (#363) is the ninth — it edits the
- * PR body and comments on the PR, both GitHub whatever the tracker is.
+ * and `expandVariants` refuses the build, so the roster can grow but never drop
+ * below 8. `update-pr-evidence` (#363) is the newest member: it edits the PR body
+ * and comments on the PR, both GitHub whatever the tracker is.
  */
 export const PR_HOST_OPS = [
-    'ensure-pr-ready',
     'validate-branch',
     'post-review-summary',
     'check-ci-status',
@@ -347,6 +360,44 @@ export const GIT_CROSS_CUTTING_DOCS = [
     'publication-gate',
     'trust-rule',
 ];
+/**
+ * The Git operations whose one operation reference is a cross-cutting document
+ * rather than a per-op file in `pr/` or `tracker/{provider}/` (D-OP-ONE-REF).
+ *
+ * `learn-conventions` is the only one: it has no PR-host half and no provider half,
+ * so its reference is the named document {@link GIT_CROSS_CUTTING_DOCS} already emits
+ * at the references root. Its contract is compiled into that document like every
+ * other operation's (D-OP-CONTRACT-ONCE).
+ */
+export const DOC_BACKED_OPS = ['learn-conventions'];
+/**
+ * Every operation the Git agent routes, derived from the three rosters that emit its
+ * reference — never retyped. Each one loads exactly one operation reference
+ * ({@link operationReferenceRel}).
+ */
+export const GIT_OPERATIONS = [...PR_HOST_OPS, ...TRACKER_OPS, ...DOC_BACKED_OPS];
+/**
+ * The skill-relative path (under `references/`) of the one reference an operation
+ * loads, or `null` for a name that is not a Git operation.
+ *
+ * D-OP-ONE-REF. A PR-host operation is `pr/{op}.md`, the same file under every
+ * provider; a tracker operation is `tracker/{provider}/{op}.md` for the resolved
+ * provider; a doc-backed operation is its named document. The Git agent's
+ * `## Loading the mechanics` table states these paths in prose, and
+ * `tests/tracker/reference-reachability.test.ts` holds the table to this function.
+ *
+ * Total and pure: an unknown operation is `null`, never a throw. `ensure-pr-ready` is
+ * a tracker operation, so it resolves per provider even though its PR half is shared.
+ */
+export function operationReferenceRel(op, provider) {
+    if (TRACKER_OPS.includes(op))
+        return `${TRACKER_DESTINATION_ROOT}/${provider}/${op}.md`;
+    if (PR_HOST_OPS.includes(op))
+        return `${PR_HOST_DESTINATION_ROOT}/${op}.md`;
+    if (DOC_BACKED_OPS.includes(op))
+        return `${op}.md`;
+    return null;
+}
 /**
  * Every reference module the build knows about — a closed registry, read the
  * same way ALLOWED_OUTPUT_DIRS is read.
@@ -363,6 +414,28 @@ export const GIT_CROSS_CUTTING_DOCS = [
  * Registering a provider whose `subdir` is one of MCP_BACKED_PROVIDER_SUBDIRS is
  * also what opens the generation gate on the tool-call contract; see
  * {@link mcpContractIsGenerated}. There is no second edit and no flag.
+ *
+ * D-TRACKER-CONTRACT-ON-DEMAND. The last entry, `_contract.mds`, is the first
+ * UNGATED `kind: 'contract'` module (the tool-call contract of
+ * {@link MCP_CONTRACT_MODULE} is gated, so it is not in this array). It emits
+ * `tracker/_contract.md`: the provider resolution and the tracker input contract
+ * that used to sit in the always-loaded Git agent, where every spawn paid for
+ * them although most spawns run a PR-host operation that never touches the
+ * issue tracker. A spawn now reads the file once, only when it runs a tracker
+ * operation, before its first tracker step. The agent's `## Loading the mechanics`
+ * section is the one line that names it; it keeps the one-reference rule and the
+ * table naming every non-tracker operation's reference, which a PR-only spawn
+ * needs and which this file cannot instruct a spawn to load. It is ungated for
+ * the reason the registry's other provider-independent files are: every install
+ * carries every provider, GitHub included, so no registered provider is the
+ * condition it depends on.
+ *
+ * The budget clause: the file is a per-SPAWN term of each tracker row (GitHub,
+ * Jira, Linear), charged the way the tool-call contract is (`contractTerm` in
+ * tests/tracker/budget-model.ts) and added in `providerLoadedSet`. It is not part
+ * of `ownLoadForProvider`, of the PR-host row or of the per-operation load cap
+ * (D-OP-LOAD-CAP): the cap prices one operation's own reference, which is the same
+ * whichever tracker row it is read through.
  */
 export const VARIANT_MODULES = [
     {
@@ -395,6 +468,12 @@ export const VARIANT_MODULES = [
         kind: 'named',
         ops: GIT_CROSS_CUTTING_DOCS,
     },
+    {
+        source: 'src/assets/mds/tracker/_contract.mds',
+        subdir: 'tracker',
+        kind: 'contract',
+        ops: ['_contract'],
+    },
 ];
 // ---------------------------------------------------------------------------
 // The tool-call contract module, and the gate on its generation