@deftai/directive-core 0.104.0 → 0.106.0

package/dist/policy/project-invariants.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Typed plan.policy.projectInvariants (#3425 Story A).
+ *
+ * Authored project-level must-not-break contracts. Empty or absent list is a
+ * no-op. Parse/validate only — preflight fail-closed is Story B.
+ */
+export declare const FIELD_PROJECT_INVARIANTS = "plan.policy.projectInvariants";
+export declare const FIELD_PROJECT_INVARIANTS_CLI_ALIAS = "projectInvariants";
+export interface ProjectInvariantContractSurface {
+    readonly paths: readonly string[];
+    readonly moduleIds: readonly string[];
+}
+export interface ProjectInvariant {
+    readonly id: string;
+    readonly statement: string;
+    readonly contractSurface: ProjectInvariantContractSurface;
+}
+export type ProjectInvariantsSource = "typed" | "default" | "default-on-error";
+export interface ProjectInvariantsParseResult {
+    readonly invariants: readonly ProjectInvariant[];
+    readonly errors: readonly string[];
+}
+export interface ProjectInvariantsResolved {
+    readonly invariants: readonly ProjectInvariant[];
+    readonly source: ProjectInvariantsSource;
+    readonly error: string | null;
+}
+export interface ProjectInvariantsPolicyField {
+    readonly name: typeof FIELD_PROJECT_INVARIANTS;
+    readonly current: readonly ProjectInvariant[];
+    readonly default: readonly ProjectInvariant[];
+    readonly source: string;
+}
+/** Parse a raw projectInvariants value. Absent/null → empty list, no errors. */
+export declare function parseProjectInvariants(raw: unknown): ProjectInvariantsParseResult;
+/**
+ * Map codeStructure.modules[] id → pathGlobs for applicability intersection.
+ * Pure: pass PROJECT-DEFINITION (or plan) data, no disk IO.
+ */
+export declare function extractModulePathGlobs(projectDefinition: unknown): Record<string, string[]>;
+/**
+ * Resolve projectInvariants from PROJECT-DEFINITION data already in memory.
+ * Absent/null → default empty. Present invalid → default-on-error + message.
+ */
+export declare function resolveProjectInvariantsFromData(data: Record<string, unknown> | null): ProjectInvariantsResolved;
+/** Resolve from a project root via the PROJECT-DEFINITION IO path. */
+export declare function resolveProjectInvariants(projectRoot: string): ProjectInvariantsResolved;
+/** Inspector row for `task policy:show --field=projectInvariants`. */
+export declare function inspectProjectInvariants(data: Record<string, unknown> | null, projectRoot?: string): ProjectInvariantsPolicyField;
+//# sourceMappingURL=project-invariants.d.ts.map

package/dist/policy/project-invariants.js

@@ -0,0 +1,205 @@
+/**
+ * Typed plan.policy.projectInvariants (#3425 Story A).
+ *
+ * Authored project-level must-not-break contracts. Empty or absent list is a
+ * no-op. Parse/validate only — preflight fail-closed is Story B.
+ */
+import { readPlanPolicy } from "./plan-extensions.js";
+import { loadProjectDefinition } from "./resolve.js";
+export const FIELD_PROJECT_INVARIANTS = "plan.policy.projectInvariants";
+export const FIELD_PROJECT_INVARIANTS_CLI_ALIAS = "projectInvariants";
+const EMPTY = [];
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function asStrList(value) {
+    if (value === null || value === undefined)
+        return [];
+    if (typeof value === "string")
+        return value.trim().length > 0 ? [value.trim()] : [];
+    if (Array.isArray(value)) {
+        return value.map((item) => String(item).trim()).filter((s) => s.length > 0);
+    }
+    return [];
+}
+function pythonTypeName(value) {
+    if (value === null)
+        return "None";
+    if (Array.isArray(value))
+        return "list";
+    if (typeof value === "boolean")
+        return "bool";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? "int" : "float";
+    if (typeof value === "string")
+        return "str";
+    if (typeof value === "object")
+        return "dict";
+    return typeof value;
+}
+function parseContractSurface(body, loc) {
+    const nested = asRecord(body.contractSurface) ?? asRecord(body.contract_surface) ?? asRecord(body.contract);
+    const pathSource = nested ?? body;
+    const moduleSource = nested ?? body;
+    const pathsRaw = pathSource.paths ?? pathSource.pathGlobs ?? pathSource.path_globs ?? body.paths;
+    const moduleRaw = moduleSource.moduleIds ??
+        moduleSource.module_ids ??
+        moduleSource.modules ??
+        body.moduleIds ??
+        body.module_ids;
+    // Shorthand: contractSurface / contract_surface as a string list of paths.
+    const shorthand = body.contractSurface ?? body.contract_surface ?? body.contract;
+    const paths = [...asStrList(pathsRaw), ...(nested === null ? asStrList(shorthand) : [])];
+    const moduleIds = asStrList(moduleRaw);
+    if (paths.length === 0 && moduleIds.length === 0) {
+        return {
+            surface: null,
+            errors: [
+                `${loc}: contract surface requires paths[] and/or moduleIds[] ` +
+                    `(must-not-break module/contract)`,
+            ],
+        };
+    }
+    return {
+        surface: { paths, moduleIds },
+        errors: [],
+    };
+}
+/** Parse a raw projectInvariants value. Absent/null → empty list, no errors. */
+export function parseProjectInvariants(raw) {
+    if (raw === null || raw === undefined) {
+        return { invariants: EMPTY, errors: [] };
+    }
+    if (!Array.isArray(raw)) {
+        return {
+            invariants: EMPTY,
+            errors: [`${FIELD_PROJECT_INVARIANTS} must be an array; got ${pythonTypeName(raw)}`],
+        };
+    }
+    const invariants = [];
+    const errors = [];
+    const seen = new Set();
+    for (let i = 0; i < raw.length; i += 1) {
+        const loc = `${FIELD_PROJECT_INVARIANTS}[${i}]`;
+        const item = raw[i];
+        const rec = asRecord(item);
+        if (rec === null) {
+            errors.push(`${loc}: entry must be an object`);
+            continue;
+        }
+        const id = rec.id;
+        const statement = rec.statement ?? rec.Statement;
+        if (!isNonEmptyString(id)) {
+            errors.push(`${loc}: id is required`);
+            continue;
+        }
+        const trimmedId = id.trim();
+        if (seen.has(trimmedId)) {
+            errors.push(`${loc}: duplicate id '${trimmedId}'`);
+            continue;
+        }
+        if (!isNonEmptyString(statement)) {
+            errors.push(`${loc}: statement is required`);
+            continue;
+        }
+        const { surface, errors: surfaceErrors } = parseContractSurface(rec, loc);
+        errors.push(...surfaceErrors);
+        if (surface === null)
+            continue;
+        seen.add(trimmedId);
+        invariants.push({
+            id: trimmedId,
+            statement: String(statement).trim(),
+            contractSurface: surface,
+        });
+    }
+    return { invariants, errors };
+}
+/**
+ * Map codeStructure.modules[] id → pathGlobs for applicability intersection.
+ * Pure: pass PROJECT-DEFINITION (or plan) data, no disk IO.
+ */
+export function extractModulePathGlobs(projectDefinition) {
+    const root = asRecord(projectDefinition);
+    if (root === null)
+        return {};
+    const plan = asRecord(root.plan) ?? root;
+    const architecture = asRecord(plan.architecture);
+    if (architecture === null)
+        return {};
+    const codeStructure = asRecord(architecture.codeStructure ?? architecture.code_structure);
+    if (codeStructure === null)
+        return {};
+    const modules = codeStructure.modules;
+    if (!Array.isArray(modules))
+        return {};
+    const out = {};
+    for (const item of modules) {
+        const rec = asRecord(item);
+        if (rec === null || !isNonEmptyString(rec.id))
+            continue;
+        const globs = asStrList(rec.pathGlobs ?? rec.path_globs ?? rec.paths);
+        if (globs.length === 0)
+            continue;
+        out[rec.id.trim()] = globs;
+    }
+    return out;
+}
+function readPolicyBlock(data) {
+    if (data === null)
+        return null;
+    const policy = readPlanPolicy(data.plan);
+    return asRecord(policy);
+}
+/**
+ * Resolve projectInvariants from PROJECT-DEFINITION data already in memory.
+ * Absent/null → default empty. Present invalid → default-on-error + message.
+ */
+export function resolveProjectInvariantsFromData(data) {
+    const policy = readPolicyBlock(data);
+    if (policy === null || !("projectInvariants" in policy)) {
+        return { invariants: EMPTY, source: "default", error: null };
+    }
+    const raw = policy.projectInvariants;
+    if (raw === null) {
+        return { invariants: EMPTY, source: "default", error: null };
+    }
+    const parsed = parseProjectInvariants(raw);
+    if (parsed.errors.length > 0) {
+        return {
+            invariants: EMPTY,
+            source: "default-on-error",
+            error: parsed.errors.join("; "),
+        };
+    }
+    return { invariants: parsed.invariants, source: "typed", error: null };
+}
+/** Resolve from a project root via the PROJECT-DEFINITION IO path. */
+export function resolveProjectInvariants(projectRoot) {
+    const [data, err] = loadProjectDefinition(projectRoot);
+    if (data === null) {
+        return { invariants: EMPTY, source: "default", error: err };
+    }
+    return resolveProjectInvariantsFromData(data);
+}
+/** Inspector row for `task policy:show --field=projectInvariants`. */
+export function inspectProjectInvariants(data, projectRoot) {
+    const resolved = data !== null
+        ? resolveProjectInvariantsFromData(data)
+        : projectRoot !== undefined && projectRoot.length > 0
+            ? resolveProjectInvariants(projectRoot)
+            : { invariants: EMPTY, source: "default", error: null };
+    return {
+        name: FIELD_PROJECT_INVARIANTS,
+        current: resolved.invariants,
+        default: EMPTY,
+        source: resolved.source,
+    };
+}
+//# sourceMappingURL=project-invariants.js.map

package/dist/policy/require-human-merge.js

@@ -18,7 +18,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
 import { policyColonInvocation } from "./policy-invocation.js";
-import { appendAuditLog, loadProjectDefinition, projectDefinitionPath } from "./resolve.js";
+import { appendAuditLog, loadProjectDefinition, projectDefinitionPath, stampChangedToken, } from "./resolve.js";
 export const FIELD_REQUIRE_HUMAN_MERGE = "plan.policy.requireHumanMerge";
 export const FIELD_REQUIRE_HUMAN_MERGE_CLI_ALIAS = "requireHumanMerge";
 export const FIELD_AUTO_DEPLOY_ON_MERGE = "plan.policy.autoDeployOnMerge";
@@ -285,7 +285,7 @@ export function setRequireHumanMerge(projectRoot, options) {
             }
         }
         const plan = data.plan;
