@deftai/directive-core 0.87.0 → 0.89.0

package/dist/finish-loop/directive-finish-loop.js

@@ -0,0 +1,239 @@
+/**
+ * directive:finish-loop — outer walk-away cascade (#871 Wave 5).
+ *
+ * 1. Gate on finish-loop human-origin grant (or DEFT_ALLOW_FINISH_LOOP)
+ * 2. Scan xbrief queue (active/pending)
+ * 3. Append progress JSONL each iteration
+ * 4. When --pr supplied, run pr:finish-loop
+ * 5. Implementation steps are agent-owned: CLI emits AGENT_STEP and exits
+ *    ACTION_REQUIRED so a live agent continues; full autonomous coding is
+ *    not inlined in the Taskfile.
+ *
+ * Halt: empty queue | grant expiry/deny | max iterations | gate deny
+ */
+import { evaluateFinishLoopGrant } from "./grant-gate.js";
+import { runPrFinishLoop } from "./pr-finish-loop.js";
+import { appendFinishLoopProgress, finishLoopProgressPath, makeProgressLine } from "./progress.js";
+import { scanFinishLoopQueue } from "./queue.js";
+import { EXIT_ACTION_REQUIRED, EXIT_BLOCKED, EXIT_OK, } from "./types.js";
+export const DEFAULT_MAX_ITERATIONS = 20;
+export function runDirectiveFinishLoop(options) {
+    const projectRoot = options.projectRoot;
+    const progressPath = finishLoopProgressPath(projectRoot);
+    const maxIterations = options.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+    const writeProgress = options.writeProgress !== false;
+    const scan = options.scanQueueFn ?? scanFinishLoopQueue;
+    const prLoop = options.prFinishLoopFn ?? runPrFinishLoop;
+    const progress = (phase, iteration, haltReason, message, fields = {}) => {
+        if (!writeProgress)
+            return;
+        appendFinishLoopProgress(projectRoot, makeProgressLine({
+            phase,
+            iteration,
+            haltReason,
+            message,
+            prNumber: fields.prNumber ?? options.prNumber ?? null,
+            grantId: fields.grantId ?? null,
+            queueCount: fields.queueCount ?? null,
+            exitCode: fields.exitCode ?? null,
+            extra: fields.extra,
+        }));
+    };
+    // --- Gate ---
+    let grantId = null;
+    if (options.skipGrantGate !== true) {
+        const gate = evaluateFinishLoopGrant({
+            projectRoot,
+            env: options.env,
+            now: options.now,
+        });
+        if (!gate.allowed) {
+            const haltReason = gate.code === "authz-grant-expired" ? "grant-expired" : "grant-missing";
+            const message = `BLOCKED directive:finish-loop: ${gate.reason}`;
+            progress("gate", 0, haltReason, message, {
+                grantId: gate.grantId,
+                exitCode: EXIT_BLOCKED,
+            });
+            return {
+                exitCode: EXIT_BLOCKED,
+                haltReason,
+                message,
+                iterations: 0,
+                queueCount: 0,
+                grantId: gate.grantId,
+                progressPath,
+            };
+        }
+        grantId = gate.grantId;
+        progress("gate", 0, null, `grant ok: ${gate.reason}`, { grantId });
+    }
+    let lastQueueCount = 0;
+    for (let iteration = 1; iteration <= maxIterations; iteration += 1) {
+        // Re-check grant each iteration (expiry mid-loop)
+        if (options.skipGrantGate !== true) {
+            const gate = evaluateFinishLoopGrant({
+                projectRoot,
+                env: options.env,
+                now: options.now,
+            });
+            if (!gate.allowed) {
+                const haltReason = gate.code === "authz-grant-expired" ? "grant-expired" : "grant-deny";
+                const message = `BLOCKED directive:finish-loop mid-loop: ${gate.reason}`;
+                progress("halt", iteration, haltReason, message, {
+                    grantId: gate.grantId,
+                    exitCode: EXIT_BLOCKED,
+                    queueCount: lastQueueCount,
+                });
+                return {
+                    exitCode: EXIT_BLOCKED,
+                    haltReason,
+                    message,
+                    iterations: iteration,
+                    queueCount: lastQueueCount,
+                    grantId: gate.grantId,
+                    progressPath,
+                };
+            }
+            grantId = gate.grantId;
+        }
+        const queue = scan(projectRoot);
+        lastQueueCount = queue.length;
+        progress("queue-scan", iteration, null, `queue count=${queue.length}`, {
+            grantId,
+            queueCount: queue.length,
+        });
+        if (queue.length === 0 && (options.prNumber === null || options.prNumber === undefined)) {
+            const message = "directive:finish-loop complete: empty scope queue (no active/pending xBRIEF work).";
+            progress("halt", iteration, "empty-queue", message, {
+                grantId,
+                queueCount: 0,
+                exitCode: EXIT_OK,
+            });
+            return {
+                exitCode: EXIT_OK,
+                haltReason: "empty-queue",
+                message,
+                iterations: iteration,
+                queueCount: 0,
+                grantId,
+                progressPath,
+            };
+        }
+        // Optional PR shepherd
+        if (options.prNumber !== null && options.prNumber !== undefined) {
+            const prResult = prLoop({
+                projectRoot,
+                prNumber: options.prNumber,
+                repo: options.repo,
+                maxWaitMinutes: options.maxWaitMinutes,
+                pollSeconds: options.pollSeconds,
+                oneShot: options.oneShot,
+                merge: options.merge,
+                skipGrantGate: true, // already gated
+                env: options.env,
+                now: options.now,
+                writeProgress,
+                iteration,
+            });
+            progress("pr-watch", iteration, prResult.haltReason, prResult.message, {
+                grantId,
+                queueCount: queue.length,
+                exitCode: prResult.exitCode,
+                prNumber: options.prNumber,
+            });
+            if (prResult.haltReason === "address-findings") {
+                return {
+                    exitCode: EXIT_ACTION_REQUIRED,
+                    haltReason: "address-findings",
+                    message: prResult.message,
+                    iterations: iteration,
+                    queueCount: queue.length,
+                    grantId,
+                    progressPath,
+                };
+            }
+            if (prResult.haltReason === "require-human-merge") {
+                return {
+                    exitCode: EXIT_ACTION_REQUIRED,
+                    haltReason: "require-human-merge",
+                    message: prResult.message,
+                    iterations: iteration,
+                    queueCount: queue.length,
+                    grantId,
+                    progressPath,
+                };
+            }
+            if (prResult.exitCode === EXIT_BLOCKED) {
+                return {
+                    exitCode: EXIT_BLOCKED,
+                    haltReason: prResult.haltReason,
+                    message: prResult.message,
+                    iterations: iteration,
+                    queueCount: queue.length,
+                    grantId,
+                    progressPath,
+                };
+            }
+            // CLEAN / MERGED with empty queue → done
+            if (queue.length === 0) {
+                const message = `directive:finish-loop done after PR #${options.prNumber}: ${prResult.haltReason}`;
+                progress("halt", iteration, prResult.haltReason, message, {
+                    grantId,
+                    queueCount: 0,
+                    exitCode: EXIT_OK,
+                    prNumber: options.prNumber,
+                });
+                return {
+                    exitCode: EXIT_OK,
+                    haltReason: prResult.haltReason,
+                    message,
+                    iterations: iteration,
+                    queueCount: 0,
+                    grantId,
+                    progressPath,
+                };
+            }
+        }
+        // Agent-owned implement step when queue non-empty
+        if (queue.length > 0) {
+            const top = queue[0];
+            const message = `AGENT_STEP directive:finish-loop iteration=${iteration}: ` +
+                `${queue.length} scope item(s) remain (next: ${top?.name ?? "?"}). ` +
+                "Implementation is agent-orchestrated: promote/activate story, implement, " +
+                "open PR, then re-run `task directive:finish-loop` / `task pr:finish-loop -- <N>`. " +
+                "Gates already verified finish-loop grant for edit/push/pr/merge.";
+            progress("implement", iteration, "agent-implement", message, {
+                grantId,
+                queueCount: queue.length,
+                exitCode: EXIT_ACTION_REQUIRED,
+                extra: { nextPath: top?.path },
+            });
+            return {
+                exitCode: EXIT_ACTION_REQUIRED,
+                haltReason: "agent-implement",
+                message,
+                iterations: iteration,
+                queueCount: queue.length,
+                grantId,
+                progressPath,
+            };
+        }
+    }
+    const message = `directive:finish-loop halted: max iterations (${maxIterations}) reached ` +
+        `with queueCount=${lastQueueCount}.`;
+    progress("halt", maxIterations, "max-iterations", message, {
+        grantId,
+        queueCount: lastQueueCount,
+        exitCode: EXIT_BLOCKED,
+    });
+    return {
+        exitCode: EXIT_BLOCKED,
+        haltReason: "max-iterations",
+        message,
+        iterations: maxIterations,
+        queueCount: lastQueueCount,
+        grantId,
+        progressPath,
+    };
+}
+//# sourceMappingURL=directive-finish-loop.js.map

