@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/dist/sdk/governance/workflow-completeness.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @module sdk/governance/workflow-completeness
+ *
+ * Reduces declarative field requirements into bounded, content-free diagnostics.
+ */
+import { type WorkflowPolicyDocument, type WorkflowPolicyDecision } from "../../core/policy/workflow-policy.js";
+import type { ValidateCheck } from "./validate.js";
+/** One item-policy violation, retaining field paths but never field values. */
+export interface WorkflowCompletenessViolation {
+    /** Stable item identifier. */
+    id: string;
+    /** Runtime item type. */
+    type: string;
+    /** Lifecycle status evaluated. */
+    status: string;
+    /** Exact rule and missing-field evidence. */
+    decision: WorkflowPolicyDecision;
+}
+/** Load the policy snapshot while containing storage failures in an error check so other validation can continue. */
+export declare function readWorkflowCompletenessCheck(pmRoot: string, items: Parameters<typeof buildWorkflowCompletenessCheck>[1], rowLimit?: number, sourceIncomplete?: boolean): Promise<{
+    check: ValidateCheck;
+    warnings: string[];
+}>;
+/** Evaluate every supplied item while bounding the diagnostic rows independently. */
+export declare function buildWorkflowCompletenessCheck(document: WorkflowPolicyDocument, items: readonly (Readonly<Record<string, unknown>> & {
+    id: string;
+    type: string;
+    status: string;
+})[], rowLimit?: number, sourceIncomplete?: boolean): {
+    check: ValidateCheck;
+    warnings: string[];
+};

package/dist/sdk/governance/workflow-completeness.js

@@ -0,0 +1,2 @@
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e94b776a-9886-57bc-ba87-06f4a30de578")}catch(e2){}})();import{createWorkflowPolicyEvaluator}from"../../core/policy/workflow-policy.js";import{readWorkflowPolicies}from"../../core/policy/workflow-policy-store.js";async function readWorkflowCompletenessCheck(pmRoot,items,rowLimit,sourceIncomplete){const document=await readWorkflowPolicies(pmRoot).catch(()=>null);if(document===null)return{check:{name:"completeness",status:"error",ok:false,details:{policy_registry_readable:false,policy_registry_path:"schema/policies.json",remediation_hint:"Repair schema/policies.json, then rerun pm validate."}},warnings:["validate_completeness_policy_registry_unreadable"]};return buildWorkflowCompletenessCheck(document,items,rowLimit,sourceIncomplete)}function buildWorkflowCompletenessCheck(document,items,rowLimit=5,sourceIncomplete=false){const violations=[];const byType=new Map;let violationCount=0;let incompleteItems=0;let refused=0;const evaluate=createWorkflowPolicyEvaluator(document);for(const item of items){const evaluation=evaluate({operation:"",author:"",before:item,after:item,completeness_only:true});const missing=evaluation.decisions.filter(decision=>!decision.satisfied);if(missing.length===0)continue;incompleteItems+=1;const bucket=byType.get(item.type)??{items:0,violations:0,missing_fields:0};bucket.items+=1;for(const decision of missing){violationCount+=1;bucket.violations+=1;bucket.missing_fields+=decision.missing_fields.length;if(decision.effect==="refuse")refused+=1;if(violations.length<rowLimit)violations.push({id:item.id,type:item.type,status:item.status,decision})}byType.set(item.type,bucket)}const status=sourceIncomplete||refused>0?"error":violationCount>0?"warn":"ok";return{check:{name:"completeness",status,ok:status==="ok",details:{scope:"operation_independent_require_fields",checked_items:items.length,incomplete_items:incompleteItems,violation_count:violationCount,refused_violations:refused,missing_by_type:Object.fromEntries(byType),violations,violations_truncated:violations.length<violationCount,enforcement:document.enforcement}},warnings:[...violationCount>0?[`validate_completeness_missing_fields:${violationCount}`]:[],...sourceIncomplete?["validate_completeness_source_incomplete"]:[]]}}export{buildWorkflowCompletenessCheck,readWorkflowCompletenessCheck};
+//# sourceMappingURL=workflow-completeness.js.map

package/dist/sdk/governance/workflow-policy.d.ts

@@ -0,0 +1,47 @@
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+import { type WorkflowPolicyAction, type WorkflowPolicyDocument, type WorkflowPolicyEvaluation } from "../../core/policy/workflow-policy.js";
+export * from "../../core/policy/workflow-policy.js";
+export * from "../../core/policy/workflow-policy-schema.js";
+export { buildWorkflowCompletenessCheck, type WorkflowCompletenessViolation } from "./workflow-completeness.js";
+export { readWorkflowPolicies } from "../../core/policy/workflow-policy-store.js";
+/** Options shared by SDK, CLI and MCP policy operations. */
+export interface WorkflowPolicyActionOptions {
+    /** One policy definition for put, or proposed field values for check. */
+    definition?: unknown;
+    /** Approval declaration id. */
+    policy?: string;
+    /** Preview without registry, item, or history writes. */
+    dryRun?: boolean;
+    /** Explicit actor override; normally detected automatically. */
+    author?: string;
+    /** Rationale recorded for registry and approval mutations. */
+    message?: string;
+}
+/** Transport-neutral envelope with a discriminant for schema renderers. */
+export interface WorkflowPolicyActionResult {
+    /** Identifies this schema result without conflating type or status operations. */
+    policy_result: true;
+    /** Executed schema verb. */
+    action: WorkflowPolicyAction;
+    /** Whether durable state changed. */
+    changed: boolean;
+    /** Complete bounded result of the selected operation. */
+    result: WorkflowPolicyDocument | WorkflowPolicyEvaluation | WorkflowApprovalReceipt;
+}
+/** Content-bound approval identity returned after its history event is durable. */
+export interface WorkflowApprovalReceipt {
+    /** Reviewed item id. */
+    id: string;
+    /** Approval declaration id. */
+    policy_id: string;
+    /** Exact policy revision. */
+    policy_fingerprint: string;
+    /** Hash of reviewed content. */
+    content_fingerprint: string;
+    /** Advisory mutation diagnostics. */
+    warnings: string[];
+}
+/** Advisory defaults are opt-in data, never implicitly applied to existing projects. */
+export declare function createLifecycleCompletenessPolicies(): WorkflowPolicyDocument;
+/** Execute policy operations on every transport; policy-mode uses name as advise|refuse, validated by the registry parser. */
+export declare function runWorkflowPolicyAction(action: WorkflowPolicyAction, name: string | undefined, options?: WorkflowPolicyActionOptions, global?: Pick<GlobalOptions, "path">): Promise<WorkflowPolicyActionResult>;