-        migrateLegacyPolicyKey(plan);
+        const legacyKeyMigrated = migrateLegacyPolicyKey(plan);
         const existingPolicy = plan[PLAN_POLICY_KEY];
         if (typeof existingPolicy !== "object" ||
             existingPolicy === null ||
@@ -309,8 +309,7 @@ export function setRequireHumanMerge(projectRoot, options) {
             delete narratives[LEGACY_REQUIRE_HUMAN_MERGE_KEY];
             legacyDropped = true;
         }
-        atomicWriteProjectDefinition(path, data);
-        const changed = previous !== Boolean(requireHumanMerge) || legacyDropped;
+        const changed = previous !== Boolean(requireHumanMerge) || legacyDropped || legacyKeyMigrated;
         const parts = [
             `actor=${actor}`,
             `requireHumanMerge=${requireHumanMerge ? "true" : "false"}`,
@@ -321,8 +320,11 @@ export function setRequireHumanMerge(projectRoot, options) {
         if (note) {
             parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
         }
-        const auditEntry = parts.join(" ");
-        appendAuditLog(projectRoot, auditEntry);
+        const auditEntry = stampChangedToken(parts.join(" "), changed);
+        if (changed) {
+            atomicWriteProjectDefinition(path, data);
+        }
+        appendAuditLog(projectRoot, auditEntry, changed);
         return { changed, auditEntry };
     });
 }

