@deftai/directive-core 0.95.0 → 0.96.0

package/dist/cache/main.js

@@ -1,5 +1,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { latestDecisions, readAuditLog } from "../triage/actions/candidates-log.js";
+import { resolveCandidatesLogPath } from "../triage/cache-path.js";
+import { archiveClosedEntries, DEFAULT_ARCHIVE_OLDER_THAN_DAYS, listArchivedEntries, restoreFromArchive, } from "./archive.js";
 import { ALLOWED_SOURCES, DEFAULT_BATCH_SIZE, DEFAULT_DELAY_MS, DEFAULT_PRUNE_OLDER_THAN_DAYS, } from "./constants.js";
 import { CacheCapBreachedError, CacheError, CacheFetchError, CacheNotFoundError, CacheValidationError, } from "./errors.js";
 import { cacheFetchAll, cacheRefreshClosed } from "./fetch.js";
@@ -8,7 +11,7 @@ import { cacheGet, cacheInvalidate, cachePrune, cachePruneToCap, cachePut } from
 import { resolveCaps } from "./quota.js";
 import { clearTaskCache } from "./task-cache/store.js";
 function usage() {
-    process.stderr.write("usage: cache [-h] {put,get,invalidate,fetch-all,prune,clear} ...\n");
+    process.stderr.write("usage: cache [-h] {put,get,invalidate,fetch-all,prune,clear,archive-closed,archive-list,restore-from-archive} ...\n");
 }
 function normaliseLabelFilter(raw) {
     if (!raw || raw.length === 0)
@@ -309,6 +312,293 @@ function cmdPrune(args) {
     process.stdout.write(`${pythonJsonPretty(payload)}\n`);
     return 0;
 }
+/**
+ * Reversible closed-entry archive (#1137). Operator-only; not TTL prune.
+ * Distinct from `cache prune` (hard-delete by expires_at).
+ */
+function cmdArchiveClosed(args) {
+    let olderThanDays = DEFAULT_ARCHIVE_OLDER_THAN_DAYS;
+    let source = "github-issue";
+    let repo;
+    let dryRun = false;
+    let json = false;
+    let terminalDecisionOnly = false;
+    let projectRoot;
+    let cacheRoot;
+    let reason;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--older-than-days") {
+            olderThanDays = Number.parseInt(args[i + 1] ?? "", 10);
+            i += 1;
+        }
+        else if (arg === "--source") {
+            source = args[i + 1] ?? "github-issue";
+            i += 1;
+        }
+        else if (arg === "--repo") {
+            repo = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--dry-run") {
+            dryRun = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--terminal-decision-only") {
+            terminalDecisionOnly = true;
+        }
+        else if (arg === "--project-root") {
+            projectRoot = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--cache-root") {
+            cacheRoot = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--reason") {
+            reason = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            process.stdout.write("usage: cache archive-closed [--dry-run] [--older-than-days 30] [--repo OWNER/NAME]\n" +
+                "       [--source github-issue] [--json] [--terminal-decision-only]\n" +
+                "       [--project-root PATH] [--cache-root PATH] [--reason TEXT]\n" +
+                "\n" +
+                "Reversible archive of closed github-issue cache entries (not TTL cache:prune).\n" +
+                "Skips issues still referenced by xbrief/{proposed,pending,active}.\n" +
+                "Also available as: task triage:cache-archive\n");
+            return 0;
+        }
+        else {
+            throw new CacheError(`unexpected argument: ${arg}`);
+        }
+    }
+    const resolvedProjectRoot = projectRoot ?? process.cwd();
+    const resolvedCacheRoot = cacheRoot ?? (projectRoot !== undefined ? resolve(projectRoot, ".deft-cache") : undefined);
+    let latestDecisionMap = null;
+    if (terminalDecisionOnly) {
+        try {
+            const logPath = resolveCandidatesLogPath(resolvedProjectRoot);
+            latestDecisionMap = latestDecisions(readAuditLog(logPath, repo ?? null));
+        }
+        catch {
+            latestDecisionMap = new Map();
+        }
+    }
+    const result = archiveClosedEntries({
+        olderThanDays,
+        source,
+        repo: repo ?? null,
+        dryRun,
+        terminalDecisionOnly,
+        latestDecisions: latestDecisionMap,
+        projectRoot: resolvedProjectRoot,
+        cacheRoot: resolvedCacheRoot,
+        reason,
+    });
+    const payload = {
+        mode: "archive-closed",
+        note: "Reversible closed-entry archive; distinct from cache:prune (TTL hard-delete).",
+        dry_run: result.dryRun,
+        older_than_days: result.olderThanDays,
+        source: result.source,
+        repo: result.repo,
+        terminal_decision_only: terminalDecisionOnly,
+        archived_count: result.archivedCount,
+        skipped_count: result.skippedCount,
+        archived: result.archived.map((c) => ({
+            key: c.key,
+            live_dir: c.liveDir,
+            archive_dir: c.archiveDir,
+            age_basis: c.ageBasis,
+            closed_at: c.closedAt,
+            pre_archive_decision: c.preArchiveDecision,
+        })),
+        skipped: result.skipped.map((s) => ({
+            key: s.key,
+            reason: s.reason,
+            detail: s.detail ?? null,
+        })),
+    };
+    if (json) {
+        process.stdout.write(`${pythonJsonPretty(payload)}\n`);
+    }
+    else {
+        process.stdout.write(`cache:archive-closed dry_run=${pythonBool(result.dryRun)} archived=${result.archivedCount} skipped=${result.skippedCount} older_than_days=${result.olderThanDays}\n`);
+        for (const c of result.archived) {
+            process.stdout.write(`  archived ${c.key} -> ${c.archiveDir}\n`);
+        }
+        for (const s of result.skipped) {
+            process.stdout.write(`  skipped ${s.key} (${s.reason}${s.detail ? `: ${s.detail}` : ""})\n`);
+        }
+    }
+    return 0;
+}
+function cmdArchiveList(args) {
+    let source = "github-issue";
+    let repo;
+    let since;
+    let limit;
+    let format = "text";
+    let cacheRoot;
+    let projectRoot;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--source") {
+            source = args[i + 1] ?? "github-issue";
+            i += 1;
+        }
+        else if (arg === "--repo") {
+            repo = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--since") {
+            since = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--limit") {
+            limit = Number.parseInt(args[i + 1] ?? "", 10);
+            i += 1;
+        }
+        else if (arg === "--format") {
+            format = args[i + 1] ?? "text";
+            i += 1;
+        }
+        else if (arg === "--format=json" || arg === "--json") {
+            format = "json";
+        }
+        else if (arg?.startsWith("--format=")) {
+            format = arg.slice("--format=".length);
+        }
+        else if (arg === "--cache-root") {
+            cacheRoot = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--project-root") {
+            projectRoot = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            process.stdout.write("usage: cache archive-list [--repo OWNER/NAME] [--since ISO] [--limit N]\n" +
+                "       [--format=json|text] [--source github-issue] [--cache-root PATH]\n" +
+                "Also available as: task triage:archive-list\n");
+            return 0;
+        }
+        else {
+            throw new CacheError(`unexpected argument: ${arg}`);
+        }
+    }
+    const resolvedCacheRoot = cacheRoot ?? (projectRoot !== undefined ? resolve(projectRoot, ".deft-cache") : undefined);
+    const result = listArchivedEntries({
+        source,
+        repo: repo ?? null,
+        since: since ?? null,
+        limit: limit ?? null,
+        cacheRoot: resolvedCacheRoot,
+    });
+    if (format === "json") {
+        process.stdout.write(`${pythonJsonPretty({
+            source: result.source,
+            repo: result.repo,
+            count: result.count,
+            entries: result.entries.map((e) => ({
+                key: e.key,
+                archived_at: e.archivedAt,
+                archive_dir: e.archiveDir,
+                meta: e.meta,
+            })),
+        })}\n`);
+    }
+    else {
+        process.stdout.write(`cache:archive-list count=${result.count}\n`);
+        for (const e of result.entries) {
+            process.stdout.write(`  ${e.key} archived_at=${e.archivedAt}\n`);
+        }
+    }
+    return 0;
+}
+function cmdRestoreFromArchive(args) {
+    let source = "github-issue";
+    let key;
+    let issue;
+    let repo;
+    let force = false;
+    let cacheRoot;
+    let projectRoot;
+    let json = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--source") {
+            source = args[i + 1] ?? "github-issue";
+            i += 1;
+        }
+        else if (arg === "--key") {
+            key = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--issue") {
+            const rawIssue = args[i + 1] ?? "";
+            if (!/^[1-9]\d*$/.test(rawIssue)) {
+                throw new CacheError(`--issue must be a positive integer (got ${JSON.stringify(rawIssue)})`);
+            }
+            issue = Number.parseInt(rawIssue, 10);
+            i += 1;
+        }
+        else if (arg === "--repo") {
+            repo = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--force") {
+            force = true;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg === "--cache-root") {
+            cacheRoot = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "--project-root") {
+            projectRoot = args[i + 1];
+            i += 1;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            process.stdout.write("usage: cache restore-from-archive -- --issue N --repo OWNER/NAME [--force]\n" +
+                "       [--key owner/repo/N] [--source github-issue] [--json]\n" +
+                "Also available as: task triage:restore-from-archive\n");
+            return 0;
+        }
+        else if (!key && arg && !arg.startsWith("-") && arg.includes("/")) {
+            key = arg;
+        }
+        else {
+            throw new CacheError(`unexpected argument: ${arg}`);
+        }
+    }
+    const resolvedCacheRoot = cacheRoot ?? (projectRoot !== undefined ? resolve(projectRoot, ".deft-cache") : undefined);
+    const result = restoreFromArchive({
+        source,
+        key,
+        issue,
+        repo: repo ?? null,
+        force,
+        cacheRoot: resolvedCacheRoot,
+    });
+    if (json) {
+        process.stdout.write(`${pythonJsonPretty(result)}\n`);
+    }
+    else {
+        process.stdout.write(`cache:restore-from-archive status=${result.status} key=${result.key} live=${result.liveDir}\n`);
+        if (result.detail) {
+            process.stdout.write(`  detail: ${result.detail}\n`);
+        }
+    }
+    if (result.status === "missing" || result.status === "conflict")
+        return 1;
+    return 0;
+}
 /** CLI entry point (mirrors `scripts/cache.py::main`). */
 export function main(argv) {
     if (argv.length === 0) {
@@ -332,6 +622,13 @@ export function main(argv) {
                 return cmdPrune(rest);
             case "clear":
                 return cmdClear(rest);
+            case "archive-closed":
+            case "cache-archive":
+                return cmdArchiveClosed(rest);
+            case "archive-list":
+                return cmdArchiveList(rest);
+            case "restore-from-archive":
+                return cmdRestoreFromArchive(rest);
             default:
                 usage();
                 process.stderr.write(`cache: error: argument cmd: invalid choice: '${cmd}'\n`);

package/dist/content-contracts/skills/helpers.d.ts

@@ -21,7 +21,7 @@ export declare function readSkill(relPath: string): string;
  */
 export declare const SWARM_SKILL_REL = "skills/deft-directive-swarm/SKILL.md";
 /** Stable load order: core phases, then host launch adapters, then ops. */
-export declare const SWARM_REFERENCE_ORDER: readonly ["core-phase-0.md", "core-phase-1-2.md", "core-phase-3.md", "host-warp.md", "host-generic.md", "host-grok-build.md", "host-cursor.md", "host-openclaw.md", "core-phase-4.md", "core-phase-5-6.md", "core-ops.md"];
+export declare const SWARM_REFERENCE_ORDER: readonly ["core-phase-0.md", "core-phase-1-2.md", "core-phase-3.md", "host-warp.md", "host-generic.md", "host-grok-build.md", "host-cursor.md", "host-claude-code.md", "host-openclaw.md", "core-phase-4.md", "core-phase-5-6.md", "core-ops.md"];
 export declare function readSwarmSkillSurface(): string;
 export declare function readAgentsMd(): string;
 /** Slice the first `## Returning Sessions` section body out of AGENTS.md. */

package/dist/content-contracts/skills/helpers.js

@@ -48,6 +48,7 @@ export const SWARM_REFERENCE_ORDER = [
     "host-generic.md",
     "host-grok-build.md",
     "host-cursor.md",
+    "host-claude-code.md",
     "host-openclaw.md",
     "core-phase-4.md",
     "core-phase-5-6.md",

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export * as lifecycle from "./lifecycle/index.js";
 export * as metrics from "./metrics/index.js";
 export * as orchestration from "./orchestration/index.js";
 export * as packs from "./packs/index.js";
+export * as parentTurnShape from "./parent-turn-shape/index.js";
 export * as platform from "./platform/index.js";
 export * as policy from "./policy/index.js";
 export * as prClosingKeywords from "./pr-closing-keywords/index.js";

package/dist/index.js

@@ -36,6 +36,7 @@ export * as lifecycle from "./lifecycle/index.js";
 export * as metrics from "./metrics/index.js";
 export * as orchestration from "./orchestration/index.js";
 export * as packs from "./packs/index.js";
+export * as parentTurnShape from "./parent-turn-shape/index.js";
 export * as platform from "./platform/index.js";
 export * as policy from "./policy/index.js";
 export * as prClosingKeywords from "./pr-closing-keywords/index.js";

package/dist/init-deposit/hygiene.d.ts

@@ -8,7 +8,7 @@
  * and scope briefs are never installer-managed; if they reappear in
  * `installerManagedMatchers()`, unit tests and deposit-time assert fail closed.
  *
- * Refs #1576, #1453, #1430, #3029, #3030.
+ * Refs #1576, #1453, #1430, #3029, #3030, #3127, #3117.
  */
 import { type InitDepositIo } from "./constants.js";
 export declare const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";

package/dist/init-deposit/hygiene.js

@@ -8,7 +8,7 @@
  * and scope briefs are never installer-managed; if they reappear in
  * `installerManagedMatchers()`, unit tests and deposit-time assert fail closed.
  *
- * Refs #1576, #1453, #1430, #3029, #3030.
+ * Refs #1576, #1453, #1430, #3029, #3030, #3127, #3117.
  */
 import { execFileSync } from "node:child_process";
 import { existsSync, readdirSync, rmSync } from "node:fs";
@@ -82,6 +82,16 @@ export function installerManagedMatchers() {
         { exact: CODEQL_CONFIG_REL },
         { exact: CORE_GUARD_WORKFLOW_REL },
         { exact: "Taskfile.yml" },
+        // Upgrade co-travel unit (#3127): npm pin + lock follow-through and the
+        // freshness live stamp (#3117) are part of a normal framework upgrade, not
+        // product feature work. Path-level allow for v1 (stricter “only
+        // @deftai/directive version changed” is a follow-on if needed).
+        // Mixing .deft/core/** with true app/product paths still fails (#1430).
+        { exact: "package.json" },
+        { exact: "package-lock.json" },
+        { exact: "pnpm-lock.yaml" },
+        { exact: "yarn.lock" },
+        { exact: ".deft/GENERATION.json" },
         // Legacy vbrief/ tree -- retained for not-yet-migrated consumers.
         { exact: "vbrief/.deft-version" },
         { exact: "vbrief/vbrief.md" },
@@ -476,9 +486,11 @@ export function printCommitGuidance(io, paths, staged) {
     if (paths.length === 0)
         return;
     const addCmd = `git add ${paths.join(" ")}`;
-    io.printf("\nCommit hygiene (#1453, #1671): keep the framework deposit in its OWN branch/PR.\n");
-    io.printf("Do NOT use `git add -A` -- mixing the payload with your own files trips the\n");
+    io.printf("\nCommit hygiene (#1453, #1671, #3127): keep the framework upgrade in its OWN branch/PR.\n");
+    io.printf("Do NOT use `git add -A` -- mixing the payload with product/app files trips the\n");
     io.printf("deft-core-guard CI check.\n");
+    io.printf("One upgrade PR MAY co-travel: .deft/core/** + installer-managed deposits + package.json\n");
+    io.printf("pin/lock + .deft/GENERATION.json. True app/product paths still require a separate PR.\n");
     if (staged) {
         io.printf("The installer already staged ONLY these framework + installer-managed paths:\n");
         io.printf(`  ${addCmd}\n`);
@@ -488,7 +500,7 @@ export function printCommitGuidance(io, paths, staged) {
         io.printf(`  ${addCmd}\n`);
     }
     io.printf("Then take the framework deposit through the full PR lifecycle so deft-core-guard\n");
-    io.printf("evaluates a clean, standalone PR:\n");
+    io.printf("evaluates a clean, standalone upgrade PR:\n");
     io.printf(`  1. Branch: git switch -c ${COMMIT_HYGIENE_BRANCH_NAME}\n`);
     io.printf('  2. Commit: git commit -m "chore(deft): update framework payload"\n');
     io.printf(`  3. Push:   git push -u origin ${COMMIT_HYGIENE_BRANCH_NAME}\n`);

package/dist/init-deposit/scaffold.js

@@ -507,11 +507,12 @@ function coreGuardWorkflowContent() {
     const baseSha = githubActionsExpr("github.event.pull_request.base.sha");
     const headSha = githubActionsExpr("github.event.pull_request.head.sha");
     return ("name: deft-core-guard\n\n" +
-        "# Deft framework guard (#1430): a single PR should not mix changes to the\n" +
-        "# vendored framework payload (.deft/core/**) with changes to your own project\n" +
-        "# files. Framework updates come from `deft-install` / upgrade and should\n" +
-        "# land in their own PR so reviewers (and bot reviewers) can treat them as\n" +
-        "# packaged, machine-managed assets. Delete this file if you do not want the guard.\n" +
+        "# Deft framework guard (#1430 / #3127): a single PR should not mix changes to the\n" +
+        "# vendored framework payload (.deft/core/**) with true application/product files.\n" +
+        "# One upgrade PR MAY include deposit + installer-managed paths + package.json pin/lock\n" +
+        "# + .deft/GENERATION.json. Framework updates come from `deft update` / install and should\n" +
+        "# land without product feature work so reviewers treat the payload as machine-managed.\n" +
+        "# Delete this file if you do not want the guard.\n" +
         "on:\n" +
         "  pull_request:\n\n" +
         "permissions:\n" +

package/dist/parent-turn-shape/evaluate.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Parent turn-shape hard-stop for text-repetition hang (FC14 / #3131).
+ *
+ * Soft skill prose (#2943) alone is insufficient: parents still burn the full
+ * output budget on identical progress sentences with zero tool_use after leaf
+ * announce. This pure library is the Directive-side machine-checkable gate.
+ *
+ * Hosts (OpenClaw, swarm parents, review monitors) SHOULD evaluate the parent
+ * turn stream mid-generation and hard-stop when `ok` is false.
+ *
+ * Illegal shape (MUST NOT):
+ *   N > maxIdenticalWithoutTool (default 2) near-identical assistant sentences
+ *   (or streaming text chunks) in one turn with no tool_use and no yield.
+ *
+ * Legal post-announce shapes:
+ *   1. Tool batch (ground-truth) then one consolidate
+ *   2. sessions_yield / wait without filler
+ *   3. One short user answer that is NOT a repeated progress line
+ */
+/** Failure class codes for operator / host recovery surfaces. */
+export type ParentTurnFailClass = "none" | "FC14" | "text-repetition-hang" | "progress-only-no-tool";
+/** Ordered events observed within a single parent turn. */
+export type ParentTurnEvent = {
+    kind: "assistant_text";
+    text: string;
+} | {
+    kind: "tool_use";
+    name?: string;
+} | {
+    kind: "yield";
+};
+export interface ParentTurnShapeInput {
+    /** Ordered events from one parent turn (streaming deltas may be separate). */
+    readonly events: readonly ParentTurnEvent[];
+    /**
+     * When true, multi-sentence progress-only text with zero tools/yield is also
+     * illegal even without exact N>2 identity (post-`subagent_announce` policy).
+     */
+    readonly afterSubagentAnnounce?: boolean;
+    /**
+     * Max near-identical consecutive (or within-turn) text units allowed without
+     * tool_use / yield. Issue contract: MUST NOT emit N>2 → default max = 2.
+     */
+    readonly maxIdenticalWithoutTool?: number;
+}
+export interface ParentTurnShapeResult {
+    readonly ok: boolean;
+    /** Primary fail class (`FC14` aliases `text-repetition-hang`). */
+    readonly failClass: ParentTurnFailClass;
+    readonly reasons: readonly string[];
+    /** Highest count of near-identical text units observed without tool/yield. */
+    readonly maxIdenticalCount: number;
+    readonly hasToolUse: boolean;
+    readonly hasYield: boolean;
+}
+/** Canonical fail class for the hang (#3131 / soft FC14 recurrence of #2943). */
+export declare const PARENT_TURN_FAIL_FC14: "FC14";
+/** Default max identical text units without tool/yield (N>2 is illegal). */
+export declare const DEFAULT_MAX_IDENTICAL_WITHOUT_TOOL = 2;
+/**
+ * Normalize assistant text for identity comparison.
+ * Collapses whitespace, lowercases, strips common trailing punctuation.
+ */
+export declare function normalizeTurnText(text: string): string;
+/** Split a blob into sentence-like units (periods, newlines, ellipsis). */
+export declare function splitTextUnits(text: string): string[];
+/**
+ * True when two normalized strings are near-identical (exact, containment with
+ * high length ratio, or high word Jaccard). Short units never match.
+ */
+export declare function isNearIdentical(a: string, b: string): boolean;
+/**
+ * Detect when a single blob itself embeds the same sentence many times
+ * (model streams one giant assistant message of repeated lines).
+ */
+export declare function countRepeatedUnitsInBlob(text: string): number;
+/**
+ * Evaluate whether a parent turn shape is legal under the FC14 hard-stop.
+ * Pure / side-effect free — safe for mid-stream host gates and unit tests.
+ */
+export declare function evaluateParentTurnShape(input: ParentTurnShapeInput): ParentTurnShapeResult;
+/** Convenience: true when the turn is an illegal text-repetition hang. */
+export declare function isTextRepetitionHang(input: ParentTurnShapeInput): boolean;
+//# sourceMappingURL=evaluate.d.ts.map