package/dist/sdk/governance/workflow-policy.js

@@ -0,0 +1,4 @@
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e60a4620-c210-5d5e-baf4-d96467406cf4")}catch(e2){}})();import path from"node:path";import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{resolvePmRoot}from"../../core/store/paths.js";import{readSettings}from"../../core/store/settings.js";import{resolveAuthor}from"../../core/shared/author.js";import{PmCliError}from"../../core/shared/errors.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{mutateWorkspaceJsonWithHistory}from"../../core/history/workspace-history.js";import{locateItem,readLocatedItem,mutateItemWithHistoryContextResolver}from"../../core/store/item-store.js";import{resolveItemTypeRegistry}from"../../core/item/type-registry.js";import{getActiveExtensionRegistrations}from"../../core/extensions/index.js";import{decodeWorkflowPolicyDocument,readWorkflowPolicies,readWorkflowApprovals,evaluateWorkspacePolicies,MAX_WORKFLOW_POLICY_BYTES}from"../../core/policy/workflow-policy-store.js";import{WORKFLOW_POLICY_ACTIONS,parseWorkflowPolicy,parseWorkflowPolicyDocument,workflowPolicyFingerprint,workflowApprovalFingerprint}from"../../core/policy/workflow-policy.js";export*from"../../core/policy/workflow-policy.js";export*from"../../core/policy/workflow-policy-schema.js";import{buildWorkflowCompletenessCheck}from"./workflow-completeness.js";import{readWorkflowPolicies as readWorkflowPolicies2}from"../../core/policy/workflow-policy-store.js";function createLifecycleCompletenessPolicies(){const requiredByType=[["Epic",["goal","objective","body"]],["Story",["description","value","acceptance_criteria"]],["Decision",["body","resolution"]],["Feature",["acceptance_criteria","expected_result"]],["Task",["description"]],["Issue",["repro_steps","expected_result"]],["Chore",["description"]]];return{version:1,enforcement:"advise",policies:[...requiredByType.map(([type,fields])=>({id:`completeness-${type.toLowerCase()}`,effect:"advise",description:`Evidence expected when ${type} work reaches completion.`,subject:{types:[type],statuses:["closed"]},rule:{kind:"require_fields",fields:[...fields]}})),{id:"completeness-resolution",effect:"advise",subject:{statuses:["closed"]},rule:{kind:"require_fields",fields:["resolution","expected_result","actual_result"]}}]}}function policyInputObject(value){let parsed=value;if(typeof value==="string"){try{parsed=JSON.parse(value)}catch{throw new PmCliError("Policy definition must be valid JSON.",EXIT_CODE.USAGE)}}if(typeof parsed!=="object"||parsed===null||Array.isArray(parsed))throw new PmCliError("Policy definition must be an object.",EXIT_CODE.USAGE);return parsed}async function policyContext(global2,author){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot);return{pmRoot,settings,author:resolveAuthor(author,settings.author_default)}}function changedPolicyDocument(action,name,before,options){if(action==="policy-mode")return parseWorkflowPolicyDocument({...before,enforcement:name});const remaining=before.policies.filter(policy2=>policy2.id!==name);if(action==="policy-remove")return{...before,policies:remaining};const policy=parseWorkflowPolicy(policyInputObject(options.definition));if(policy.id!==name)throw new PmCliError("Policy definition id must match its operand.",EXIT_CODE.USAGE);const next=parseWorkflowPolicyDocument({...before,policies:[...remaining,policy].sort((left,right)=>left.id.localeCompare(right.id))});if(Buffer.byteLength(`${JSON.stringify(next,null,2)}
+`)>MAX_WORKFLOW_POLICY_BYTES)throw new PmCliError("Policy registry exceeds its byte ceiling.",EXIT_CODE.USAGE);return next}async function mutatePolicyRegistry(action,name,options,context){if(options.dryRun)return{policy_result:true,action,changed:false,result:changedPolicyDocument(action,name,await readWorkflowPolicies(context.pmRoot),options)};const mutation=await mutateWorkspaceJsonWithHistory({pmRoot:context.pmRoot,filePath:path.join(context.pmRoot,"schema","policies.json"),op:`schema:${action}`,author:context.author,message:options.message,lockTtlSeconds:context.settings.locks.ttl_seconds,lockWaitMs:context.settings.locks.wait_ms,mutate(beforeRaw){const next=changedPolicyDocument(action,name,decodeWorkflowPolicyDocument(beforeRaw),options);const raw=`${JSON.stringify(next,null,2)}
+`;return{raw,result:next}}});return{policy_result:true,action,changed:mutation.changed,result:mutation.result}}async function approvePolicy(name,options,context){let evidence;const mutation=await mutateItemWithHistoryContextResolver({...context,id:name,op:"policy_approve",message:options.message,resolveHistoryContext:()=>({workflow_approval:evidence}),async mutate(document){const registry=await readWorkflowPolicies(context.pmRoot);const policy=registry.policies.find(candidate=>candidate.id===options.policy);if(!policy||policy.rule.kind!=="approval")throw new PmCliError("--policy must name an approval rule.",EXIT_CODE.USAGE);if(!policy.rule.authors.includes(context.author))throw new PmCliError("This actor is not a declared approver.",EXIT_CODE.CONFLICT);await readWorkflowApprovals(context.pmRoot,document.metadata.id);evidence={policy_id:policy.id,policy_fingerprint:workflowPolicyFingerprint(policy),content_fingerprint:workflowApprovalFingerprint(policy,{...document.metadata,body:document.body})};return{changedFields:[]}}});return{policy_result:true,action:"policy-approve",changed:true,result:{id:mutation.item.id,...evidence,warnings:mutation.warnings}}}async function runWorkflowPolicyAction(action,name,options={},global2={}){if(!WORKFLOW_POLICY_ACTIONS.includes(action))throw new PmCliError("Unknown workflow policy action.",EXIT_CODE.USAGE);if(action==="policy-presets")return{policy_result:true,action,changed:false,result:createLifecycleCompletenessPolicies()};const context=await policyContext(global2,options.author);if(action==="policies")return{policy_result:true,action,changed:false,result:await readWorkflowPolicies(context.pmRoot)};if(!name?.trim())throw new PmCliError(`schema ${action} requires an operand.`,EXIT_CODE.USAGE);if(["policy-put","policy-remove","policy-mode"].includes(action))return mutatePolicyRegistry(action,name,options,context);if(action==="policy-approve"){if(options.dryRun)throw new PmCliError("Use policy-check to preview; policy-approve records an approval.",EXIT_CODE.USAGE);return approvePolicy(name,options,context)}const types=resolveItemTypeRegistry(context.settings,getActiveExtensionRegistrations());const located=await locateItem(context.pmRoot,name,context.settings.id_prefix,context.settings.item_format,types.type_to_folder);if(!located)throw new PmCliError(`Item ${name} not found.`,EXIT_CODE.NOT_FOUND);const{document}=await readLocatedItem(located,{schema:context.settings.schema});const before={...document.metadata,body:document.body};const after=options.definition===void 0?before:{...before,...policyInputObject(options.definition)};if(after.id!==before.id)throw new PmCliError("Policy preview cannot change the item id.",EXIT_CODE.USAGE);return{policy_result:true,action,changed:false,result:await evaluateWorkspacePolicies(context.pmRoot,await readWorkflowPolicies(context.pmRoot),{operation:"update",author:context.author,before,after,completeness_only:options.definition===void 0})}}export{buildWorkflowCompletenessCheck,createLifecycleCompletenessPolicies,readWorkflowPolicies2 as readWorkflowPolicies,runWorkflowPolicyAction};
+//# sourceMappingURL=workflow-policy.js.map

