@deftai/directive-core 0.55.0

package/dist/release-rollback/guard.js

@@ -0,0 +1,97 @@
+import { DEFAULT_BOT_THRESHOLD, DOUBLE_READ_SLEEP_SECONDS, FIVE_MINUTES_SECONDS, THIRTY_MINUTES_SECONDS, } from "./constants.js";
+import { ghReleaseViewJson } from "./gh.js";
+export function sumDownloads(payload) {
+    const assets = payload.assets ?? [];
+    let total = 0;
+    for (const asset of assets) {
+        const count = asset.downloadCount;
+        const parsed = Number(count);
+        if (!Number.isNaN(parsed)) {
+            total += parsed;
+        }
+    }
+    return total;
+}
+export function releaseAgeSeconds(payload, now = new Date()) {
+    const createdAt = payload.createdAt ?? payload.publishedAt;
+    if (!createdAt) {
+        return 0;
+    }
+    try {
+        let normalized = createdAt;
+        if (normalized.endsWith("Z")) {
+            normalized = `${normalized.slice(0, -1)}+00:00`;
+        }
+        const dt = new Date(normalized);
+        if (Number.isNaN(dt.getTime())) {
+            return 0;
+        }
+        const deltaMs = now.getTime() - dt.getTime();
+        return Math.max(0, Math.floor(deltaMs / 1000));
+    }
+    catch {
+        return 0;
+    }
+}
+export function computeThreshold(ageSeconds, options) {
+    const { allowLowDownloads, allowDataLoss, forceStrict0 } = options;
+    if (forceStrict0) {
+        return [0, "--force-strict-0 override (require exactly 0 downloads)"];
+    }
+    if (allowDataLoss) {
+        return [2 ** 31 - 1, "--allow-data-loss override (accept any count)"];
+    }
+    if (ageSeconds < FIVE_MINUTES_SECONDS) {
+        return [0, "release age < 5 min; threshold=0 (rollback safe)"];
+    }
+    if (ageSeconds < THIRTY_MINUTES_SECONDS) {
+        const threshold = Math.max(allowLowDownloads, DEFAULT_BOT_THRESHOLD);
+        return [
+            threshold,
+            `release age 5-30 min; threshold=${threshold} ` +
+                `(filters bot fetches; --allow-low-downloads=${allowLowDownloads})`,
+        ];
+    }
+    return [
+        null,
+        "release age > 30 min; downloads likely consumer-driven. " +
+            "Pass --allow-data-loss to acknowledge consumer impact, OR " +
+            "abandon rollback in favour of a hot-fix release with a " +
+            "withdrawal note in the next CHANGELOG entry.",
+    ];
+}
+export function doubleReadDownloads(version, repo, options = {}, seams = {}) {
+    const sleepSeconds = options.sleepSeconds ?? DOUBLE_READ_SLEEP_SECONDS;
+    const [ok1, payload1, reason1] = ghReleaseViewJson(version, repo, seams);
+    if (!ok1 || payload1 === null) {
+        return [false, 0, 0, `first read failed: ${reason1}`];
+    }
+    const firstCount = sumDownloads(payload1);
+    if (sleepSeconds > 0) {
+        const sleepFn = seams.sleep ??
+            ((seconds) => {
+                const start = Date.now();
+                while (Date.now() - start < seconds * 1000) {
+                    // busy-wait fallback
+                }
+            });
+        sleepFn(sleepSeconds);
+    }
+    const [ok2, payload2, reason2] = ghReleaseViewJson(version, repo, seams);
+    if (!ok2 || payload2 === null) {
+        return [false, firstCount, 0, `second read failed: ${reason2}`];
+    }
+    const secondCount = sumDownloads(payload2);
+    if (secondCount > firstCount) {
+        return [
+            false,
+            firstCount,
+            secondCount,
+            `download_count grew between reads (${firstCount} -> ` +
+                `${secondCount}); a real consumer downloaded the asset during ` +
+                "the rollback window. Re-run with the new count visible.",
+        ];
+    }
+    return [true, firstCount, secondCount, ""];
+}
+//# sourceMappingURL=guard.js.map

