@deftai/directive-core 0.90.0 → 0.92.0

package/dist/render/roadmap-render.js

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { assertWriteTargetSafe } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
-import { MIGRATOR_METADATA_KEY, ROADMAP_BANNER } from "./constants.js";
+import { MIGRATOR_METADATA_KEY, ROADMAP_BANNER, ROADMAP_COMPLETED_CAP, ROADMAP_EMPTY_FORWARD_MARKER, } from "./constants.js";
 import { phaseSortKey } from "./text-utils.js";
 function scopeMetadataRank(plan) {
     const metadata = plan.metadata;
@@ -246,16 +246,79 @@ function renderScopeItem(vbriefData) {
 function resolveCompletedDir(pendingDir, completedDir) {
     return completedDir ?? join(dirname(pendingDir), "completed");
 }
-/** Single render-to-buffer entry used by both write and --check (mirrors ``scripts/roadmap_render.generate_roadmap_content``). */
-export function renderRoadmapToBuffer(pendingDir, completedDir) {
-    const vbriefs = loadVbriefs(pendingDir);
-    const resolvedCompleted = resolveCompletedDir(pendingDir, completedDir);
-    const completedVbriefs = loadVbriefs(resolvedCompleted);
-    const lines = [ROADMAP_BANNER, "# Roadmap\n"];
-    if (vbriefs.length === 0 && completedVbriefs.length === 0) {
-        lines.push("No pending work items.\n");
-        return `${lines.join("\n")}\n`;
+function lifecycleSibling(pendingDir, bucket) {
+    return join(dirname(pendingDir), bucket);
+}
+function hasLifecycleArtifacts(dir) {
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).some((n) => hasArtifactSuffix(n));
+    }
+    catch {
+        return false;
     }
+}
+/**
+ * Prefer completion-time stamps over creation-dated filenames so the cap
+ * keeps recently completed scopes (#2653 Greptile P1).
+ * Order: plan.metadata.completedAt → plan.updated → envelope updated → _source_file.
+ */
+function completedRecencyKey(vbrief) {
+    const plan = (vbrief.plan ?? {});
+    const metadata = plan.metadata;
+    if (typeof metadata === "object" && metadata !== null && !Array.isArray(metadata)) {
+        const completedAt = metadata.completedAt;
+        if (typeof completedAt === "string" && completedAt.trim())
+            return completedAt.trim();
+    }
+    if (typeof plan.updated === "string" && plan.updated.trim())
+        return plan.updated.trim();
+    for (const envelopeKey of ["xBRIEFInfo", "vBRIEFInfo"]) {
+        const env = vbrief[envelopeKey];
+        if (typeof env === "object" && env !== null && !Array.isArray(env)) {
+            const updated = env.updated;
+            if (typeof updated === "string" && updated.trim())
+                return updated.trim();
+        }
+    }
+    return String(vbrief._source_file ?? "");
+}
+/** Newest-first by completion recency, then cap. */
+function takeCompletedCap(vbriefs, cap = ROADMAP_COMPLETED_CAP) {
+    const sorted = [...vbriefs].sort((a, b) => {
+        const kb = completedRecencyKey(b);
+        const ka = completedRecencyKey(a);
+        const byKey = kb.localeCompare(ka);
+        if (byKey !== 0)
+            return byKey;
+        return String(b._source_file ?? "").localeCompare(String(a._source_file ?? ""));
+    });
+    if (sorted.length <= cap) {
+        return { shown: sorted, total: sorted.length, omitted: 0 };
+    }
+    return {
+        shown: sorted.slice(0, cap),
+        total: sorted.length,
+        omitted: sorted.length - cap,
+    };
+}
+/** Flat list of scope bullets (proposed / active / completed). */
+function renderScopeList(vbriefs) {
+    const lines = [];
+    for (const vb of vbriefs)
+        lines.push(...renderScopeItem(vb));
+    if (vbriefs.length > 0)
+        lines.push("");
+    return lines;
+}
+/**
+ * Pending-only body: preserve phase-grouped and hierarchical heading models
+ * so existing ROADMAP consumers keep stable ## structure when pending is the
+ * sole forward source.
+ */
+function renderPendingBody(vbriefs) {
+    const lines = [];
     const hasPhaseNarratives = vbriefs.some((vb) => {
         const plan = (vb.plan ?? {});
         return Boolean(migratorField(plan, "Phase"));
@@ -292,57 +355,94 @@ export function renderRoadmapToBuffer(pendingDir, completedDir) {
                 lines.push("");
             }
         }
+        return lines;
     }
-    else {
-        for (const vbrief of vbriefs) {
-            const plan = (vbrief.plan ?? {});
-            const planTitle = String(plan.title ?? "Untitled");
-            const issueRefs = extractIssueRefs(plan.references);
-            const titleParts = [`## ${planTitle}`];
-            if (issueRefs.length > 0)
-                titleParts.push(`(${issueRefs.join(", ")})`);
-            lines.push(`${titleParts.join(" ")}\n`);
-            const narratives = plan.narratives;
-            if (typeof narratives === "object" && narratives !== null && !Array.isArray(narratives)) {
-                const overview = narratives.Overview;
-                if (typeof overview === "string" && overview)
-                    lines.push(`${overview}\n`);
-            }
-            const depMap = buildEdgeMap(vbrief);
-            const phases = Array.isArray(plan.items)
-                ? plan.items.filter((p) => typeof p === "object" && p !== null && !Array.isArray(p))
-                : [];
-            const sortedPhases = topoSortItems(phases, depMap);
-            for (const phase of sortedPhases) {
-                const phaseId = String(phase.id ?? "");
-                const phaseTitle = String(phase.title ?? "Untitled Phase");
-                const phaseStatus = String(phase.status ?? "");
-                let heading = phaseId ? `### ${phaseId}: ${phaseTitle}` : `### ${phaseTitle}`;
-                if (phaseStatus)
-                    heading += ` \`[${phaseStatus}]\``;
-                lines.push(`${heading}\n`);
-                const narrative = phase.narrative;
-                if (typeof narrative === "object" && narrative !== null && !Array.isArray(narrative)) {
-                    for (const [key, val] of Object.entries(narrative)) {
-                        if (key !== "Traces" && key !== "Acceptance")
-                            lines.push(`${String(val)}\n`);
-                    }
-                }
-                const subItems = phase.subItems;
-                if (Array.isArray(subItems) && subItems.length > 0) {
-                    const subs = subItems.filter((s) => typeof s === "object" && s !== null && !Array.isArray(s));
-                    const sortedSubs = topoSortItems(subs, depMap);
-                    for (const item of sortedSubs)
-                        lines.push(...renderItem(item, depMap));
-                    lines.push("");
+    for (const vbrief of vbriefs) {
+        const plan = (vbrief.plan ?? {});
+        const planTitle = String(plan.title ?? "Untitled");
+        const issueRefs = extractIssueRefs(plan.references);
+        const titleParts = [`## ${planTitle}`];
+        if (issueRefs.length > 0)
+            titleParts.push(`(${issueRefs.join(", ")})`);
+        lines.push(`${titleParts.join(" ")}\n`);
+        const narratives = plan.narratives;
+        if (typeof narratives === "object" && narratives !== null && !Array.isArray(narratives)) {
+            const overview = narratives.Overview;
+            if (typeof overview === "string" && overview)
+                lines.push(`${overview}\n`);
+        }
+        const depMap = buildEdgeMap(vbrief);
+        const phases = Array.isArray(plan.items)
+            ? plan.items.filter((p) => typeof p === "object" && p !== null && !Array.isArray(p))
+            : [];
+        const sortedPhases = topoSortItems(phases, depMap);
+        for (const phase of sortedPhases) {
+            const phaseId = String(phase.id ?? "");
+            const phaseTitle = String(phase.title ?? "Untitled Phase");
+            const phaseStatus = String(phase.status ?? "");
+            let heading = phaseId ? `### ${phaseId}: ${phaseTitle}` : `### ${phaseTitle}`;
+            if (phaseStatus)
+                heading += ` \`[${phaseStatus}]\``;
+            lines.push(`${heading}\n`);
+            const narrative = phase.narrative;
+            if (typeof narrative === "object" && narrative !== null && !Array.isArray(narrative)) {
+                for (const [key, val] of Object.entries(narrative)) {
+                    if (key !== "Traces" && key !== "Acceptance")
+                        lines.push(`${String(val)}\n`);
                 }
             }
-            lines.push("---\n");
+            const subItems = phase.subItems;
+            if (Array.isArray(subItems) && subItems.length > 0) {
+                const subs = subItems.filter((s) => typeof s === "object" && s !== null && !Array.isArray(s));
+                const sortedSubs = topoSortItems(subs, depMap);
+                for (const item of sortedSubs)
+                    lines.push(...renderItem(item, depMap));
+                lines.push("");
+            }
         }
+        lines.push("---\n");
+    }
+    return lines;
+}
+/** Single render-to-buffer entry used by both write and --check (mirrors ``scripts/roadmap_render.generate_roadmap_content``). */
+export function renderRoadmapToBuffer(pendingDir, completedDir) {
+    const pendingVbriefs = loadVbriefs(pendingDir);
+    const activeVbriefs = loadVbriefs(lifecycleSibling(pendingDir, "active"));
+    const proposedVbriefs = loadVbriefs(lifecycleSibling(pendingDir, "proposed"));
+    const resolvedCompleted = resolveCompletedDir(pendingDir, completedDir);
+    const completedVbriefs = loadVbriefs(resolvedCompleted);
+    const lines = [ROADMAP_BANNER, "# Roadmap\n"];
+    const hasForward = pendingVbriefs.length > 0 || activeVbriefs.length > 0 || proposedVbriefs.length > 0;
+    const hasAny = hasForward || completedVbriefs.length > 0;
+    if (!hasAny) {
+        lines.push("No pending work items.\n");
+        return `${lines.join("\n")}\n`;
+    }
+    // D2.2: never emit Completed-only without an explicit empty-forward marker.
+    if (!hasForward && completedVbriefs.length > 0) {
+        lines.push("## Forward plan\n");
+        lines.push(ROADMAP_EMPTY_FORWARD_MARKER);
+    }
+    if (pendingVbriefs.length > 0) {
+        lines.push(...renderPendingBody(pendingVbriefs));
+    }
+    if (activeVbriefs.length > 0) {
+        lines.push("## Active\n");
+        lines.push(...renderScopeList(activeVbriefs));
+    }
+    if (proposedVbriefs.length > 0) {
+        lines.push("## Proposed\n");
+        lines.push("_Scopes not yet promoted to pending. Orientation only — not a substitute for `task triage:queue`._\n");
+        lines.push(...renderScopeList(proposedVbriefs));
     }
     if (completedVbriefs.length > 0) {
+        const { shown, total, omitted } = takeCompletedCap(completedVbriefs);
         lines.push("## Completed\n");
-        for (const vb of completedVbriefs)
+        if (omitted > 0) {
+            lines.push(`_Showing ${shown.length} of ${total} completed scopes (newest first). ` +
+                `Full history: lifecycle \`completed/\` (or \`task report\` when available)._\n`);
+        }
+        for (const vb of shown)
             lines.push(...renderScopeItem(vb));
         lines.push("");
     }
@@ -378,19 +478,23 @@ export function renderRoadmap(pendingDir, outPath, completedDirOrOptions) {
 export function checkDrift(pendingDir, roadmapPath, completedDir) {
     const expected = renderRoadmapToBuffer(pendingDir, completedDir);
     if (!existsSync(roadmapPath)) {
-        const hasPending = existsSync(pendingDir) && readdirSync(pendingDir).some((n) => hasArtifactSuffix(n));
+        const hasPending = hasLifecycleArtifacts(pendingDir);
+        const hasActive = hasLifecycleArtifacts(lifecycleSibling(pendingDir, "active"));
+        const hasProposed = hasLifecycleArtifacts(lifecycleSibling(pendingDir, "proposed"));
         const inferredCompleted = resolveCompletedDir(pendingDir, completedDir);
-        const hasCompleted = existsSync(inferredCompleted) &&
-            readdirSync(inferredCompleted).some((n) => hasArtifactSuffix(n));
-        if (!hasPending && !hasCompleted) {
-            return [true, "✓ No ROADMAP.md needed (no pending or completed vBRIEFs)"];
+        const hasCompleted = hasLifecycleArtifacts(inferredCompleted);
+        if (!hasPending && !hasActive && !hasProposed && !hasCompleted) {
+            return [true, "✓ No ROADMAP.md needed (no lifecycle scope vBRIEFs)"];
         }
         return [false, "✗ ROADMAP.md does not exist but vBRIEFs found"];
     }
     const actual = readFileSync(roadmapPath, "utf8");
     if (actual === expected)
         return [true, "✓ ROADMAP.md is up to date"];
-    return [false, "✗ ROADMAP.md has drifted from pending/ vBRIEFs -- run: task roadmap:render"];
+    return [
+        false,
+        "✗ ROADMAP.md has drifted from lifecycle scope vBRIEFs -- run: task roadmap:render",
+    ];
 }
 /** CLI entry (mirrors ``scripts/roadmap_render.main``). */
 export function main(argv) {

package/dist/render/scope-outlook.d.ts

@@ -1,6 +1,11 @@
 export interface ScopeOutlookOptions {
     readonly includeProposed?: boolean;
     readonly proposedLimit?: number;
+    /**
+     * When false, omit the completed lifecycle bucket (#1566 compact render).
+     * Default true so callers that opt into full aggregation keep prior behavior.
+     */
+    readonly includeCompleted?: boolean;
 }
 /** Build Scope outlook section per #2013 Wave 0 §4. */
 export declare function buildScopeOutlookSection(vbriefDir: string, options?: ScopeOutlookOptions): string[];

package/dist/render/scope-outlook.js

@@ -203,6 +203,7 @@ function filterProposed(vb) {
 export function buildScopeOutlookSection(vbriefDir, options = {}) {
     const includeProposed = options.includeProposed ?? false;
     const proposedLimit = options.proposedLimit ?? 0;
+    const includeCompleted = options.includeCompleted ?? true;
     const buckets = [];
     if (includeProposed) {
         let proposed = loadScopeVbriefs(join(vbriefDir, "proposed")).filter(([, vb]) => filterProposed(vb));
@@ -220,6 +221,8 @@ export function buildScopeOutlookSection(vbriefDir, options = {}) {
         }
     }
     for (const [folder, heading, filter] of COMMITTED_BUCKETS) {
+        if (folder === "completed" && !includeCompleted)
+            continue;
         let scopes = loadScopeVbriefs(join(vbriefDir, folder));
         if (filter)
             scopes = scopes.filter(([, vb]) => filter(vb));

package/dist/render/spec-render.d.ts

@@ -1,12 +1,38 @@
+import { type IncludeScopesMode } from "./constants.js";
+/**
+ * Parse a string include-scopes token. Returns undefined when the token is not a known mode
+ * (callers MUST fail closed rather than silently omitting content — #1566 Greptile P1).
+ */
+export declare function tryParseIncludeScopesMode(value: string): IncludeScopesMode | undefined;
+/**
+ * Parse include-legacy-artifacts on/off tokens. undefined = invalid token.
+ */
+export declare function tryParseOnOffFlag(value: string): boolean | undefined;
+/**
+ * Normalize CLI / API include-scopes values to a mode (#1566).
+ * Default is compact (`off`) so completed lifecycle is not dumped into SPECIFICATION.md.
+ * Unknown string tokens throw — do not silently drop requested content.
+ */
+export declare function normalizeIncludeScopesMode(value: boolean | IncludeScopesMode | string | undefined, defaultMode?: IncludeScopesMode): IncludeScopesMode;
 export type RenderSpecResult = readonly [boolean, string];
 export interface RenderSpecOptions {
-    readonly includeScopes?: boolean;
+    /**
+     * Lifecycle scope aggregation (#1566).
+     * - `off` / false (default): no Scope outlook section
+     * - `current` / `active`: pending + active only
+     * - `all` / true / `on`: pending + active + completed (legacy dump)
+     */
+    readonly includeScopes?: boolean | IncludeScopesMode;
+    /** When true, emit the LegacyArtifacts narrative. Default false (#1566). */
+    readonly includeLegacyArtifacts?: boolean;
 }
 /** Render specification JSON to markdown (mirrors ``scripts/spec_render.render_spec``). */
 export declare function renderSpec(specPath: string, outPath: string, options?: RenderSpecOptions): RenderSpecResult;
 export declare function parseIncludeScopesFlag(argv: readonly string[]): {
-    includeScopes: boolean;
+    includeScopes: IncludeScopesMode;
+    includeLegacyArtifacts: boolean;
     remaining: string[];
+    errors: string[];
 };
 /** CLI entry (mirrors ``scripts/spec_render.main``). */
 export declare function main(argv: readonly string[]): number;

package/dist/render/spec-render.js

@@ -1,8 +1,9 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { RENDERABLE_SPEC_STATUSES, SPEC_RENDER_BANNER, SPECIFICATION_NARRATIVE_KEY_ORDER, } from "./constants.js";
-import { aggregateScopeSection } from "./scope-outlook.js";
+import { DEFAULT_INCLUDE_SCOPES_MODE, LEGACY_ARTIFACTS_NARRATIVE_KEY, RENDERABLE_SPEC_STATUSES, SPEC_RENDER_BANNER, SPECIFICATION_NARRATIVE_KEY_ORDER, } from "./constants.js";
+import { buildScopeOutlookSection } from "./scope-outlook.js";
 import { validateSpec } from "./spec-validate.js";
+import { stripTrailingWhitespace } from "./text-utils.js";
 function splitAcceptance(value) {
     if (Array.isArray(value)) {
         return value.map((item) => String(item).trim()).filter((s) => s.length > 0);
@@ -22,9 +23,63 @@ function splitAcceptance(value) {
     }
     return parts;
 }
+const INCLUDE_SCOPES_OFF = new Set(["off", "false", "0", "no"]);
+const INCLUDE_SCOPES_CURRENT = new Set(["current", "active"]);
+const INCLUDE_SCOPES_ALL = new Set(["all", "on", "true", "1", "yes"]);
+const LEGACY_ARTIFACTS_ON = new Set(["on", "true", "1", "yes"]);
+const LEGACY_ARTIFACTS_OFF = new Set(["off", "false", "0", "no"]);
+/**
+ * Parse a string include-scopes token. Returns undefined when the token is not a known mode
+ * (callers MUST fail closed rather than silently omitting content — #1566 Greptile P1).
+ */
+export function tryParseIncludeScopesMode(value) {
+    const v = value.trim().toLowerCase();
+    if (INCLUDE_SCOPES_OFF.has(v))
+        return "off";
+    if (INCLUDE_SCOPES_CURRENT.has(v))
+        return "current";
+    if (INCLUDE_SCOPES_ALL.has(v))
+        return "all";
+    return undefined;
+}
+/**
+ * Parse include-legacy-artifacts on/off tokens. undefined = invalid token.
+ */
+export function tryParseOnOffFlag(value) {
+    const v = value.trim().toLowerCase();
+    if (LEGACY_ARTIFACTS_ON.has(v))
+        return true;
+    if (LEGACY_ARTIFACTS_OFF.has(v))
+        return false;
+    return undefined;
+}
+/**
+ * Normalize CLI / API include-scopes values to a mode (#1566).
+ * Default is compact (`off`) so completed lifecycle is not dumped into SPECIFICATION.md.
+ * Unknown string tokens throw — do not silently drop requested content.
+ */
+export function normalizeIncludeScopesMode(value, defaultMode = DEFAULT_INCLUDE_SCOPES_MODE) {
+    if (value === undefined)
+        return defaultMode;
+    if (value === true)
+        return "all";
+    if (value === false)
+        return "off";
+    const parsed = tryParseIncludeScopesMode(String(value));
+    if (parsed === undefined) {
+        throw new Error(`Invalid include-scopes mode '${String(value)}' (expected off|current|all)`);
+    }
+    return parsed;
+}
+function shouldRenderNarrativeKey(key, includeLegacyArtifacts) {
+    if (includeLegacyArtifacts)
+        return true;
+    return key !== LEGACY_ARTIFACTS_NARRATIVE_KEY;
+}
 /** Render specification JSON to markdown (mirrors ``scripts/spec_render.render_spec``). */
 export function renderSpec(specPath, outPath, options = {}) {
-    const includeScopes = options.includeScopes ?? true;
+    const includeScopesMode = normalizeIncludeScopesMode(options.includeScopes);
+    const includeLegacyArtifacts = options.includeLegacyArtifacts ?? false;
     const [ok, msg] = validateSpec(specPath);
     if (!ok)
         return [false, msg];
@@ -70,6 +125,8 @@ export function renderSpec(specPath, outPath, options = {}) {
     }
     const renderedKeys = new Set();
     for (const key of SPECIFICATION_NARRATIVE_KEY_ORDER) {
+        if (!shouldRenderNarrativeKey(key, includeLegacyArtifacts))
+            continue;
         const val = narratives[key];
         if (val) {
             lines.push(`## ${key}\n`);
@@ -80,6 +137,8 @@ export function renderSpec(specPath, outPath, options = {}) {
     for (const key of Object.keys(narratives).sort()) {
         if (renderedKeys.has(key) || !narratives[key])
             continue;
+        if (!shouldRenderNarrativeKey(key, includeLegacyArtifacts))
+            continue;
         lines.push(`## ${key}\n`);
         lines.push(`${String(narratives[key])}\n`);
     }
@@ -129,44 +188,82 @@ export function renderSpec(specPath, outPath, options = {}) {
             }
         }
     }
-    if (includeScopes) {
+    if (includeScopesMode !== "off") {
         const vbriefDir = resolve(dirname(specPath));
-        const scopeLines = aggregateScopeSection(vbriefDir);
+        const scopeLines = buildScopeOutlookSection(vbriefDir, {
+            includeProposed: false,
+            includeCompleted: includeScopesMode === "all",
+        });
         if (scopeLines.length > 0)
             lines.push(...scopeLines);
     }
-    writeFileSync(outPath, lines.join("\n"), "utf8");
+    writeFileSync(outPath, stripTrailingWhitespace(lines.join("\n")), "utf8");
     return [true, `✓ Rendered to ${outPath}`];
 }
 export function parseIncludeScopesFlag(argv) {
-    let includeScopes = true;
+    let includeScopes = DEFAULT_INCLUDE_SCOPES_MODE;
+    let includeLegacyArtifacts = false;
     const remaining = [];
+    const errors = [];
     for (const arg of argv) {
         if (arg === "--include-scopes") {
-            includeScopes = true;
+            includeScopes = "all";
             continue;
         }
         if (arg.startsWith("--include-scopes=")) {
-            const value = arg.split("=", 2)[1]?.toLowerCase() ?? "";
-            includeScopes = value === "on" || value === "true" || value === "1" || value === "yes";
+            const value = arg.split("=", 2)[1] ?? "";
+            const parsed = tryParseIncludeScopesMode(value);
+            if (parsed === undefined) {
+                errors.push(`Invalid --include-scopes=${value} (expected off|current|all|active|on|true|1|yes|false|0|no)`);
+            }
+            else {
+                includeScopes = parsed;
+            }
+            continue;
+        }
+        if (arg === "--include-legacy-artifacts") {
+            includeLegacyArtifacts = true;
+            continue;
+        }
+        if (arg.startsWith("--include-legacy-artifacts=")) {
+            const value = arg.split("=", 2)[1] ?? "";
+            const parsed = tryParseOnOffFlag(value);
+            if (parsed === undefined) {
+                errors.push(`Invalid --include-legacy-artifacts=${value} (expected on|off|true|false|1|0|yes|no)`);
+            }
+            else {
+                includeLegacyArtifacts = parsed;
+            }
             continue;
         }
         remaining.push(arg);
     }
-    return { includeScopes, remaining };
+    return { includeScopes, includeLegacyArtifacts, remaining, errors };
 }
 /** CLI entry (mirrors ``scripts/spec_render.main``). */
 export function main(argv) {
-    const { includeScopes, remaining } = parseIncludeScopesFlag(argv);
+    const { includeScopes, includeLegacyArtifacts, remaining, errors } = parseIncludeScopesFlag(argv);
+    if (errors.length > 0) {
+        for (const err of errors)
+            process.stderr.write(`${err}\n`);
+        process.stderr.write("Usage: spec-render <spec_file> [out_file] " +
+            "[--include-scopes=off|current|all] [--include-legacy-artifacts=on|off]\n");
+        return 2;
+    }
     if (remaining.length === 0) {
-        process.stderr.write("Usage: spec_render.py <spec_file> [out_file] [--include-scopes=on|off]\n");
+        process.stderr.write("Usage: spec-render <spec_file> [out_file] " +
+            "[--include-scopes=off|current|all] [--include-legacy-artifacts=on|off]\n" +
+            "  Defaults (#1566): --include-scopes=off --include-legacy-artifacts=off\n");
         return 2;
     }
     const specPath = remaining[0] ?? "";
     const outPath = remaining.length >= 2
         ? (remaining[1] ?? "")
         : join(resolve(dirname(specPath)), "..", "SPECIFICATION.md");
-    const [ok, message] = renderSpec(specPath, outPath, { includeScopes });
+    const [ok, message] = renderSpec(specPath, outPath, {
+        includeScopes,
+        includeLegacyArtifacts,
+    });
     process.stdout.write(`${message}\n`);
     return ok ? 0 : 1;
 }

package/dist/render/text-utils.d.ts

@@ -5,4 +5,10 @@ export declare function splitWords(text: string): string[];
 /** Parse ``Phase N`` prefix for roadmap sorting (#641). */
 export declare function parsePhaseNumber(phaseName: string): number | null;
 export declare function phaseSortKey(phaseName: string): [number, number, string];
+/**
+ * Strip trailing horizontal whitespace from each line (#1566).
+ * Linear scan (no regex) so long runs of tabs/spaces cannot trip ReDoS scanners.
+ * Preserves newline structure (including a final trailing newline).
+ */
+export declare function stripTrailingWhitespace(text: string): string;
 //# sourceMappingURL=text-utils.d.ts.map

package/dist/render/text-utils.js

@@ -69,4 +69,27 @@ export function phaseSortKey(phaseName) {
         return [0, num, phaseName];
     return [1, 0, phaseName];
 }
+/**
+ * Strip trailing horizontal whitespace from each line (#1566).
+ * Linear scan (no regex) so long runs of tabs/spaces cannot trip ReDoS scanners.
+ * Preserves newline structure (including a final trailing newline).
+ */
+export function stripTrailingWhitespace(text) {
+    const lines = text.split("\n");
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        let end = line.length;
+        while (end > 0) {
+            const code = line.charCodeAt(end - 1);
+            // space, tab, non-breaking space
+            if (code === 0x20 || code === 0x09 || code === 0xa0)
+                end -= 1;
+            else
+                break;
+        }
+        if (end !== line.length)
+            lines[i] = line.slice(0, end);
+    }
+    return lines.join("\n");
+}
 //# sourceMappingURL=text-utils.js.map

package/dist/scm/binary.d.ts

@@ -6,6 +6,9 @@ export declare function defaultWhich(name: string): string | null;
 /**
  * Return `"ghx"` if on PATH, else `"gh"`; raise if neither is present.
  * Mirrors `scripts/scm.py::resolve_binary`.
+ *
+ * On failure the message is the #2275 fail-loud diagnostic (execution-env
+ * boundary + remediation), not an opaque spawn error.
  */
 export declare function resolveBinary(whichFn?: WhichFn): string;
 //# sourceMappingURL=binary.d.ts.map

package/dist/scm/binary.js

@@ -22,6 +22,9 @@ export function defaultWhich(name) {
 /**
  * Return `"ghx"` if on PATH, else `"gh"`; raise if neither is present.
  * Mirrors `scripts/scm.py::resolve_binary`.
+ *
+ * On failure the message is the #2275 fail-loud diagnostic (execution-env
+ * boundary + remediation), not an opaque spawn error.
  */
 export function resolveBinary(whichFn = defaultWhich) {
     for (const candidate of BINARY_PREFERENCE) {
@@ -29,7 +32,12 @@ export function resolveBinary(whichFn = defaultWhich) {
             return candidate;
         }
     }
-    throw new ScmStubError("neither 'ghx' nor 'gh' found on PATH; install GitHub CLI " +
-        "(https://cli.github.com/) or the ghx proxy (#884)");
+    // Keep the historical substring for existing tests / triage mappers, then
+    // append the #2275 execution-env remediation so agents see a named reason.
+    throw new ScmStubError("neither 'ghx' nor 'gh' found on PATH in this execution env; " +
+        "install GitHub CLI (https://cli.github.com/) or the ghx proxy (#884), " +
+        "or pass GH_TOKEN into a matched env and re-run; SCM-dependent gates " +
+        "(triage:queue, issue:ingest, pr:*, reconcile:issues, cache:fetch-all, scm:*) " +
+        "cannot run here. Framework-local gates do not need SCM. Refs #2275.");
 }
 //# sourceMappingURL=binary.js.map

package/dist/scm/call.d.ts

@@ -20,6 +20,11 @@ export interface CallOptions {
 /**
  * Source-aware SCM invocation -- partial down-payment on #445 / #935 Workstream 6.
  * Mirrors `scripts/scm.py::call`.
+ *
+ * Binary absence still throws ScmStubError via resolveBinary with the #2275
+ * diagnostic. Full auth readiness is enforced at SCM CLI entry points
+ * (`scm/main`, issue-ingest, reconcile-issues) via requireScmReady — not on
+ * every call() — so unit tests that inject binary/seams stay hermetic.
  */
 export declare function call(source: string, verb: string, args?: readonly string[] | null, options?: CallOptions): CompletedProcess;
 //# sourceMappingURL=call.d.ts.map

package/dist/scm/call.js

@@ -5,6 +5,11 @@ import { pyRepr } from "./py-format.js";
 /**
  * Source-aware SCM invocation -- partial down-payment on #445 / #935 Workstream 6.
  * Mirrors `scripts/scm.py::call`.
+ *
+ * Binary absence still throws ScmStubError via resolveBinary with the #2275
+ * diagnostic. Full auth readiness is enforced at SCM CLI entry points
+ * (`scm/main`, issue-ingest, reconcile-issues) via requireScmReady — not on
+ * every call() — so unit tests that inject binary/seams stay hermetic.
  */
 export function call(source, verb, args = null, options = {}) {
     if (!SUPPORTED_CALL_SOURCES.includes(source)) {

package/dist/scm/index.d.ts

@@ -7,5 +7,6 @@ export * from "./errors.js";
 export * from "./gh-rest.js";
 export * from "./main.js";
 export * from "./py-format.js";
+export * from "./readiness.js";
 export * from "./rest-dispatch.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/scm/index.js

@@ -7,5 +7,6 @@ export * from "./errors.js";
 export * from "./gh-rest.js";
 export * from "./main.js";
 export * from "./py-format.js";
+export * from "./readiness.js";
 export * from "./rest-dispatch.js";
 //# sourceMappingURL=index.js.map