package/dist/finish-loop/grant-gate.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Finish-loop grant gate (#871): require a live human-origin grant covering
+ * edit/push/pr/merge (finish-loop template ops), or DEFT_ALLOW_FINISH_LOOP=1.
+ *
+ * Agent-authored grants never satisfy. No second mint path.
+ */
+import type { AuthzOperation, HumanOriginGrant } from "../authz/types.js";
+import type { FinishLoopGrantGateResult } from "./types.js";
+export type EnvMap = Readonly<Record<string, string | undefined>>;
+/**
+ * True when grant.operations covers every finish-loop op (edit, push, pr, merge).
+ * A single grant may cover the full set; partial coverage reports missing ops.
+ */
+export declare function grantCoversFinishLoopOps(grant: HumanOriginGrant): {
+    covered: boolean;
+    missing: AuthzOperation[];
+};
+export interface EvaluateFinishLoopGrantInput {
+    readonly projectRoot: string;
+    readonly grants?: readonly HumanOriginGrant[];
+    readonly env?: EnvMap;
+    readonly now?: Date;
+    /** When set, require grant to cover at least this op (default: full finish-loop set). */
+    readonly requireFullSet?: boolean;
+    readonly op?: AuthzOperation;
+}
+/**
+ * Fail-closed gate for finish-loop / pr:finish-loop entry.
+ */
+export declare function evaluateFinishLoopGrant(input: EvaluateFinishLoopGrantInput): FinishLoopGrantGateResult;
+//# sourceMappingURL=grant-gate.d.ts.map

package/dist/finish-loop/grant-gate.js

@@ -0,0 +1,169 @@
+/**
+ * Finish-loop grant gate (#871): require a live human-origin grant covering
+ * edit/push/pr/merge (finish-loop template ops), or DEFT_ALLOW_FINISH_LOOP=1.
+ *
+ * Agent-authored grants never satisfy. No second mint path.
+ */
+import { isHumanOriginGrant, isRejectedOriginKind } from "../authz/origin.js";
+import { listActiveHumanGrants, listGrants, loadAuthzState } from "../authz/store.js";
+import { FINISH_LOOP_OPERATIONS, FINISH_LOOP_TEMPLATE_NAME } from "../authz/templates.js";
+const ENV_BYPASS = "DEFT_ALLOW_FINISH_LOOP";
+function envTruthy(value) {
+    if (value === undefined)
+        return false;
+    const v = value.trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+function grantLive(grant, now) {
+    if (!isHumanOriginGrant(grant)) {
+        const kind = grant.origin.kind;
+        if (isRejectedOriginKind(kind)) {
+            return {
+                ok: false,
+                code: "authz-grant-origin-reject",
+                reason: `Directive denied finish-loop: grant ${grant.id} origin.kind=${kind} is ` +
+                    "agent/self-authored and cannot authorize walk-away ops. " +
+                    `Human action required: \`deft authz:grant -- --template ${FINISH_LOOP_TEMPLATE_NAME}\`.`,
+            };
+        }
+        return {
+            ok: false,
+            code: "authz-grant-origin-reject",
+            reason: `Directive denied finish-loop: grant ${grant.id} lacks human-origin provenance. ` +
+                `Human action required: \`deft authz:grant -- --template ${FINISH_LOOP_TEMPLATE_NAME}\`.`,
+        };
+    }
+    if (grant.semantics.revokedAt !== null) {
+        return {
+            ok: false,
+            code: "authz-grant-revoked",
+            reason: `Directive denied finish-loop: grant ${grant.id} was revoked at ${grant.semantics.revokedAt}.`,
+        };
+    }
+    if (grant.semantics.singleUse && grant.semantics.usedAt !== null) {
+        return {
+            ok: false,
+            code: "authz-grant-single-use-spent",
+            reason: `Directive denied finish-loop: single-use grant ${grant.id} already spent.`,
+        };
+    }
+    if (grant.semantics.expiresAt !== null) {
+        const exp = Date.parse(grant.semantics.expiresAt);
+        if (Number.isNaN(exp) || exp <= now.getTime()) {
+            return {
+                ok: false,
+                code: "authz-grant-expired",
+                reason: `Directive denied finish-loop: grant ${grant.id} expired at ${grant.semantics.expiresAt}. ` +
+                    `Human action required: mint a fresh grant via \`deft authz:grant -- --template ${FINISH_LOOP_TEMPLATE_NAME}\`.`,
+            };
+        }
+    }
+    return { ok: true, code: "finish-loop-allow", reason: "ok" };
+}
+/**
+ * True when grant.operations covers every finish-loop op (edit, push, pr, merge).
+ * A single grant may cover the full set; partial coverage reports missing ops.
+ */
+export function grantCoversFinishLoopOps(grant) {
+    const have = new Set(grant.scope.operations.map((o) => o.toLowerCase()));
+    const missing = FINISH_LOOP_OPERATIONS.filter((op) => !have.has(op.toLowerCase()));
+    return { covered: missing.length === 0, missing: [...missing] };
+}
+/**
+ * Fail-closed gate for finish-loop / pr:finish-loop entry.
+ */
+export function evaluateFinishLoopGrant(input) {
+    const env = input.env ?? process.env;
+    if (envTruthy(env[ENV_BYPASS])) {
+        return {
+            allowed: true,
+            code: "finish-loop-env-bypass",
+            reason: `Directive allowed finish-loop via ephemeral env bypass ${ENV_BYPASS}=1.`,
+            grantId: null,
+            missingOps: [],
+        };
+    }
+    const now = input.now ?? new Date();
+    const state = loadAuthzState(input.projectRoot);
+    // Prefer active grants; if none, still inspect disk grants so expiry/origin
+    // denials surface as grant-expired / origin-reject rather than silent missing.
+    let grants;
+    if (input.grants !== undefined) {
+        grants = input.grants;
+    }
+    else {
+        const active = listActiveHumanGrants(input.projectRoot, state, now);
+        grants = active.length > 0 ? active : listGrants(input.projectRoot);
+    }
+    let lastDeny = null;
+    for (const grant of grants) {
+        const live = grantLive(grant, now);
+        if (!live.ok) {
+            lastDeny = {
+                allowed: false,
+                code: live.code,
+                reason: live.reason,
+                grantId: grant.id,
+                missingOps: [],
+            };
+            continue;
+        }
+        if (input.op !== undefined) {
+            const have = grant.scope.operations.map((o) => o.toLowerCase());
+            if (!have.includes(input.op.toLowerCase())) {
+                lastDeny = {
+                    allowed: false,
+                    code: "authz-grant-scope-deny",
+                    reason: `Directive denied finish-loop: grant ${grant.id} ops=[${grant.scope.operations.join(",")}] ` +
+                        `does not cover '${input.op}'. Human action required: ` +
+                        `\`deft authz:grant -- --template ${FINISH_LOOP_TEMPLATE_NAME}\`.`,
+                    grantId: grant.id,
+                    missingOps: [input.op],
+                };
+                continue;
+            }
+            return {
+                allowed: true,
+                code: "finish-loop-allow",
+                reason: `Directive allowed finish-loop op '${input.op}' via human-origin grant ${grant.id}.`,
+                grantId: grant.id,
+                missingOps: [],
+            };
+        }
+        const cover = grantCoversFinishLoopOps(grant);
+        if (!cover.covered && input.requireFullSet !== false) {
+            lastDeny = {
+                allowed: false,
+                code: "authz-grant-scope-deny",
+                reason: `Directive denied finish-loop: grant ${grant.id} missing ops ` +
+                    `[${cover.missing.join(",")}]. Finish-loop requires ` +
+                    `[${FINISH_LOOP_OPERATIONS.join(",")}]. Human action required: ` +
+                    `\`deft authz:grant -- --template ${FINISH_LOOP_TEMPLATE_NAME}\`.`,
+                grantId: grant.id,
+                missingOps: cover.missing,
+            };
+            continue;
+        }
+        return {
+            allowed: true,
+            code: "finish-loop-allow",
+            reason: `Directive allowed finish-loop via human-origin grant ${grant.id}.`,
+            grantId: grant.id,
+            missingOps: [],
+        };
+    }
+    if (lastDeny !== null)
+        return lastDeny;
+    return {
+        allowed: false,
+        code: "authz-grant-missing",
+        reason: "Directive denied finish-loop: no human-origin grant covers edit/push/pr/merge " +
+            `and ${ENV_BYPASS} is not set. Human action required: ` +
+            `\`deft authz:grant -- --template ${FINISH_LOOP_TEMPLATE_NAME}\` ` +
+            `(or set ${ENV_BYPASS}=1 for a single-shell ephemeral bypass). ` +
+            "Release-class verbs are NOT authorized by this template.",
+        grantId: null,
+        missingOps: [...FINISH_LOOP_OPERATIONS],
+    };
+}
+//# sourceMappingURL=grant-gate.js.map

package/dist/finish-loop/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Walk-away finish-loop product (#871 Wave 5 / #2948).
+ */
+export * from "./directive-finish-loop.js";
+export * from "./grant-gate.js";
+export * from "./main.js";
+export * from "./pr-finish-loop.js";
+export * from "./progress.js";
+export * from "./queue.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/finish-loop/index.js

@@ -0,0 +1,11 @@
+/**
+ * Walk-away finish-loop product (#871 Wave 5 / #2948).
+ */
+export * from "./directive-finish-loop.js";
+export * from "./grant-gate.js";
+export * from "./main.js";
+export * from "./pr-finish-loop.js";
+export * from "./progress.js";
+export * from "./queue.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/finish-loop/main.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CLI entry for pr:finish-loop and directive:finish-loop (#871).
+ */
+export interface ParsedPrFinishArgs {
+    readonly prNumber: number | null;
+    readonly repo: string | null;
+    readonly projectRoot: string;
+    readonly maxWaitMinutes: number | null;
+    readonly pollSeconds: number | null;
+    readonly oneShot: boolean;
+    readonly merge: boolean;
+    readonly emitJson: boolean;
+    readonly help: boolean;
+    readonly error?: string;
+}
+export interface ParsedDirectiveFinishArgs {
+    readonly prNumber: number | null;
+    readonly repo: string | null;
+    readonly projectRoot: string;
+    readonly maxIterations: number | null;
+    readonly maxWaitMinutes: number | null;
+    readonly pollSeconds: number | null;
+    readonly oneShot: boolean;
+    readonly merge: boolean;
+    readonly emitJson: boolean;
+    readonly help: boolean;
+    readonly error?: string;
+}
+export declare function parsePrFinishArgs(argv: readonly string[]): ParsedPrFinishArgs;
+export declare function parseDirectiveFinishArgs(argv: readonly string[]): ParsedDirectiveFinishArgs;
+export declare function formatPrFinishHelp(): string;
+export declare function formatDirectiveFinishHelp(): string;
+export declare function cmdPrFinishLoop(argv?: readonly string[]): number;
+export declare function cmdDirectiveFinishLoop(argv?: readonly string[]): number;
+//# sourceMappingURL=main.d.ts.map