package/dist/sdk/governance/workspace-position.js

@@ -1,164 +1,2 @@
-/**
- * @module sdk/governance/workspace-position
- *
- * Produces one bounded, read-only workspace readiness answer from merge-fence,
- * merge-receipt, and append-only history evidence.
- */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e900c117-6d8d-55d3-86df-f543dc499930")}catch(e){}}();
-import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
-import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
-import { nowIso } from "../../core/shared/time.js";
-import { resolvePmRoot } from "../../core/store/paths.js";
-import { readSettings } from "../../core/store/settings.js";
-import { renderPmCommand } from "../command-line.js";
-import { assertInitializedTracker } from "../environment/tracker-preflight.js";
-import { auditMergeAttributeFence, auditMergeDriverConfiguration, findGitWorkspaceRoot, resolveProjectMergeTypeFolders, } from "../merge/install.js";
-import { inspectMergeReceiptEvidence, partitionMergeReceipts, } from "../merge/receipts.js";
-import { buildValidateHistoryDriftCheck } from "./validate-history-drift.js";
-import { readValidateItems } from "./validate-item-reader.js";
-function selectWorkspacePositionState(params) {
-    if (params.invalidEvidenceCount > 0)
-        return "merge_evidence_invalid";
-    if (!params.historyEvidenceValid)
-        return "history_evidence_invalid";
-    if (params.pendingDecisionCount > 0 || params.losslessCount > 0) {
-        return "merge_reconciliation_required";
-    }
-    if (params.driftedItemCount > 0)
-        return "history_repair_required";
-    if (params.fence.status !== "ok" ||
-        params.drivers === null ||
-        params.drivers.status !== "ok") {
-        return "merge_fence_unprepared";
-    }
-    return "ready";
-}
-function commandForWorkspacePositionState(state, pmRoot, platform = process.platform) {
-    const commandArgs = ["--pm-path", pmRoot];
-    if (state === "merge_evidence_invalid")
-        return renderPmCommand([...commandArgs, "merge", "report"], platform);
-    if (state === "history_evidence_invalid") {
-        return renderPmCommand([...commandArgs, "validate", "--check-history-drift", "--full"], platform);
-    }
-    if (state === "merge_reconciliation_required") {
-        return renderPmCommand([...commandArgs, "merge", "reconcile"], platform);
-    }
-    if (state === "history_repair_required") {
-        return renderPmCommand([...commandArgs, "history-repair", "--all"], platform);
-    }
-    if (state === "merge_fence_unprepared") {
-        return renderPmCommand([...commandArgs, "merge", "install"], platform);
-    }
-    return null;
-}
-/** Normalize defensive history-check evidence into the bounded position shape. */
-function normalizeWorkspaceHistoryDrift(details) {
-    const driftedItemIds = Array.isArray(details.drifted_items)
-        ? details.drifted_items.filter((entry) => typeof entry === "string")
-        : [];
-    const evidenceValid = Array.isArray(details.drifted_items) &&
-        details.drifted_items.every((entry) => typeof entry === "string") &&
-        typeof details.drifted_items_count === "number" &&
-        Number.isInteger(details.drifted_items_count) &&
-        details.drifted_items_count >= 0 &&
-        typeof details.drifted_items_truncated === "boolean" &&
-        typeof details.counts === "object" &&
-        details.counts !== null &&
-        !Array.isArray(details.counts);
-    return {
-        evidence_valid: evidenceValid,
-        drifted_item_count: typeof details.drifted_items_count === "number"
-            ? details.drifted_items_count
-            : driftedItemIds.length,
-        drifted_item_ids: driftedItemIds,
-        drifted_item_ids_truncated: details.drifted_items_truncated === true,
-        counts: typeof details.counts === "object" && details.counts !== null
-            ? details.counts
-            : {},
-    };
-}
-/** Read aggregate workspace position without flags, session state, or mutation. */
-export async function readWorkspacePosition(global) {
-    const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    await assertInitializedTracker(pmRoot);
-    const settings = await readSettings(pmRoot);
-    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
-    const itemReadWarnings = [];
-    const items = await readValidateItems({
-        includeBody: true,
-        pmRoot,
-        settings,
-        typeToFolder: typeRegistry.type_to_folder,
-        warnings: itemReadWarnings,
-    });
-    const gitWorkspaceRoot = await findGitWorkspaceRoot(pmRoot);
-    const [fence, drivers, receiptEvidence, drift] = await Promise.all([
-        auditMergeAttributeFence(pmRoot, resolveProjectMergeTypeFolders(settings)),
-        gitWorkspaceRoot === null
-            ? Promise.resolve(null)
-            : auditMergeDriverConfiguration(gitWorkspaceRoot),
-        inspectMergeReceiptEvidence(gitWorkspaceRoot ?? pmRoot, {
-            includeLossless: true,
-            pmRoot,
-        }),
-        buildValidateHistoryDriftCheck(pmRoot, items, false),
-    ]);
-    const { pendingDecisions, lossless } = partitionMergeReceipts(receiptEvidence.receipts);
-    const pendingItemIds = [
-        ...new Set(pendingDecisions.map((receipt) => receipt.item_id)),
-    ].sort((left, right) => left.localeCompare(right));
-    const driftDetails = drift.check.details;
-    const historyDrift = normalizeWorkspaceHistoryDrift(driftDetails);
-    const state = selectWorkspacePositionState({
-        invalidEvidenceCount: receiptEvidence.invalid_evidence_count,
-        pendingDecisionCount: pendingDecisions.length,
-        losslessCount: lossless.length,
-        historyEvidenceValid: historyDrift.evidence_valid,
-        driftedItemCount: historyDrift.drifted_item_count,
-        fence,
-        drivers,
-    });
-    return {
-        ok: state === "ready",
-        state,
-        merge_fence: {
-            committed: fence,
-            clone_local_drivers: drivers,
-        },
-        merge_receipts: {
-            pending_decision_count: pendingDecisions.length,
-            pending_item_ids: pendingItemIds.slice(0, 25),
-            pending_item_ids_truncated: pendingItemIds.length > 25,
-            lossless_count: lossless.length,
-            invalid_evidence_count: receiptEvidence.invalid_evidence_count,
-        },
-        history_drift: historyDrift,
-        next_action: {
-            command: commandForWorkspacePositionState(state, pmRoot),
-            reason: state,
-        },
-        warnings: [...new Set(itemReadWarnings)].sort((left, right) => left.localeCompare(right)),
-        generated_at: nowIso(),
-    };
-}
-/** Render the bounded workspace position for human CLI output. */
-export function formatWorkspacePositionHuman(result) {
-    const action = result.next_action.command ?? "none";
-    return [
-        `workspace_position: ${result.state}`,
-        `merge_fence: ${result.merge_fence.committed.status}`,
-        `clone_local_drivers: ${result.merge_fence.clone_local_drivers?.status ?? "unavailable"}`,
-        `pending_merge_decisions: ${result.merge_receipts.pending_decision_count}`,
-        `history_drifted_items: ${result.history_drift.drifted_item_count}`,
-        `next_action: ${action}`,
-    ].join("\n");
-}
-/** Public contract for focused unit verification. */
-export const _testOnlyWorkspacePosition = {
-    commandForWorkspacePositionState,
-    normalizeWorkspaceHistoryDrift,
-    selectWorkspacePositionState,
-};
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="48abeea1-703c-57e9-9d99-787cb2829efb")}catch(e2){}})();import{getActiveExtensionRegistrations}from"../../core/extensions/index.js";import{resolveItemTypeRegistry}from"../../core/item/type-registry.js";import{nowIso}from"../../core/shared/time.js";import{resolvePmRoot}from"../../core/store/paths.js";import{readSettings}from"../../core/store/settings.js";import{renderPmCommand}from"../command-line.js";import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{auditMergeAttributeFence,auditMergeDriverConfiguration,findGitWorkspaceRoot,resolveProjectMergeTypeFolders}from"../merge/install.js";import{inspectMergeReceiptEvidence,partitionMergeReceipts}from"../merge/receipts.js";import{buildValidateHistoryDriftCheck}from"./validate-history-drift.js";import{readValidateItems}from"./validate-item-reader.js";function selectWorkspacePositionState(params){if(params.invalidEvidenceCount>0)return"merge_evidence_invalid";if(!params.historyEvidenceValid)return"history_evidence_invalid";if(params.pendingDecisionCount>0||params.losslessCount>0){return"merge_reconciliation_required"}if(params.driftedItemCount>0)return"history_repair_required";if(params.fence.status!=="ok"||params.drivers===null||params.drivers.status!=="ok"){return"merge_fence_unprepared"}return"ready"}function commandForWorkspacePositionState(state,pmRoot,platform=process.platform){const commandArgs=["--pm-path",pmRoot];if(state==="merge_evidence_invalid")return renderPmCommand([...commandArgs,"merge","report"],platform);if(state==="history_evidence_invalid"){return renderPmCommand([...commandArgs,"validate","--check-history-drift","--full"],platform)}if(state==="merge_reconciliation_required"){return renderPmCommand([...commandArgs,"merge","reconcile"],platform)}if(state==="history_repair_required"){return renderPmCommand([...commandArgs,"history-repair","--all"],platform)}if(state==="merge_fence_unprepared"){return renderPmCommand([...commandArgs,"merge","install"],platform)}return null}function normalizeWorkspaceHistoryDrift(details){const driftedItemIds=Array.isArray(details.drifted_items)?details.drifted_items.filter(entry=>typeof entry==="string"):[];const evidenceValid=Array.isArray(details.drifted_items)&&details.drifted_items.every(entry=>typeof entry==="string")&&typeof details.drifted_items_count==="number"&&Number.isInteger(details.drifted_items_count)&&details.drifted_items_count>=0&&typeof details.drifted_items_truncated==="boolean"&&typeof details.counts==="object"&&details.counts!==null&&!Array.isArray(details.counts);return{evidence_valid:evidenceValid,drifted_item_count:typeof details.drifted_items_count==="number"?details.drifted_items_count:driftedItemIds.length,drifted_item_ids:driftedItemIds,drifted_item_ids_truncated:details.drifted_items_truncated===true,counts:typeof details.counts==="object"&&details.counts!==null?details.counts:{}}}async function readWorkspacePosition(global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot);const typeRegistry=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations());const itemReadWarnings=[];const items=await readValidateItems({includeBody:true,pmRoot,settings,typeToFolder:typeRegistry.type_to_folder,warnings:itemReadWarnings});const gitWorkspaceRoot=await findGitWorkspaceRoot(pmRoot);const[fence,drivers,receiptEvidence,drift]=await Promise.all([auditMergeAttributeFence(pmRoot,resolveProjectMergeTypeFolders(settings)),gitWorkspaceRoot===null?Promise.resolve(null):auditMergeDriverConfiguration(gitWorkspaceRoot),inspectMergeReceiptEvidence(gitWorkspaceRoot??pmRoot,{includeLossless:true,pmRoot}),buildValidateHistoryDriftCheck(pmRoot,items,false)]);const{pendingDecisions,lossless}=partitionMergeReceipts(receiptEvidence.receipts);const pendingItemIds=[...new Set(pendingDecisions.map(receipt=>receipt.item_id))].sort((left,right)=>left.localeCompare(right));const driftDetails=drift.check.details;const historyDrift=normalizeWorkspaceHistoryDrift(driftDetails);const state=selectWorkspacePositionState({invalidEvidenceCount:receiptEvidence.invalid_evidence_count,pendingDecisionCount:pendingDecisions.length,losslessCount:lossless.length,historyEvidenceValid:historyDrift.evidence_valid,driftedItemCount:historyDrift.drifted_item_count,fence,drivers});return{ok:state==="ready",state,merge_fence:{committed:fence,clone_local_drivers:drivers},merge_receipts:{pending_decision_count:pendingDecisions.length,pending_item_ids:pendingItemIds.slice(0,25),pending_item_ids_truncated:pendingItemIds.length>25,lossless_count:lossless.length,invalid_evidence_count:receiptEvidence.invalid_evidence_count},history_drift:historyDrift,next_action:{command:commandForWorkspacePositionState(state,pmRoot),reason:state},warnings:[...new Set(itemReadWarnings)].sort((left,right)=>left.localeCompare(right)),generated_at:nowIso()}}function formatWorkspacePositionHuman(result){const action=result.next_action.command??"none";return[`workspace_position: ${result.state}`,`merge_fence: ${result.merge_fence.committed.status}`,`clone_local_drivers: ${result.merge_fence.clone_local_drivers?.status??"unavailable"}`,`pending_merge_decisions: ${result.merge_receipts.pending_decision_count}`,`history_drifted_items: ${result.history_drift.drifted_item_count}`,`next_action: ${action}`].join("\n")}const _testOnlyWorkspacePosition={commandForWorkspacePositionState,normalizeWorkspaceHistoryDrift,selectWorkspacePositionState};export{_testOnlyWorkspacePosition,formatWorkspacePositionHuman,readWorkspacePosition};
 //# sourceMappingURL=workspace-position.js.map
