@deftai/directive-core 0.55.0

package/dist/scm/main.js

@@ -0,0 +1,65 @@
+import { spawnSync } from "node:child_process";
+import { extractFlag } from "./argv.js";
+import { buildCommand } from "./build-command.js";
+import { REST_OPT_IN_VERBS } from "./constants.js";
+import { ScmStubError } from "./errors.js";
+import { runRestList, runRestView } from "./rest-dispatch.js";
+/**
+ * CLI entry point. Returns the underlying binary's exit code (or 2 on arg error).
+ * Mirrors `scripts/scm.py::main`.
+ */
+export function main(argv, options = {}) {
+    if (argv.length < 2) {
+        process.stderr.write("usage: scm.py <namespace> <verb> [pass-through args...]\n" +
+            "       (v1 stub: namespace=issue, verb=list|view|close|edit)\n" +
+            "       --rest opt-in is supported on issue view/list (#976)\n");
+        return 2;
+    }
+    const namespace = argv[0] ?? "";
+    const verb = argv[1] ?? "";
+    let extra = argv.slice(2);
+    const [restMode, afterRest] = extractFlag(extra, "--rest");
+    extra = afterRest;
+    if (restMode) {
+        if (namespace !== "issue" ||
+            !REST_OPT_IN_VERBS.includes(verb)) {
+            process.stderr.write("error: --rest is only supported on 'issue {view|list}'; " +
+                `got 'scm.py ${namespace} ${verb}'. Mutations (close, edit) ` +
+                "still forward to gh in the v1 stub; #881 owns the full " +
+                "REST migration.\n");
+            return 2;
+        }
+        const seams = {
+            whichFn: options.whichFn,
+            runGhApiFn: options.runGhApiFn,
+        };
+        const result = verb === "view" ? runRestView(extra, seams) : runRestList(extra, seams);
+        if (result.stdout.length > 0) {
+            process.stdout.write(result.stdout);
+        }
+        if (result.stderr.length > 0) {
+            process.stderr.write(result.stderr);
+        }
+        return result.exitCode;
+    }
+    try {
+        const cmd = buildCommand(namespace, verb, extra, { whichFn: options.whichFn });
+        const binary = cmd[0];
+        if (binary === undefined) {
+            throw new ScmStubError("internal error: empty command argv");
+        }
+        const proc = spawnSync(binary, cmd.slice(1), {
+            stdio: "inherit",
+            env: process.env,
+        });
+        return proc.status ?? 1;
+    }
+    catch (err) {
+        if (err instanceof ScmStubError) {
+            process.stderr.write(`error: ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=main.js.map

package/dist/scm/py-format.d.ts

@@ -0,0 +1,9 @@
+/** Format values like Python `repr()` for golden parity with the oracle. */
+export declare function pyRepr(value: unknown): string;
+/** Format a tuple like Python `('a', 'b')` including trailing comma for length 1. */
+export declare function pyTuple(items: readonly unknown[]): string;
+/** JSON.dumps(..., ensure_ascii=False) default separators: ', ' and ': '.
+ * Only structural separators are expanded -- colons/commas inside string
+ * literals are preserved so values like "fix: bug" or "foo, bar" survive. */
+export declare function pythonJsonStringify(value: unknown): string;
+//# sourceMappingURL=py-format.d.ts.map

package/dist/scm/py-format.js

@@ -0,0 +1,31 @@
+import { expandPythonJsonSeparators } from "../text/redos-safe.js";
+/** Format values like Python `repr()` for golden parity with the oracle. */
+export function pyRepr(value) {
+    if (value === null) {
+        return "None";
+    }
+    if (typeof value === "string") {
+        return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => pyRepr(item)).join(", ")}]`;
+    }
+    return JSON.stringify(value);
+}
+/** Format a tuple like Python `('a', 'b')` including trailing comma for length 1. */
+export function pyTuple(items) {
+    if (items.length === 1) {
+        return `(${pyRepr(items[0])},)`;
+    }
+    return `(${items.map((item) => pyRepr(item)).join(", ")})`;
+}
+/** JSON.dumps(..., ensure_ascii=False) default separators: ', ' and ': '.
+ * Only structural separators are expanded -- colons/commas inside string
+ * literals are preserved so values like "fix: bug" or "foo, bar" survive. */
+export function pythonJsonStringify(value) {
+    return expandPythonJsonSeparators(JSON.stringify(value, null, 0));
+}
+//# sourceMappingURL=py-format.js.map

package/dist/scm/rest-dispatch.d.ts

@@ -0,0 +1,14 @@
+import { type GhRestSeams } from "./gh-rest.js";
+/** Dispatch `scm issue view --rest <N> --repo X [--json fields]`. */
+export declare function runRestView(extra: readonly string[], seams?: GhRestSeams): {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+/** Dispatch `scm issue list --rest --repo X [...flags]`. */
+export declare function runRestList(extra: readonly string[], seams?: GhRestSeams): {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+//# sourceMappingURL=rest-dispatch.d.ts.map

package/dist/scm/rest-dispatch.js

@@ -0,0 +1,175 @@
+import { extractValueFlag, filterJsonFields } from "./argv.js";
+import { GhRestError, InvalidRepoError, restIssueList, restIssueView, } from "./gh-rest.js";
+import { pyRepr, pythonJsonStringify } from "./py-format.js";
+function parseJsonFields(jsonSpec) {
+    if (jsonSpec === null || jsonSpec.length === 0) {
+        return [];
+    }
+    return jsonSpec.split(",").map((f) => f.trim());
+}
+/** Dispatch `scm issue view --rest <N> --repo X [--json fields]`. */
+export function runRestView(extra, seams = {}) {
+    let remainder = [...extra];
+    const [repo, afterRepo] = extractValueFlag(remainder, "--repo");
+    remainder = afterRepo;
+    const [jsonSpec, afterJson] = extractValueFlag(remainder, "--json");
+    remainder = afterJson;
+    if (repo === null || repo.length === 0) {
+        return {
+            exitCode: 2,
+            stdout: "",
+            stderr: "error: --rest issue view requires --repo OWNER/NAME\n",
+        };
+    }
+    const positionals = remainder.filter((t) => !t.startsWith("-"));
+    const leftoverFlags = remainder.filter((t) => t.startsWith("-"));
+    if (leftoverFlags.length > 0) {
+        return {
+            exitCode: 2,
+            stdout: "",
+            stderr: `error: --rest issue view does not recognise these flags: ` +
+                `${pyRepr(leftoverFlags)}. Supported flags are --repo, --json. ` +
+                "Mutations / additional read filters belong on #881.\n",
+        };
+    }
+    if (positionals.length !== 1) {
+        return {
+            exitCode: 2,
+            stdout: "",
+            stderr: "error: --rest issue view expects exactly one positional issue " +
+                `number; got ${pyRepr(positionals)}\n`,
+        };
+    }
+    const issueStr = positionals[0] ?? "";
+    const issueN = Number.parseInt(issueStr, 10);
+    if (Number.isNaN(issueN) || String(issueN) !== issueStr) {
+        return {
+            exitCode: 2,
+            stdout: "",
+            stderr: `error: issue number must be an integer; got ${pyRepr(issueStr)}\n`,
+        };
+    }
+    try {
+        const response = restIssueView(repo, issueN, seams);
+        const fields = parseJsonFields(jsonSpec);
+        const filtered = filterJsonFields(response, fields);
+        return {
+            exitCode: 0,
+            stdout: `${pythonJsonStringify(filtered)}\n`,
+            stderr: "",
+        };
+    }
+    catch (err) {
+        if (err instanceof InvalidRepoError) {
+            return {
+                exitCode: 2,
+                stdout: "",
+                stderr: `error: invalid --repo value: ${err.message}\n`,
+            };
+        }
+        if (err instanceof GhRestError) {
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: `error: ${err.message}\n`,
+            };
+        }
+        throw err;
+    }
+}
+/** Dispatch `scm issue list --rest --repo X [...flags]`. */
+export function runRestList(extra, seams = {}) {
+    let remainder = [...extra];
+    const [repo, afterRepo] = extractValueFlag(remainder, "--repo");
+    remainder = afterRepo;
+    const [state, afterState] = extractValueFlag(remainder, "--state", "open");
+    remainder = afterState;
+    const [jsonSpec, afterJson] = extractValueFlag(remainder, "--json");
+    remainder = afterJson;
+    const [author, afterAuthor] = extractValueFlag(remainder, "--author");
+    remainder = afterAuthor;
+    const labelValues = [];
+    while (true) {
+        const [labelPart, afterLabel] = extractValueFlag(remainder, "--label");
+        if (labelPart === null) {
+            break;
+        }
+        labelValues.push(labelPart);
+        remainder = afterLabel;
+    }
+    const [limitStr, afterLimit] = extractValueFlag(remainder, "--limit", "30");
+    remainder = afterLimit;
+    const leftoverFlags = remainder.filter((t) => t.startsWith("-"));
+    if (leftoverFlags.length > 0) {
+        return {
+            exitCode: 2,
+            stdout: "",
+            stderr: `error: --rest issue list does not recognise these flags: ` +
+                `${pyRepr(leftoverFlags)}. Supported flags are --repo, --state, ` +
+                "--label, --author, --limit, --json. Additional filters " +
+                "belong on #881.\n",
+        };
+    }
+    const leftoverPositionals = remainder.filter((t) => !t.startsWith("-"));
+    if (leftoverPositionals.length > 0) {
+        return {
+            exitCode: 2,
+            stdout: "",
+            stderr: `error: --rest issue list takes no positional arguments; ` +
+                `got ${pyRepr(leftoverPositionals)}. Did you mean ` +
+                `\`scm.py issue view --rest ${leftoverPositionals[0]} --repo OWNER/NAME\`?\n`,
+        };
+    }
+    if (repo === null || repo.length === 0) {
+        return {
+            exitCode: 2,
+            stdout: "",
+            stderr: "error: --rest issue list requires --repo OWNER/NAME\n",
+        };
+    }
+    const perPage = limitStr !== null ? Number.parseInt(limitStr, 10) : 30;
+    if (Number.isNaN(perPage)) {
+        return {
+            exitCode: 2,
+            stdout: "",
+            stderr: `error: --limit must be an integer; got ${pyRepr(limitStr)}\n`,
+        };
+    }
+    const labels = labelValues.flatMap((value) => value
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0));
+    try {
+        const response = restIssueList(repo, {
+            state: state ?? "open",
+            labels,
+            author,
+            perPage,
+        }, seams);
+        const fields = parseJsonFields(jsonSpec);
+        const filtered = filterJsonFields(response, fields);
+        return {
+            exitCode: 0,
+            stdout: `${pythonJsonStringify(filtered)}\n`,
+            stderr: "",
+        };
+    }
+    catch (err) {
+        if (err instanceof InvalidRepoError) {
+            return {
+                exitCode: 2,
+                stdout: "",
+                stderr: `error: invalid --repo value: ${err.message}\n`,
+            };
+        }
+        if (err instanceof GhRestError) {
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: `error: ${err.message}\n`,
+            };
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=rest-dispatch.js.map

package/dist/scope/audit-log.d.ts

@@ -0,0 +1,14 @@
+import { utcNowIso } from "./vbrief-json.js";
+export declare class ScopeAuditLogError extends Error {
+    constructor(message: string);
+}
+export declare function newDecisionId(): string;
+export declare function canonicalLogPath(projectRoot: string): string;
+/** Validate and append an audit entry; returns decision_id. */
+export declare function append(entry: Record<string, unknown>, logPath: string): string;
+/** Read all well-formed audit entries in insertion order. */
+export declare function readAll(logPath: string): Record<string, unknown>[];
+export declare function findByPath(vbriefPath: string, logPath: string): Record<string, unknown>[];
+export declare function latestForPath(vbriefPath: string, action: string | null, logPath: string): Record<string, unknown> | null;
+export { utcNowIso as auditUtcNowIso };
+//# sourceMappingURL=audit-log.d.ts.map

package/dist/scope/audit-log.js

@@ -0,0 +1,186 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { AUDIT_LOG_REL_PATH } from "./constants.js";
+import { utcNowIso } from "./vbrief-json.js";
+export class ScopeAuditLogError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ScopeAuditLogError";
+    }
+}
+const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+const ISO8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+const REQUIRED_FIELDS = [
+    "decision_id",
+    "timestamp",
+    "action",
+    "vbrief_path",
+    "from_status",
+    "to_status",
+    "actor",
+];
+const DEMOTE_META_REQUIRED = [
+    "was_promoted",
+    "original_promotion_decision_id",
+    "days_in_pending",
+    "demote_reason",
+    "demoted_from",
+];
+let threadLock = false;
+function replacerSortKeys(_key, value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const sorted = {};
+        for (const k of Object.keys(value).sort()) {
+            sorted[k] = value[k];
+        }
+        return sorted;
+    }
+    return value;
+}
+function validateDemoteMeta(meta) {
+    const missing = DEMOTE_META_REQUIRED.filter((f) => !(f in meta));
+    if (missing.length > 0) {
+        throw new ScopeAuditLogError(`demote_meta missing required field(s): ${missing}`);
+    }
+    if (typeof meta.was_promoted !== "boolean") {
+        throw new ScopeAuditLogError(`demote_meta.was_promoted must be bool, got ${JSON.stringify(meta.was_promoted)}`);
+    }
+    const opdid = meta.original_promotion_decision_id;
+    if (opdid !== null && (typeof opdid !== "string" || !UUID_RE.test(opdid))) {
+        throw new ScopeAuditLogError(`demote_meta.original_promotion_decision_id must be a UUID string or null, got ${JSON.stringify(opdid)}`);
+    }
+    const days = meta.days_in_pending;
+    if (typeof days !== "number" || !Number.isInteger(days) || days < 0) {
+        throw new ScopeAuditLogError(`demote_meta.days_in_pending must be a non-negative int, got ${JSON.stringify(days)}`);
+    }
+    if (typeof meta.demote_reason !== "string" || meta.demote_reason.length === 0) {
+        throw new ScopeAuditLogError(`demote_meta.demote_reason must be a non-empty string, got ${JSON.stringify(meta.demote_reason)}`);
+    }
+    if (typeof meta.demoted_from !== "string" || meta.demoted_from.length === 0) {
+        throw new ScopeAuditLogError(`demote_meta.demoted_from must be a non-empty string, got ${JSON.stringify(meta.demoted_from)}`);
+    }
+}
+function validateEntry(entry) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        throw new ScopeAuditLogError(`entry must be a dict, got ${entry === null ? "None" : typeof entry}`);
+    }
+    const e = entry;
+    const missing = REQUIRED_FIELDS.filter((f) => !(f in e));
+    if (missing.length > 0) {
+        throw new ScopeAuditLogError(`entry missing required field(s): ${missing}`);
+    }
+    if (typeof e.decision_id !== "string" || !UUID_RE.test(e.decision_id)) {
+        throw new ScopeAuditLogError(`decision_id must be a UUID string, got ${JSON.stringify(e.decision_id)}`);
+    }
+    if (typeof e.timestamp !== "string" || !ISO8601_RE.test(e.timestamp)) {
+        throw new ScopeAuditLogError(`timestamp must be ISO-8601 UTC with Z suffix, got ${JSON.stringify(e.timestamp)}`);
+    }
+    for (const field of ["action", "vbrief_path", "from_status", "to_status", "actor"]) {
+        const value = e[field];
+        if (typeof value !== "string" || value.length === 0) {
+            throw new ScopeAuditLogError(`${field} must be a non-empty string, got ${JSON.stringify(value)}`);
+        }
+    }
+    if (e.action === "demote") {
+        const meta = e.demote_meta;
+        if (typeof meta !== "object" || meta === null || Array.isArray(meta)) {
+            throw new ScopeAuditLogError(`action='demote' requires a 'demote_meta' object, got ${JSON.stringify(meta)}`);
+        }
+        validateDemoteMeta(meta);
+    }
+}
+export function newDecisionId() {
+    return randomUUID();
+}
+export function canonicalLogPath(projectRoot) {
+    return join(resolve(projectRoot), AUDIT_LOG_REL_PATH);
+}
+function withAppendLock(logPath, fn) {
+    const lockPath = `${logPath}.lock`;
+    mkdirSync(dirname(logPath), { recursive: true });
+    while (threadLock) {
+        /* spin-wait for in-process serialization */
+    }
+    threadLock = true;
+    let fd = null;
+    try {
+        fd = openSync(lockPath, "a+");
+        if (readFileSync(lockPath).length === 0) {
+            writeSync(fd, "\0");
+        }
+        fn();
+    }
+    finally {
+        threadLock = false;
+        if (fd !== null) {
+            closeSync(fd);
+        }
+        try {
+            if (existsSync(lockPath)) {
+                unlinkSync(lockPath);
+            }
+        }
+        catch {
+            /* best-effort lock cleanup */
+        }
+    }
+}
+/** Validate and append an audit entry; returns decision_id. */
+export function append(entry, logPath) {
+    if (logPath.length === 0) {
+        throw new ScopeAuditLogError("append() requires log_path; pass canonicalLogPath(projectRoot)");
+    }
+    validateEntry(entry);
+    const logFile = resolve(logPath);
+    mkdirSync(join(logFile, ".."), { recursive: true });
+    const line = JSON.stringify(entry, replacerSortKeys);
+    withAppendLock(logFile, () => {
+        writeFileSync(logFile, `${line}\n`, { encoding: "utf8", flag: "a" });
+    });
+    return String(entry.decision_id);
+}
+/** Read all well-formed audit entries in insertion order. */
+export function readAll(logPath) {
+    if (logPath.length === 0) {
+        throw new ScopeAuditLogError("readAll() requires log_path; pass canonicalLogPath(projectRoot)");
+    }
+    const logFile = resolve(logPath);
+    if (!existsSync(logFile)) {
+        return [];
+    }
+    const out = [];
+    const raw = readFileSync(logFile, "utf8");
+    for (const line of raw.split("\n")) {
+        const stripped = line.trim();
+        if (stripped.length === 0) {
+            continue;
+        }
+        try {
+            const obj = JSON.parse(stripped);
+            if (typeof obj === "object" && obj !== null && !Array.isArray(obj)) {
+                out.push(obj);
+            }
+        }
+        catch {
+            /* skip malformed lines */
+        }
+    }
+    return out;
+}
+export function findByPath(vbriefPath, logPath) {
+    return readAll(logPath).filter((e) => e.vbrief_path === vbriefPath);
+}
+export function latestForPath(vbriefPath, action, logPath) {
+    let rows = findByPath(vbriefPath, logPath);
+    if (action !== null) {
+        rows = rows.filter((r) => r.action === action);
+    }
+    if (rows.length === 0) {
+        return null;
+    }
+    rows.sort((a, b) => String(a.timestamp ?? "").localeCompare(String(b.timestamp ?? "")));
+    return rows[rows.length - 1] ?? null;
+}
+export { utcNowIso as auditUtcNowIso };
+//# sourceMappingURL=audit-log.js.map