package/dist/release-rollback/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./constants.js";
+export * from "./flags.js";
+export * from "./gh.js";
+export * from "./git.js";
+export * from "./guard.js";
+export * from "./main.js";
+export * from "./pipeline.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/release-rollback/index.js

@@ -0,0 +1,10 @@
+/* v8 ignore file -- re-export barrel; covered via main.ts */
+export * from "./constants.js";
+export * from "./flags.js";
+export * from "./gh.js";
+export * from "./git.js";
+export * from "./guard.js";
+export * from "./main.js";
+export * from "./pipeline.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/release-rollback/main.d.ts

@@ -0,0 +1,3 @@
+import type { RollbackSeams } from "./types.js";
+export declare function cmdRollback(args: readonly string[], seams?: RollbackSeams): number;
+//# sourceMappingURL=main.d.ts.map

package/dist/release-rollback/main.js

@@ -0,0 +1,51 @@
+import { resolveProjectRoot, resolveRepo } from "../release/paths.js";
+import { validateVersion } from "../release/version.js";
+import { EXIT_CONFIG_ERROR, ROLLBACK_USAGE_SHORT } from "./constants.js";
+import { formatRollbackHelp, parseRollbackFlags } from "./flags.js";
+import { runRollback } from "./pipeline.js";
+export function cmdRollback(args, seams = {}) {
+    const flags = parseRollbackFlags(args);
+    if (flags.help) {
+        process.stdout.write(formatRollbackHelp());
+        return 0;
+    }
+    if (flags.parseError) {
+        process.stderr.write(ROLLBACK_USAGE_SHORT);
+        process.stderr.write(`release_rollback: error: ${flags.parseError}\n`);
+        return EXIT_CONFIG_ERROR;
+    }
+    if (flags.unknown.length > 0) {
+        process.stderr.write(`release_rollback: error: unrecognized arguments: ${flags.unknown.join(" ")}\n`);
+        return EXIT_CONFIG_ERROR;
+    }
+    if (flags.version === null) {
+        process.stderr.write("release_rollback: error: the following arguments are required: version\n");
+        return EXIT_CONFIG_ERROR;
+    }
+    try {
+        validateVersion(flags.version);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Error: ${msg}\n`);
+        return EXIT_CONFIG_ERROR;
+    }
+    const projectRoot = resolveProjectRoot(flags.projectRoot);
+    const repo = resolveRepo(flags.repo, projectRoot, seams);
+    if (flags.allowLowDownloads < 0) {
+        process.stderr.write(`Error: --allow-low-downloads must be >= 0 (got ${flags.allowLowDownloads}).\n`);
+        return EXIT_CONFIG_ERROR;
+    }
+    const config = {
+        version: flags.version,
+        repo,
+        baseBranch: flags.baseBranch,
+        projectRoot,
+        dryRun: flags.dryRun,
+        allowLowDownloads: flags.allowLowDownloads,
+        allowDataLoss: flags.allowDataLoss,
+        forceStrict0: flags.forceStrict0,
+    };
+    return runRollback(config, seams);
+}
+//# sourceMappingURL=main.js.map

package/dist/release-rollback/pipeline.d.ts

@@ -0,0 +1,7 @@
+import type { GhReleasePayload, RollbackConfig, RollbackSeams } from "./types.js";
+export declare function detectState(config: RollbackConfig, seams?: RollbackSeams): [string, GhReleasePayload | null, string];
+export declare function unwindLocal(config: RollbackConfig, seams?: RollbackSeams): number;
+export declare function unwindTagPushedNoRelease(config: RollbackConfig, seams?: RollbackSeams): number;
+export declare function unwindReleased(config: RollbackConfig, payload: GhReleasePayload, seams?: RollbackSeams): number;
+export declare function runRollback(config: RollbackConfig, seams?: RollbackSeams): number;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/release-rollback/pipeline.js

@@ -0,0 +1,221 @@
+import { DOUBLE_READ_SLEEP_SECONDS, EXIT_OK, EXIT_VIOLATION } from "./constants.js";
+import { ghReleaseDelete, ghReleaseExists } from "./gh.js";
+import { gitDeleteLocalTag, gitDeleteRemoteTag, gitPushBase, gitRevertReleaseCommit, gitTagExistsLocal, gitTagExistsOrigin, resolveReleasePrepSha, } from "./git.js";
+import { computeThreshold, doubleReadDownloads, releaseAgeSeconds } from "./guard.js";
+function defaultEmit(label, status) {
+    process.stderr.write(`[rollback] ${label}... ${status}\n`);
+}
+function emit(label, status, seams) {
+    (seams.emit ?? defaultEmit)(label, status);
+}
+export function detectState(config, seams = {}) {
+    const { projectRoot, version, repo } = config;
+    const [state, payload, reason] = ghReleaseExists(version, repo, seams);
+    if (state === "exists") {
+        return ["released", payload, ""];
+    }
+    if (state === "error") {
+        return ["error", null, reason];
+    }
+    const local = gitTagExistsLocal(projectRoot, version, seams);
+    const remote = gitTagExistsOrigin(projectRoot, version, seams);
+    if (remote) {
+        return ["tag-pushed-no-release", null, ""];
+    }
+    if (local) {
+        return ["local-only", null, ""];
+    }
+    return ["absent", null, ""];
+}
+function resolvePrepShaOrEmit(config, seams) {
+    const [sha, reason] = resolveReleasePrepSha(config.projectRoot, config.version, seams);
+    if (!sha) {
+        emit(`Resolve release-prep SHA for v${config.version}`, `FAIL (${reason})`, seams);
+        return ["", EXIT_VIOLATION];
+    }
+    emit(`Resolve release-prep SHA for v${config.version}`, `OK (${sha})`, seams);
+    return [sha, null];
+}
+export function unwindLocal(config, seams = {}) {
+    const { projectRoot, version } = config;
+    if (config.dryRun) {
+        emit(`Unwind local v${version}`, `DRYRUN (would resolve release-prep SHA + run ` +
+            `\`git tag -d v${version}\` + \`git revert <sha> --no-edit\`)`, seams);
+        return EXIT_OK;
+    }
+    const [sha, refusal] = resolvePrepShaOrEmit(config, seams);
+    if (refusal !== null) {
+        return refusal;
+    }
+    const [ok, reason] = gitDeleteLocalTag(projectRoot, version, seams);
+    if (!ok) {
+        emit(`Delete local tag v${version}`, `FAIL (${reason})`, seams);
+        return EXIT_VIOLATION;
+    }
+    emit(`Delete local tag v${version}`, `OK (${reason})`, seams);
+    const [revertOk, revertReason] = gitRevertReleaseCommit(projectRoot, sha, seams);
+    if (!revertOk) {
+        emit(`Revert release-prep commit ${sha.slice(0, 12)}`, `FAIL (${revertReason})`, seams);
+        return EXIT_VIOLATION;
+    }
+    emit(`Revert release-prep commit ${sha.slice(0, 12)}`, `OK (${revertReason})`, seams);
+    return EXIT_OK;
+}
+export function unwindTagPushedNoRelease(config, seams = {}) {
+    const { projectRoot, version, baseBranch } = config;
+    if (config.dryRun) {
+        emit(`Unwind pushed tag v${version}`, `DRYRUN (would resolve release-prep SHA + run ` +
+            `\`git push --delete origin v${version}\` + ` +
+            `\`git tag -d v${version}\` + \`git revert <sha> --no-edit\` + ` +
+            `\`git push origin ${baseBranch}\` (no force))`, seams);
+        return EXIT_OK;
+    }
+    const [sha, refusal] = resolvePrepShaOrEmit(config, seams);
+    if (refusal !== null) {
+        return refusal;
+    }
+    const [remoteOk, remoteReason] = gitDeleteRemoteTag(projectRoot, version, seams);
+    if (!remoteOk) {
+        emit(`Delete remote tag v${version}`, `FAIL (${remoteReason})`, seams);
+        return EXIT_VIOLATION;
+    }
+    emit(`Delete remote tag v${version}`, `OK (${remoteReason})`, seams);
+    if (gitTagExistsLocal(projectRoot, version, seams)) {
+        const [localOk, localReason] = gitDeleteLocalTag(projectRoot, version, seams);
+        if (!localOk) {
+            emit(`Delete local tag v${version}`, `FAIL (${localReason})`, seams);
+            return EXIT_VIOLATION;
+        }
+        emit(`Delete local tag v${version}`, `OK (${localReason})`, seams);
+    }
+    const [revertOk, revertReason] = gitRevertReleaseCommit(projectRoot, sha, seams);
+    if (!revertOk) {
+        emit(`Revert release-prep commit ${sha.slice(0, 12)}`, `FAIL (${revertReason})`, seams);
+        return EXIT_VIOLATION;
+    }
+    emit(`Revert release-prep commit ${sha.slice(0, 12)}`, `OK (${revertReason})`, seams);
+    const [pushOk, pushReason] = gitPushBase(projectRoot, baseBranch, seams);
+    if (!pushOk) {
+        emit(`Push ${baseBranch} to origin`, `FAIL (${pushReason})`, seams);
+        return EXIT_VIOLATION;
+    }
+    emit(`Push ${baseBranch} to origin`, `OK (${pushReason})`, seams);
+    return EXIT_OK;
+}
+export function unwindReleased(config, payload, seams = {}) {
+    const { projectRoot, version, repo } = config;
+    const ageSeconds = releaseAgeSeconds(payload);
+    const [threshold, thresholdReason] = computeThreshold(ageSeconds, {
+        allowLowDownloads: config.allowLowDownloads,
+        allowDataLoss: config.allowDataLoss,
+        forceStrict0: config.forceStrict0,
+    });
+    emit(`Compute guard threshold (age=${ageSeconds}s)`, thresholdReason, seams);
+    if (threshold === null) {
+        emit("Guard refusal", "FAIL (release > 30 min old without --allow-data-loss; " +
+            "see hot-fix-path recommendation in script docstring)", seams);
+        return EXIT_VIOLATION;
+    }
+    if (config.dryRun) {
+        emit(`Double-read download_count (threshold=${threshold})`, "DRYRUN (would read download_count, sleep 5s, re-read)", seams);
+        emit(`Delete release v${version}`, `DRYRUN (would run \`gh release delete v${version} --yes --cleanup-tag\`)`, seams);
+        emit(`Revert release-prep commit for v${version}`, `DRYRUN (would resolve release-prep SHA + run ` +
+            `\`git revert <sha> --no-edit\` + \`git push origin ` +
+            `${config.baseBranch}\` (no force))`, seams);
+        return EXIT_OK;
+    }
+    const [sha, refusal] = resolvePrepShaOrEmit(config, seams);
+    if (refusal !== null) {
+        return refusal;
+    }
+    const sleepSeconds = config.skipSleep ? 0 : DOUBLE_READ_SLEEP_SECONDS;
+    const [ok, firstCount, secondCount, reason] = doubleReadDownloads(version, repo, { sleepSeconds }, seams);
+    emit(`Double-read download_count (threshold=${threshold})`, `first=${firstCount}, second=${secondCount}, ok=${ok}; reason: ${reason || "agreed"}`, seams);
+    if (!ok) {
+        return EXIT_VIOLATION;
+    }
+    if (Math.max(firstCount, secondCount) > threshold) {
+        emit("Guard refusal", `FAIL (download_count=${Math.max(firstCount, secondCount)} > ` +
+            `threshold=${threshold}; pass --allow-low-downloads or ` +
+            "--allow-data-loss to override)", seams);
+        return EXIT_VIOLATION;
+    }
+    const [deleteOk, deleteReason] = ghReleaseDelete(version, repo, seams);
+    if (!deleteOk) {
+        emit(`Delete release v${version}`, `FAIL (${deleteReason})`, seams);
+        return EXIT_VIOLATION;
+    }
+    emit(`Delete release v${version}`, `OK (${deleteReason})`, seams);
+    if (gitTagExistsLocal(projectRoot, version, seams)) {
+        const [localOk, localReason] = gitDeleteLocalTag(projectRoot, version, seams);
+        if (!localOk) {
+            emit(`Delete local tag v${version}`, `WARN (${localReason})`, seams);
+        }
+        else {
+            emit(`Delete local tag v${version}`, `OK (${localReason})`, seams);
+        }
+    }
+    const [revertOk, revertReason] = gitRevertReleaseCommit(projectRoot, sha, seams);
+    if (!revertOk) {
+        emit(`Revert release-prep commit ${sha.slice(0, 12)}`, `FAIL (${revertReason})`, seams);
+        return EXIT_VIOLATION;
+    }
+    emit(`Revert release-prep commit ${sha.slice(0, 12)}`, `OK (${revertReason})`, seams);
+    const [pushOk, pushReason] = gitPushBase(projectRoot, config.baseBranch, seams);
+    if (!pushOk) {
+        emit(`Push ${config.baseBranch} to origin`, `FAIL (${pushReason})`, seams);
+        return EXIT_VIOLATION;
+    }
+    emit(`Push ${config.baseBranch} to origin`, `OK (${pushReason})`, seams);
+    return EXIT_OK;
+}
+export function runRollback(config, seams = {}) {
+    if (config.dryRun) {
+        emit("Detect post-release state", `DRYRUN (would probe gh release view v${config.version} + git tag -l + git ls-remote)`, seams);
+        const [state, payload, reason] = detectState(config, seams);
+        emit("State (dry-run probe)", `${state} (${reason || "no reason"})`, seams);
+        if (state === "absent") {
+            emit("Rollback", "DRYRUN (no-op; nothing to unwind)", seams);
+            return EXIT_OK;
+        }
+        if (state === "local-only") {
+            return unwindLocal(config, seams);
+        }
+        if (state === "tag-pushed-no-release") {
+            return unwindTagPushedNoRelease(config, seams);
+        }
+        if (state === "released" && payload !== null) {
+            return unwindReleased(config, payload, seams);
+        }
+        if (state === "error") {
+            emit("State probe", `FAIL (${reason})`, seams);
+            return EXIT_VIOLATION;
+        }
+        return EXIT_OK;
+    }
+    const [state, payload, reason] = detectState(config, seams);
+    emit("Detect post-release state", `${state} (${reason || "ok"})`, seams);
+    if (state === "absent") {
+        emit("Rollback", "NOOP (no local tag, no remote tag, no release)", seams);
+        return EXIT_OK;
+    }
+    if (state === "error") {
+        return EXIT_VIOLATION;
+    }
+    if (state === "local-only") {
+        return unwindLocal(config, seams);
+    }
+    if (state === "tag-pushed-no-release") {
+        return unwindTagPushedNoRelease(config, seams);
+    }
+    if (state === "released") {
+        if (payload === null) {
+            emit("Rollback", "FAIL (released state without payload)", seams);
+            return EXIT_VIOLATION;
+        }
+        return unwindReleased(config, payload, seams);
+    }
+    emit("Rollback", `FAIL (unknown state '${state}')`, seams);
+    return EXIT_VIOLATION;
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/release-rollback/types.d.ts

@@ -0,0 +1,41 @@
+import type { ReleaseSeams } from "../release/types.js";
+export interface RollbackConfig {
+    readonly version: string;
+    readonly repo: string;
+    readonly baseBranch: string;
+    readonly projectRoot: string;
+    readonly dryRun: boolean;
+    readonly allowLowDownloads: number;
+    readonly allowDataLoss: boolean;
+    readonly forceStrict0: boolean;
+    readonly skipSleep?: boolean;
+}
+export interface RollbackFlags {
+    readonly help: boolean;
+    readonly version: string | null;
+    readonly repo: string | null;
+    readonly baseBranch: string;
+    readonly projectRoot: string | null;
+    readonly dryRun: boolean;
+    readonly allowLowDownloads: number;
+    readonly allowDataLoss: boolean;
+    readonly forceStrict0: boolean;
+    readonly unknown: readonly string[];
+    readonly parseError: string | null;
+}
+export interface GhReleasePayload {
+    readonly isDraft?: boolean;
+    readonly name?: string;
+    readonly tagName?: string;
+    readonly createdAt?: string;
+    readonly publishedAt?: string;
+    readonly assets?: ReadonlyArray<{
+        readonly downloadCount?: unknown;
+    }>;
+    readonly url?: string;
+}
+export type RollbackSeams = ReleaseSeams & {
+    readonly emit?: (label: string, status: string) => void;
+    readonly ghReleaseViewJson?: (version: string, repo: string) => [boolean, GhReleasePayload | null, string];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/release-rollback/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/render/constants.d.ts

@@ -0,0 +1,16 @@
+/** Canonical v0.6 status enum (matches `scripts/spec_validate.py`). */
+export declare const VALID_STATUSES: Set<string>;
+export declare const VALID_VBRIEF_VERSIONS: Set<string>;
+export declare const SPECIFICATION_NARRATIVE_KEY_ORDER: readonly ["Overview", "ProblemStatement", "Goals", "UserStories", "Requirements", "SuccessMetrics", "EdgeCases", "Architecture", "TechDecisions", "ImplementationPhases", "PreImplementationGates"];
+export declare const LIFECYCLE_BUCKETS: ReadonlyArray<readonly [string, string]>;
+export declare const SPEC_RENDER_BANNER: string;
+export declare const PRD_NARRATIVE_KEY_ORDER: readonly ["Overview", "ProblemStatement", "Goals", "UserStories", "Requirements", "SuccessMetrics", "Architecture"];
+export declare const PRD_BANNER: string;
+export declare const PRD_GENERATED_SENTINEL = "AUTO-GENERATED by task prd:render";
+export declare const ROADMAP_BANNER: string;
+export declare const MIGRATOR_METADATA_KEY = "x-migrator";
+export declare const PROJECT_LIFECYCLE_FOLDERS: readonly ["proposed", "pending", "active", "completed", "cancelled"];
+export declare const SKELETON_NARRATIVES: Readonly<Record<string, string>>;
+export declare const SCOPE_SUMMARY_NARRATIVES: readonly ["Overview", "Summary", "Description", "ProblemStatement", "Problem", "Outcome"];
+export declare const RENDERABLE_SPEC_STATUSES: Set<string>;
+//# sourceMappingURL=constants.d.ts.map

package/dist/render/constants.js

@@ -0,0 +1,78 @@
+/** Canonical v0.6 status enum (matches `scripts/spec_validate.py`). */
+export const VALID_STATUSES = new Set([
+    "draft",
+    "proposed",
+    "approved",
+    "pending",
+    "running",
+    "completed",
+    "blocked",
+    "failed",
+    "cancelled",
+]);
+export const VALID_VBRIEF_VERSIONS = new Set(["0.6"]);
+export const SPECIFICATION_NARRATIVE_KEY_ORDER = [
+    "Overview",
+    "ProblemStatement",
+    "Goals",
+    "UserStories",
+    "Requirements",
+    "SuccessMetrics",
+    "EdgeCases",
+    "Architecture",
+    "TechDecisions",
+    "ImplementationPhases",
+    "PreImplementationGates",
+];
+export const LIFECYCLE_BUCKETS = [
+    ["pending", "Pending"],
+    ["active", "Active"],
+    ["completed", "Completed"],
+];
+export const SPEC_RENDER_BANNER = "<!-- AUTO-GENERATED by task spec:render -- DO NOT EDIT MANUALLY -->\n" +
+    "<!-- Purpose: rendered specification -->\n" +
+    "<!-- Source of truth: vbrief/specification.vbrief.json -->\n" +
+    "<!-- Regenerate with: task spec:render -->\n";
+export const PRD_NARRATIVE_KEY_ORDER = [
+    "Overview",
+    "ProblemStatement",
+    "Goals",
+    "UserStories",
+    "Requirements",
+    "SuccessMetrics",
+    "Architecture",
+];
+export const PRD_BANNER = "<!-- AUTO-GENERATED by task prd:render -- DO NOT EDIT MANUALLY -->\n" +
+    "<!-- Purpose: rendered PRD -->\n" +
+    "<!-- Source of truth: vbrief/specification.vbrief.json -->\n" +
+    "<!-- Regenerate with: task prd:render -->\n";
+export const PRD_GENERATED_SENTINEL = "AUTO-GENERATED by task prd:render";
+export const ROADMAP_BANNER = "<!-- AUTO-GENERATED by task roadmap:render -- DO NOT EDIT MANUALLY -->\n" +
+    "<!-- Purpose: rendered roadmap -->\n" +
+    "<!-- Source of truth: vbrief/pending/ (scope vBRIEFs) -->\n" +
+    "<!-- Regenerate with: task roadmap:render -->\n";
+export const MIGRATOR_METADATA_KEY = "x-migrator";
+export const PROJECT_LIFECYCLE_FOLDERS = [
+    "proposed",
+    "pending",
+    "active",
+    "completed",
+    "cancelled",
+];
+export const SKELETON_NARRATIVES = {
+    Overview: "",
+    "tech stack": "",
+    Architecture: "",
+    RisksAndUnknowns: "",
+    Configuration: "",
+};
+export const SCOPE_SUMMARY_NARRATIVES = [
+    "Overview",
+    "Summary",
+    "Description",
+    "ProblemStatement",
+    "Problem",
+    "Outcome",
+];
+export const RENDERABLE_SPEC_STATUSES = new Set(["approved", "running", "completed"]);
+//# sourceMappingURL=constants.js.map

package/dist/render/framework-commands.d.ts

@@ -0,0 +1,41 @@
+export type RootMode = "project" | "framework";
+export interface CommandResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface CommandSpec {
+    readonly name: string;
+    readonly entrypoint?: string;
+    readonly defaultArgs?: readonly string[];
+    readonly projectRootArg?: string;
+    readonly frameworkRootArg?: string;
+    readonly vbriefDirArg?: string;
+    readonly rootArg?: string;
+    readonly cwd?: RootMode;
+    readonly noArgv?: boolean;
+    readonly aggregate?: readonly string[];
+    readonly description?: string;
+}
+export declare const COMMANDS: Readonly<Record<string, CommandSpec>>;
+export declare function availableCommands(): readonly string[];
+export declare function hasCommand(name: string): boolean;
+export declare function normalizeTaskSeparator(argv: readonly string[]): string[];
+export declare function formatFrameworkCommand(args: readonly string[], options?: {
+    surface?: string;
+    taskPrefix?: string | null;
+}): string;
+export declare function cmdCoreValidate(argv: readonly string[]): number;
+export declare function cmdCoreLint(argv: readonly string[]): number;
+export declare function cmdCoreTest(argv: readonly string[]): number;
+export declare function resolveFrameworkRoot(): string;
+export interface RunFrameworkCommandOptions {
+    readonly projectRoot?: string;
+    readonly frameworkRoot?: string;
+    readonly capture?: boolean;
+    readonly outputFn?: (line: string) => void;
+}
+export declare function runFrameworkCommand(name: string, argv?: readonly string[], options?: RunFrameworkCommandOptions): CommandResult;
+/** CLI entry (mirrors ``scripts/framework_commands.main``). */
+export declare function main(argv: readonly string[]): number;
+//# sourceMappingURL=framework-commands.d.ts.map