-//# debugId=e900c117-6d8d-55d3-86df-f543dc499930

package/dist/sdk/governance.d.ts

@@ -19,6 +19,7 @@ export * from "./governance/stale-work.js";
 export * from "./governance/storage-integrity.js";
 export * from "./governance/status-role-diagnostics.js";
 export * from "./governance/workspace-position.js";
+export * from "./governance/workflow-policy.js";
 export { runUpgrade, type UpgradeCliResult, type UpgradeCommandOptions, type UpgradeCommandRunner, type UpgradeCommandRunnerResult, type UpgradePackageResult, type UpgradeResult, } from "./governance/upgrade.js";
 export * from "./governance/validate.js";
 export * from "./governance/linked-file-report.js";
@@ -26,3 +27,4 @@ export * from "./author-attribution.js";
 export * from "./mutation-guard.js";
 export * from "./governance/provenance-health.js";
 export * from "./similarity.js";
+export * from "./history/maintenance.js";

package/dist/sdk/governance.js

@@ -1,32 +1,2 @@
-/**
- * @module sdk/governance
- *
- * Provides validation, health, integrity, and mutation-policy primitives.
- */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5e2aaa83-a109-5e44-b9b3-316501ffadf4")}catch(e){}}();
-export * from "./governance/gc.js";
-export * from "./governance/health.js";
-export * from "./governance/extension-host-version.js";
-export * from "./governance/assurance.js";
-export * from "./governance/assurance-action.js";
-export * from "./governance/assurance-mutation-error.js";
-export * from "./governance/assurance-presets.js";
-export * from "./governance/assurance-runtime.js";
-export * from "./governance/boundary-fixtures.js";
-export * from "./governance/defect-recurrence.js";
-export * from "./governance/defect-recurrence-coverage.js";
-export { runReindex, } from "./governance/reindex.js";
-export * from "./governance/stale-work.js";
-export * from "./governance/storage-integrity.js";
-export * from "./governance/status-role-diagnostics.js";
-export * from "./governance/workspace-position.js";
-export { runUpgrade, } from "./governance/upgrade.js";
-export * from "./governance/validate.js";
-export * from "./governance/linked-file-report.js";
-export * from "./author-attribution.js";
-export * from "./mutation-guard.js";
-export * from "./governance/provenance-health.js";
-export * from "./similarity.js";
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="db5452b6-8d36-5425-a033-1d36757ce96e")}catch(e2){}})();export*from"./governance/gc.js";export*from"./governance/health.js";export*from"./governance/extension-host-version.js";export*from"./governance/assurance.js";export*from"./governance/assurance-action.js";export*from"./governance/assurance-mutation-error.js";export*from"./governance/assurance-presets.js";export*from"./governance/assurance-runtime.js";export*from"./governance/boundary-fixtures.js";export*from"./governance/defect-recurrence.js";export*from"./governance/defect-recurrence-coverage.js";import{runReindex}from"./governance/reindex.js";export*from"./governance/stale-work.js";export*from"./governance/storage-integrity.js";export*from"./governance/status-role-diagnostics.js";export*from"./governance/workspace-position.js";export*from"./governance/workflow-policy.js";import{runUpgrade}from"./governance/upgrade.js";export*from"./governance/validate.js";export*from"./governance/linked-file-report.js";export*from"./author-attribution.js";export*from"./mutation-guard.js";export*from"./governance/provenance-health.js";export*from"./similarity.js";export*from"./history/maintenance.js";export{runReindex,runUpgrade};
 //# sourceMappingURL=governance.js.map