package/dist/scope/capacity-stamp.d.ts

@@ -0,0 +1,3 @@
+/** Stamp completedAt + capacityBucket onto a completing vBRIEF (#1419). */
+export declare function stampCompletionMetadata(plan: Record<string, unknown>, projectRoot: string, timestamp: string): void;
+//# sourceMappingURL=capacity-stamp.d.ts.map

package/dist/scope/capacity-stamp.js

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { PROJECT_DEFINITION_REL_PATH } from "../policy/resolve.js";
+function resolveDefaultCapacityBucket(projectRoot) {
+    try {
+        const path = join(resolve(projectRoot), PROJECT_DEFINITION_REL_PATH);
+        const raw = readFileSync(path, "utf8");
+        const data = JSON.parse(raw);
+        const plan = data.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            return "";
+        }
+        const policy = plan.policy;
+        if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+            return "";
+        }
+        const allocation = policy.capacityAllocation;
+        if (typeof allocation !== "object" || allocation === null || Array.isArray(allocation)) {
+            return "";
+        }
+        const defaultBucket = allocation.defaultBucket;
+        return typeof defaultBucket === "string" ? defaultBucket : "";
+    }
+    catch {
+        return "";
+    }
+}
+/** Stamp completedAt + capacityBucket onto a completing vBRIEF (#1419). */
+export function stampCompletionMetadata(plan, projectRoot, timestamp) {
+    let metadata = plan.metadata;
+    if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+        metadata = {};
+        plan.metadata = metadata;
+    }
+    const meta = metadata;
+    meta.completedAt = timestamp;
+    const existing = meta.capacityBucket;
+    if (!(typeof existing === "string" && existing.trim().length > 0)) {
+        const bucket = resolveDefaultCapacityBucket(projectRoot);
+        if (bucket.length > 0) {
+            meta.capacityBucket = bucket;
+        }
+    }
+}
+//# sourceMappingURL=capacity-stamp.js.map