package/dist/policy/resolve.d.ts

@@ -6,6 +6,10 @@ export declare const ENV_BYPASS = "DEFT_ALLOW_DEFAULT_BRANCH_COMMIT";
 export declare const LEGACY_NARRATIVE_KEY = "Allow direct commits to master";
 /** Audit log relative path (#746). */
 export declare const AUDIT_LOG_REL_PATH = "meta/policy-changes.log";
+/** Operator line when a policy writer matches current state and does not append (#3528). */
+export declare const POLICY_AUDIT_NOOP_STDOUT = "  no-op: value already matched (ledger unchanged).";
+/** Stamp a machine-readable `changed=true|false` token (#3528 / UPGRADING.md). */
+export declare function stampChangedToken(entry: string, changed: boolean): string;
 export type PolicySource = "typed" | "legacy-narrative" | "env-bypass" | "default-fail-closed";
 export interface PolicyResult {
     readonly allowDirectCommits: boolean;
@@ -28,8 +32,9 @@ export declare function coerceLegacyNarrative(value: unknown): {
 export declare function loadProjectDefinition(projectRoot: string): [Record<string, unknown> | null, string | null];
 /** Resolve the effective branch-commit policy (#746 / #747). */
 export declare function resolvePolicy(projectRoot: string): PolicyResult;
-/** Append a one-line audit entry to meta/policy-changes.log (#746). */
-export declare function appendAuditLog(projectRoot: string, entry: string): string;
+/** Append a one-line audit entry to meta/policy-changes.log (#746).
+ * No-op (`changed=false`) does not create or modify the tracked file (#3528). */
+export declare function appendAuditLog(projectRoot: string, entry: string, changed?: boolean): string;
 /** Write the typed policy flag back to PROJECT-DEFINITION (#746). */
 export declare function setPolicy(projectRoot: string, options: {
     allowDirectCommits: boolean;

package/dist/policy/resolve.js

@@ -13,6 +13,16 @@ export const ENV_BYPASS = "DEFT_ALLOW_DEFAULT_BRANCH_COMMIT";
 export const LEGACY_NARRATIVE_KEY = "Allow direct commits to master";
 /** Audit log relative path (#746). */
 export const AUDIT_LOG_REL_PATH = "meta/policy-changes.log";
+/** Operator line when a policy writer matches current state and does not append (#3528). */
+export const POLICY_AUDIT_NOOP_STDOUT = "  no-op: value already matched (ledger unchanged).";
+const CHANGED_TOKEN_RE = /(?:^|\s)changed=(?:true|false)(?:\s|$)/;
+/** Stamp a machine-readable `changed=true|false` token (#3528 / UPGRADING.md). */
+export function stampChangedToken(entry, changed) {
+    if (CHANGED_TOKEN_RE.test(entry)) {
+        return entry;
+    }
+    return `${entry} changed=${changed ? "true" : "false"}`;
+}
 const TRUTHY = new Set(["1", "true", "yes", "on"]);
 /**
  * Resolve absolute path to PROJECT-DEFINITION. Layout-aware (#2109 part 2a):
@@ -176,10 +186,15 @@ export function resolvePolicy(projectRoot) {
 function nowIso() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 }
-/** Append a one-line audit entry to meta/policy-changes.log (#746). */
-export function appendAuditLog(projectRoot, entry) {
+/** Append a one-line audit entry to meta/policy-changes.log (#746).
+ * No-op (`changed=false`) does not create or modify the tracked file (#3528). */
+export function appendAuditLog(projectRoot, entry, changed = true) {
     const root = pathResolve(projectRoot);
     const logPath = join(root, AUDIT_LOG_REL_PATH);
+    const stamped = stampChangedToken(entry, changed);
+    if (!changed) {
+        return logPath;
+    }
     // #2980 wave D: product write sink routes through containedWrite.
     if (!existsSync(logPath)) {
         const header = "# meta/policy-changes.log -- audit trail for " +
@@ -194,7 +209,7 @@ export function appendAuditLog(projectRoot, entry) {
     containedWrite({
         root,
         target: AUDIT_LOG_REL_PATH,
-        data: `${nowIso()} ${entry}\n`,
+        data: `${nowIso()} ${stamped}\n`,
         mode: "append",
     });
     return logPath;
@@ -224,7 +239,7 @@ export function setPolicy(projectRoot, options) {
             }
         }
         const plan = data.plan;
-        migrateLegacyPolicyKey(plan);
+        const legacyKeyMigrated = migrateLegacyPolicyKey(plan);
         const existingPolicy = plan[PLAN_POLICY_KEY];
         if (typeof existingPolicy !== "object" ||
             existingPolicy === null ||
@@ -248,8 +263,7 @@ export function setPolicy(projectRoot, options) {
             delete narratives[LEGACY_NARRATIVE_KEY];
             legacyDropped = true;
         }
-        atomicWriteProjectDefinition(path, data);
-        const changed = previous !== Boolean(allowDirectCommits) || legacyDropped;
+        const changed = previous !== Boolean(allowDirectCommits) || legacyDropped || legacyKeyMigrated;
         const parts = [
             `actor=${actor}`,
             `allowDirectCommitsToMaster=${allowDirectCommits ? "true" : "false"}`,
@@ -261,8 +275,11 @@ export function setPolicy(projectRoot, options) {
         if (note) {
             parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
         }
-        const auditEntry = parts.join(" ");
-        appendAuditLog(projectRoot, auditEntry);
+        const auditEntry = stampChangedToken(parts.join(" "), changed);
+        if (changed) {
+            atomicWriteProjectDefinition(path, data);
+        }
+        appendAuditLog(projectRoot, auditEntry, changed);
         return { changed, auditEntry };
     });
 }

package/dist/policy/sync-default.d.ts

@@ -0,0 +1,129 @@
+/**
+ * scm:sync-default (#3391 / #3377 Wave 3).
+ *
+ * Consumes the shared #3388 detector and #3390 syncMaxFiles. Opens dest-targeted
+ * sync PRs. Over the file limit, cut at merge commits when possible so each
+ * dest-based leg is at or under the threshold. Each leg is a new branch and a
+ * new PR. Never retarget or reuse an oversized PR.
+ */
+import { type GitRunner } from "../session/git.js";
+import { type BranchSyncDetection } from "./branch-sync.js";
+import { type SyncMaxFilesProvenance } from "./sync-max-files.js";
+export declare const SYNC_DEFAULT_VERB = "scm:sync-default";
+export declare const FORBIDDEN_SYNC_PR_RETARGET = "gh pr edit --base";
+export type SyncDefaultAction = "noop" | "single" | "staged";
+export type SyncDefaultNoopReason = "not-sync" | "already-synced" | "zero-files" | "fetch-failed" | "diff-failed";
+export type SyncDefaultCutKind = "merge" | "commit" | "tip";
+export interface SyncDefaultCommit {
+    readonly sha: string;
+    readonly isMerge: boolean;
+}
+export interface SyncDefaultLeg {
+    readonly index: number;
+    readonly sha: string;
+    readonly fileCount: number;
+    readonly cutKind: SyncDefaultCutKind;
+    readonly branchName: string;
+}
+export interface SyncDefaultPlan {
+    readonly action: SyncDefaultAction;
+    readonly noopReason: SyncDefaultNoopReason | null;
+    readonly dest: string;
+    readonly source: string;
+    readonly threshold: number;
+    readonly provenance: SyncMaxFilesProvenance;
+    readonly totalCount: number | null;
+    readonly legs: readonly SyncDefaultLeg[];
+    readonly nextLegIndex: number | null;
+    readonly message: string;
+    readonly detectorReason: BranchSyncDetection["reason"];
+}
+export interface SyncDefaultOpenPull {
+    readonly number: number;
+    readonly htmlUrl: string;
+    readonly headRef: string;
+    readonly headSha: string;
+    readonly baseRef: string;
+}
+export interface SyncDefaultForge {
+    listOpenPulls(repo: string, base: string): readonly SyncDefaultOpenPull[];
+    createPull(repo: string, input: {
+        readonly title: string;
+        readonly head: string;
+        readonly base: string;
+        readonly body: string;
+    }): {
+        readonly number: number;
+        readonly htmlUrl: string;
+    };
+}
+export interface SyncDefaultOpened {
+    readonly leg: SyncDefaultLeg;
+    readonly prNumber: number;
+    readonly prUrl: string;
+    readonly branch: string;
+    readonly reusedExisting: boolean;
+}
+export interface SyncDefaultApplyResult {
+    readonly plan: SyncDefaultPlan;
+    readonly opened: readonly SyncDefaultOpened[];
+    readonly retargeted: false;
+}
+export declare function syncDefaultBranchName(dest: string, source: string, index: number, sha: string): string;
+export declare function parseGithubOwnerRepo(remoteUrl: string): string | null;
+export declare function countChangedFilesOnRange(options: {
+    readonly projectRoot: string;
+    readonly left: string;
+    readonly right: string;
+    readonly runGit?: GitRunner;
+}): {
+    readonly count: number | null;
+    readonly error: string | null;
+};
+export declare function listCommitsAfter(options: {
+    readonly projectRoot: string;
+    readonly dest: string;
+    readonly source: string;
+    readonly runGit?: GitRunner;
+}): {
+    readonly commits: readonly SyncDefaultCommit[];
+    readonly error: string | null;
+};
+/**
+ * Cut dest..source into dest-targeted legs whose dest-based file count is at
+ * or under the threshold when a merge (or other) cut exists.
+ */
+export declare function cutSyncLegs(options: {
+    readonly dest: string;
+    readonly source: string;
+    readonly destRef: string;
+    readonly sourceSha: string;
+    readonly commits: readonly SyncDefaultCommit[];
+    readonly threshold: number;
+    readonly countFiles: (left: string, right: string) => number | null;
+    /** When set, later cuts must be descendants of the previous cut. */
+    readonly isAncestor?: (ancestor: string, descendant: string) => boolean;
+}): {
+    readonly legs: readonly SyncDefaultLeg[];
+    readonly error: string | null;
+};
+export declare function planSyncDefault(options: {
+    readonly projectRoot: string;
+    readonly maxFiles?: number | null;
+    readonly destTipSha?: string;
+    readonly runGit?: GitRunner;
+}): SyncDefaultPlan;
+export declare function nextOpenableLeg(legs: readonly SyncDefaultLeg[], destTipSha: string, projectRoot: string, runGit: GitRunner): SyncDefaultLeg | null;
+export declare function applySyncDefault(options: {
+    readonly projectRoot: string;
+    readonly repo: string;
+    readonly plan?: SyncDefaultPlan;
+    readonly maxFiles?: number | null;
+    readonly destTipSha?: string;
+    readonly dryRun?: boolean;
+    readonly runGit?: GitRunner;
+    readonly forge?: SyncDefaultForge;
+}): SyncDefaultApplyResult;
+export declare function syncDefaultPrBody(plan: SyncDefaultPlan, leg: SyncDefaultLeg): string;
+export declare function formatSyncDefaultHuman(result: SyncDefaultApplyResult): string;
+//# sourceMappingURL=sync-default.d.ts.map