-//# debugId=5e2aaa83-a109-5e44-b9b3-316501ffadf4

package/dist/sdk/graph/adapter.js

@@ -1,182 +1,2 @@
-/**
- * @module sdk/graph/adapter
- *
- * Portable relationship-graph snapshots and a storage-neutral adapter
- * protocol for package-owned databases, replicated logs, and remote graph
- * services. Snapshots are immutable, content-addressed, and validated through
- * the same registry and graph kernel as native pm queries.
- */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4586a8b2-07c8-53d4-9c5d-ca557ee07977")}catch(e){}}();
-import { createHash } from "node:crypto";
-import { stableStringify } from "../../core/shared/serialization.js";
-import { RelationshipGraph, RelationshipKindRegistry, } from "../relationships.js";
-/** Current portable relationship-graph snapshot format. */
-export const RELATIONSHIP_GRAPH_SNAPSHOT_VERSION = 1;
-/** Throw when cooperative cancellation has already been requested. */
-function throwIfAborted(signal) {
-    signal?.throwIfAborted();
-}
-/** Validate one non-empty adapter/workspace identifier. */
-function requireText(value, field) {
-    if (typeof value !== "string" || value.trim().length === 0)
-        throw new TypeError(`Relationship graph ${field} must be non-empty`);
-    return value.trim();
-}
-/** Build an immutable portable snapshot from a validated graph and registry. */
-export function createRelationshipGraphSnapshot(graph, registry, options = {}) {
-    const parsedTimestamp = Date.parse(options.createdAt ?? new Date().toISOString());
-    if (!Number.isFinite(parsedTimestamp))
-        throw new TypeError("Relationship graph createdAt must be a valid timestamp");
-    const nodes = graph.nodes();
-    const edges = graph.edges();
-    const kinds = registry.list();
-    return Object.freeze({
-        version: RELATIONSHIP_GRAPH_SNAPSHOT_VERSION,
-        fingerprint: createHash("sha256")
-            .update(stableStringify({ nodes, edges, kinds }))
-            .digest("hex"),
-        created_at: new Date(parsedTimestamp).toISOString(),
-        nodes,
-        edges,
-        kinds,
-    });
-}
-/** Return whether a decoded value is a plain property-bearing object. */
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** Decode and fully validate a portable graph snapshot. */
-export function parseRelationshipGraphSnapshot(value) {
-    if (!isRecord(value))
-        throw new TypeError("Relationship graph snapshot must be an object");
-    if (value.version !== RELATIONSHIP_GRAPH_SNAPSHOT_VERSION)
-        throw new TypeError(`Unsupported relationship graph snapshot version: ${String(value.version)}`);
-    if (!Array.isArray(value.nodes) ||
-        value.nodes.some((id) => typeof id !== "string"))
-        throw new TypeError("Relationship graph snapshot nodes must be strings");
-    if (!Array.isArray(value.edges) || !Array.isArray(value.kinds))
-        throw new TypeError("Relationship graph snapshot edges and kinds must be arrays");
-    if (typeof value.created_at !== "string" ||
-        !Number.isFinite(Date.parse(value.created_at)))
-        throw new TypeError("Relationship graph snapshot created_at must be valid");
-    if (typeof value.fingerprint !== "string")
-        throw new TypeError("Relationship graph snapshot fingerprint must be a string");
-    const registry = new RelationshipKindRegistry([]);
-    for (const definition of value.kinds)
-        registry.register(definition);
-    const graph = new RelationshipGraph(value.nodes, value.edges, registry);
-    const snapshot = createRelationshipGraphSnapshot(graph, registry, {
-        createdAt: value.created_at,
-    });
-    if (snapshot.fingerprint !== value.fingerprint)
-        throw new TypeError("Relationship graph snapshot fingerprint mismatch");
-    return { snapshot, registry, graph };
-}
-/** Read and validate one adapter workspace. */
-export async function loadRelationshipGraphAdapter(adapter, context) {
-    requireText(adapter.name, "adapter name");
-    const workspace = requireText(context.workspace, "workspace");
-    throwIfAborted(context.signal);
-    const value = await adapter.read({ ...context, workspace });
-    throwIfAborted(context.signal);
-    return value === null ? null : parseRelationshipGraphSnapshot(value);
-}
-/**
- * Synchronize a complete graph snapshot with compare-and-swap protection and
- * verify the adapter's visible read after replacement.
- */
-export async function syncRelationshipGraphAdapter(adapter, context) {
-    const workspace = requireText(context.workspace, "workspace");
-    const validated = parseRelationshipGraphSnapshot(context.snapshot).snapshot;
-    const current = await loadRelationshipGraphAdapter(adapter, {
-        workspace,
-        signal: context.signal,
-    });
-    if (current?.snapshot.fingerprint === validated.fingerprint)
-        return {
-            adapter: adapter.name,
-            workspace,
-            disposition: "current",
-            fingerprint: validated.fingerprint,
-            previous_fingerprint: current.snapshot.fingerprint,
-            node_count: validated.nodes.length,
-            edge_count: validated.edges.length,
-        };
-    throwIfAborted(context.signal);
-    await adapter.replace({
-        workspace,
-        signal: context.signal,
-        snapshot: validated,
-        expected_fingerprint: current?.snapshot.fingerprint ?? null,
-    });
-    const visible = await loadRelationshipGraphAdapter(adapter, {
-        workspace,
-        signal: context.signal,
-    });
-    if (visible?.snapshot.fingerprint !== validated.fingerprint)
-        throw new Error(`Relationship graph adapter "${adapter.name}" did not expose the replaced snapshot`);
-    return {
-        adapter: adapter.name,
-        workspace,
-        disposition: "written",
-        fingerprint: validated.fingerprint,
-        ...(current ? { previous_fingerprint: current.snapshot.fingerprint } : {}),
-        node_count: validated.nodes.length,
-        edge_count: validated.edges.length,
-    };
-}
-/** Merge portable snapshots while rejecting semantic kind collisions. */
-export function federateRelationshipGraphSnapshots(values, options = {}) {
-    const loaded = values.map(parseRelationshipGraphSnapshot);
-    const definitions = new Map();
-    for (const entry of loaded) {
-        for (const definition of entry.snapshot.kinds) {
-            const prior = definitions.get(definition.kind);
-            if (prior && stableStringify(prior) !== stableStringify(definition))
-                throw new TypeError(`Conflicting federated relationship kind: ${definition.kind}`);
-            definitions.set(definition.kind, definition);
-        }
-    }
-    const registry = new RelationshipKindRegistry([...definitions.values()].sort((left, right) => left.kind.localeCompare(right.kind)));
-    const graph = new RelationshipGraph(new Set(loaded.flatMap((entry) => [...entry.snapshot.nodes])), loaded.flatMap((entry) => [...entry.snapshot.edges]), registry);
-    return createRelationshipGraphSnapshot(graph, registry, options);
-}
-/** In-memory reference adapter with atomic CAS behavior for tests and packages. */
-export class MemoryRelationshipGraphAdapter {
-    /** Stable adapter identifier used in diagnostics and conformance reports. */
-    name;
-    #snapshots = new Map();
-    /** Create a reference adapter with a stable diagnostic name. */
-    constructor(name = "memory") {
-        this.name = requireText(name, "adapter name");
-    }
-    /** Read an isolated clone of the current workspace snapshot. */
-    async read(context) {
-        throwIfAborted(context.signal);
-        const snapshot = this.#snapshots.get(requireText(context.workspace, "workspace"));
-        return snapshot ? structuredClone(snapshot) : null;
-    }
-    /** Atomically replace one workspace after enforcing its expected fingerprint. */
-    async replace(context) {
-        throwIfAborted(context.signal);
-        const workspace = requireText(context.workspace, "workspace");
-        const current = this.#snapshots.get(workspace);
-        if (context.expected_fingerprint !== undefined &&
-            (current?.fingerprint ?? null) !== context.expected_fingerprint)
-            throw new Error(`Relationship graph adapter conflict for ${workspace}`);
-        this.#snapshots.set(workspace, structuredClone(parseRelationshipGraphSnapshot(context.snapshot).snapshot));
-    }
-    /** Clear one workspace after enforcing its expected fingerprint. */
-    async clear(context) {
-        throwIfAborted(context.signal);
-        const workspace = requireText(context.workspace, "workspace");
-        const current = this.#snapshots.get(workspace);
-        if (context.expected_fingerprint !== undefined &&
-            (current?.fingerprint ?? null) !== context.expected_fingerprint)
-            throw new Error(`Relationship graph adapter conflict for ${workspace}`);
-        this.#snapshots.delete(workspace);
-    }
-}
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="eb475dcd-d16c-51fb-b248-b14cf5ade4de")}catch(e2){}})();import{createHash}from"node:crypto";import{stableStringify}from"../../core/shared/serialization.js";import{RelationshipGraph,RelationshipKindRegistry}from"../relationships.js";const RELATIONSHIP_GRAPH_SNAPSHOT_VERSION=1;function throwIfAborted(signal){signal?.throwIfAborted()}function requireText(value,field){if(typeof value!=="string"||value.trim().length===0)throw new TypeError(`Relationship graph ${field} must be non-empty`);return value.trim()}function createRelationshipGraphSnapshot(graph,registry,options={}){const parsedTimestamp=Date.parse(options.createdAt??new Date().toISOString());if(!Number.isFinite(parsedTimestamp))throw new TypeError("Relationship graph createdAt must be a valid timestamp");const nodes=graph.nodes();const edges=graph.edges();const kinds=registry.list();return Object.freeze({version:RELATIONSHIP_GRAPH_SNAPSHOT_VERSION,fingerprint:createHash("sha256").update(stableStringify({nodes,edges,kinds})).digest("hex"),created_at:new Date(parsedTimestamp).toISOString(),nodes,edges,kinds})}function isRecord(value){return typeof value==="object"&&value!==null&&!Array.isArray(value)}function parseRelationshipGraphSnapshot(value){if(!isRecord(value))throw new TypeError("Relationship graph snapshot must be an object");if(value.version!==RELATIONSHIP_GRAPH_SNAPSHOT_VERSION)throw new TypeError(`Unsupported relationship graph snapshot version: ${String(value.version)}`);if(!Array.isArray(value.nodes)||value.nodes.some(id=>typeof id!=="string"))throw new TypeError("Relationship graph snapshot nodes must be strings");if(!Array.isArray(value.edges)||!Array.isArray(value.kinds))throw new TypeError("Relationship graph snapshot edges and kinds must be arrays");if(typeof value.created_at!=="string"||!Number.isFinite(Date.parse(value.created_at)))throw new TypeError("Relationship graph snapshot created_at must be valid");if(typeof value.fingerprint!=="string")throw new TypeError("Relationship graph snapshot fingerprint must be a string");const registry=new RelationshipKindRegistry([]);for(const definition of value.kinds)registry.register(definition);const graph=new RelationshipGraph(value.nodes,value.edges,registry);const snapshot=createRelationshipGraphSnapshot(graph,registry,{createdAt:value.created_at});if(snapshot.fingerprint!==value.fingerprint)throw new TypeError("Relationship graph snapshot fingerprint mismatch");return{snapshot,registry,graph}}async function loadRelationshipGraphAdapter(adapter,context){requireText(adapter.name,"adapter name");const workspace=requireText(context.workspace,"workspace");throwIfAborted(context.signal);const value=await adapter.read({...context,workspace});throwIfAborted(context.signal);return value===null?null:parseRelationshipGraphSnapshot(value)}async function syncRelationshipGraphAdapter(adapter,context){const workspace=requireText(context.workspace,"workspace");const validated=parseRelationshipGraphSnapshot(context.snapshot).snapshot;const current=await loadRelationshipGraphAdapter(adapter,{workspace,signal:context.signal});if(current?.snapshot.fingerprint===validated.fingerprint)return{adapter:adapter.name,workspace,disposition:"current",fingerprint:validated.fingerprint,previous_fingerprint:current.snapshot.fingerprint,node_count:validated.nodes.length,edge_count:validated.edges.length};throwIfAborted(context.signal);await adapter.replace({workspace,signal:context.signal,snapshot:validated,expected_fingerprint:current?.snapshot.fingerprint??null});const visible=await loadRelationshipGraphAdapter(adapter,{workspace,signal:context.signal});if(visible?.snapshot.fingerprint!==validated.fingerprint)throw new Error(`Relationship graph adapter "${adapter.name}" did not expose the replaced snapshot`);return{adapter:adapter.name,workspace,disposition:"written",fingerprint:validated.fingerprint,...current?{previous_fingerprint:current.snapshot.fingerprint}:{},node_count:validated.nodes.length,edge_count:validated.edges.length}}function federateRelationshipGraphSnapshots(values,options={}){const loaded=values.map(parseRelationshipGraphSnapshot);const definitions=new Map;for(const entry of loaded){for(const definition of entry.snapshot.kinds){const prior=definitions.get(definition.kind);if(prior&&stableStringify(prior)!==stableStringify(definition))throw new TypeError(`Conflicting federated relationship kind: ${definition.kind}`);definitions.set(definition.kind,definition)}}const registry=new RelationshipKindRegistry([...definitions.values()].sort((left,right)=>left.kind.localeCompare(right.kind)));const graph=new RelationshipGraph(new Set(loaded.flatMap(entry=>[...entry.snapshot.nodes])),loaded.flatMap(entry=>[...entry.snapshot.edges]),registry);return createRelationshipGraphSnapshot(graph,registry,options)}class MemoryRelationshipGraphAdapter{name;#snapshots=new Map;constructor(name="memory"){this.name=requireText(name,"adapter name")}async read(context){throwIfAborted(context.signal);const snapshot=this.#snapshots.get(requireText(context.workspace,"workspace"));return snapshot?structuredClone(snapshot):null}async replace(context){throwIfAborted(context.signal);const workspace=requireText(context.workspace,"workspace");const current=this.#snapshots.get(workspace);if(context.expected_fingerprint!==void 0&&(current?.fingerprint??null)!==context.expected_fingerprint)throw new Error(`Relationship graph adapter conflict for ${workspace}`);this.#snapshots.set(workspace,structuredClone(parseRelationshipGraphSnapshot(context.snapshot).snapshot))}async clear(context){throwIfAborted(context.signal);const workspace=requireText(context.workspace,"workspace");const current=this.#snapshots.get(workspace);if(context.expected_fingerprint!==void 0&&(current?.fingerprint??null)!==context.expected_fingerprint)throw new Error(`Relationship graph adapter conflict for ${workspace}`);this.#snapshots.delete(workspace)}}export{MemoryRelationshipGraphAdapter,RELATIONSHIP_GRAPH_SNAPSHOT_VERSION,createRelationshipGraphSnapshot,federateRelationshipGraphSnapshots,loadRelationshipGraphAdapter,parseRelationshipGraphSnapshot,syncRelationshipGraphAdapter};
 //# sourceMappingURL=adapter.js.map
-//# debugId=4586a8b2-07c8-53d4-9c5d-ca557ee07977