package/dist/scope/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+/** Direct entry for tests and `node packages/core/dist/scope/cli.js`. */
+export declare function mainEntry(argv?: string[]): number;
+//# sourceMappingURL=cli.d.ts.map

package/dist/scope/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { lifecycleMain } from "./main.js";
+/** Direct entry for tests and `node packages/core/dist/scope/cli.js`. */
+export function mainEntry(argv = process.argv.slice(2)) {
+    return lifecycleMain(argv);
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(mainEntry());
+}
+//# sourceMappingURL=cli.js.map

package/dist/scope/constants.d.ts

@@ -0,0 +1,19 @@
+/** vBRIEF lifecycle folder names. */
+export declare const LIFECYCLE_FOLDERS: readonly ["proposed", "pending", "active", "completed", "cancelled"];
+export type LifecycleFolder = (typeof LIFECYCLE_FOLDERS)[number];
+export type ScopeAction = "promote" | "activate" | "complete" | "fail" | "cancel" | "restore" | "block" | "unblock";
+export interface TransitionSpec {
+    readonly allowedSources: readonly LifecycleFolder[];
+    readonly targetFolder: LifecycleFolder | null;
+    readonly targetStatus: string;
+}
+/** action -> (allowed_source_folders, target_folder, target_status) */
+export declare const TRANSITIONS: Record<ScopeAction, TransitionSpec>;
+/** Status preconditions for in-place actions. */
+export declare const STATUS_PRECONDITIONS: Partial<Record<ScopeAction, string>>;
+export declare const MOVE_LABELS: Partial<Record<ScopeAction, string>>;
+export declare const STAY_LABELS: Partial<Record<ScopeAction, string>>;
+export declare const REVERSIBLE_ACTIONS: Set<string>;
+export declare const TERMINAL_ACTIONS: Set<string>;
+export declare const AUDIT_LOG_REL_PATH = "vbrief/.eval/scope-lifecycle.jsonl";
+//# sourceMappingURL=constants.d.ts.map

package/dist/scope/constants.js

@@ -0,0 +1,44 @@
+/** vBRIEF lifecycle folder names. */
+export const LIFECYCLE_FOLDERS = [
+    "proposed",
+    "pending",
+    "active",
+    "completed",
+    "cancelled",
+];
+/** action -> (allowed_source_folders, target_folder, target_status) */
+export const TRANSITIONS = {
+    promote: { allowedSources: ["proposed"], targetFolder: "pending", targetStatus: "pending" },
+    activate: { allowedSources: ["pending"], targetFolder: "active", targetStatus: "running" },
+    complete: { allowedSources: ["active"], targetFolder: "completed", targetStatus: "completed" },
+    fail: { allowedSources: ["active"], targetFolder: "completed", targetStatus: "failed" },
+    cancel: {
+        allowedSources: LIFECYCLE_FOLDERS,
+        targetFolder: "cancelled",
+        targetStatus: "cancelled",
+    },
+    restore: { allowedSources: ["cancelled"], targetFolder: "proposed", targetStatus: "proposed" },
+    block: { allowedSources: ["active"], targetFolder: null, targetStatus: "blocked" },
+    unblock: { allowedSources: ["active"], targetFolder: null, targetStatus: "running" },
+};
+/** Status preconditions for in-place actions. */
+export const STATUS_PRECONDITIONS = {
+    block: "running",
+    unblock: "blocked",
+};
+export const MOVE_LABELS = {
+    promote: "Promoted",
+    activate: "Activated",
+    complete: "Completed",
+    fail: "Failed",
+    cancel: "Cancelled",
+    restore: "Restored",
+};
+export const STAY_LABELS = {
+    block: "Blocked",
+    unblock: "Unblocked",
+};
+export const REVERSIBLE_ACTIONS = new Set(["demote", "cancel", "restore", "undo"]);
+export const TERMINAL_ACTIONS = new Set(["complete", "fail"]);
+export const AUDIT_LOG_REL_PATH = "vbrief/.eval/scope-lifecycle.jsonl";
+//# sourceMappingURL=constants.js.map

package/dist/scope/decompose.d.ts

@@ -0,0 +1,42 @@
+/**
+ * scope/decompose.ts -- Apply or validate an approved epic/phase -> story decomposition draft.
+ *
+ * Faithful TypeScript port of scripts/scope_decompose.py + scripts/_vbrief_story_quality.py.
+ * The command is deterministic: it never invents stories from a parent scope.
+ * A caller supplies a draft with child story definitions; this module validates
+ * that draft, writes the child story vBRIEFs, and updates the parent scope references.
+ */
+export declare class DecompositionError extends Error {
+    constructor(message: string);
+}
+type JsonObj = Record<string, unknown>;
+export declare function asStrList(value: unknown): string[];
+export declare function acceptanceTextsFromItems(items: unknown): string[];
+export declare function itemHasAcceptance(item: JsonObj): boolean;
+export declare function itemsHaveAcceptance(items: unknown): boolean;
+export declare function itemHasTraces(item: JsonObj): boolean;
+export declare function missingRequiredSwarmFields(swarm: JsonObj): string[];
+export declare function deprecatedSubitemsIssues(items: unknown, prefix?: string): string[];
+export declare function storyQualityIssues(opts: {
+    title: string;
+    description: string;
+    implementationPlan: string;
+    userStory: string;
+    acceptanceTexts: string[];
+    acceptanceCountJustification: string;
+    swarm: JsonObj;
+    concurrentReady?: boolean;
+}): string[];
+export declare function validateDraft(stories: JsonObj[]): string[];
+export interface ApplyDecompositionOptions {
+    projectRoot: string;
+    parentPath: string;
+    draftPath: string;
+    checkOnly: boolean;
+    date: string;
+}
+export declare function applyDecomposition(opts: ApplyDecompositionOptions): string[];
+/** CLI entry for scope-decompose (mirrors scope_decompose.py main()). */
+export declare function decomposeMain(argv: string[]): number;
+export {};
+//# sourceMappingURL=decompose.d.ts.map