@unbrained/pm-cli 2026.10.14 → 2026.10.17

package/dist/sdk/lifecycle/claim.d.ts

@@ -1,97 +1,111 @@
 import { type GlobalOptions } from "../runtime-primitives.js";
-import { type NextRecommendation, type NextOptions } from "../query/next.js";
+import { type NextRecommendation,type NextOptions } from "../query/next.js";
 /** Stable warning/error code for an exhausted atomic next-work walk. */
 export declare const NO_AVAILABLE_NEXT_ITEM_CODE = "no_available_next_item";
 /** Documents the claim result payload exchanged by command, SDK, and package integrations. */
 export interface ClaimResult {
 /** Value that configures or reports item for this contract. */
-item: Record<string, unknown>;
+item:Record<string,unknown>;
 /** Metadata fields changed by this claim; empty for an idempotent or skipped claim. */
-changed_fields?: string[];
+changed_fields?:string[];
 /** Value that configures or reports claimed by for this contract. */
-claimed_by: string;
+claimed_by:string;
 /** Value that configures or reports previous assignee for this contract. */
-previous_assignee: string | null;
+previous_assignee:string | null;
 /** Value that configures or reports forced for this contract. */
-forced: boolean;
+forced:boolean;
 /** Value that configures or reports skipped for this contract. */
-skipped?: boolean;
+skipped?:boolean;
 /** Value that configures or reports warnings for this contract. */
-warnings?: string[];
+warnings?:string[];
 }
 /** Result of atomically selecting and claiming the next caller-available item. */
 export interface ClaimNextAvailableResult extends ClaimResult {
 /** True when an actionable candidate was claimed. */
-available: true;
+available:true;
 /** Value that configures or reports recommendation for this contract. */
-recommendation: NextRecommendation;
+recommendation:NextRecommendation;
 /** Value that configures or reports attempts for this contract. */
-attempts: number;
+attempts:number;
 }
 /** Non-error empty result returned when an if-available candidate walk is exhausted. */
 export interface ClaimNextUnavailableResult {
 /** Indicates that no candidate remained claimable. */
-available: false;
+available:false;
 /** Empty item projection for a deliberately unavailable selection. */
-item: null;
+item:null;
 /** Caller identity that attempted the selection. */
-claimed_by: string;
+claimed_by:string;
 /** No previous owner exists for an empty selection. */
-previous_assignee: null;
+previous_assignee:null;
 /** Whether forced selection was requested. */
-forced: boolean;
+forced:boolean;
 /** Signals a deliberate non-error skip. */
-skipped: true;
+skipped:true;
 /** No recommendation survived the bounded walk. */
-recommendation: null;
+recommendation:null;
 /** Number of ranked candidates attempted. */
-attempts: number;
+attempts:number;
 /** Stable machine-readable exhaustion warning. */
-warnings: [typeof NO_AVAILABLE_NEXT_ITEM_CODE];
+warnings:[typeof NO_AVAILABLE_NEXT_ITEM_CODE];
 }
 /** Result of a successful or deliberately empty atomic next-work claim. */
 export type ClaimNextResult = ClaimNextAvailableResult | ClaimNextUnavailableResult;
 /** Returns whether a failed claim lost the atomic test-and-set race. */
-export declare function isAlreadyClaimedError(error: unknown): boolean;
-type ClaimRunner = (id: string, force: boolean, global: GlobalOptions, options: ClaimMutationOptions) => Promise<ClaimResult>;
+export declare function isAlreadyClaimedError(error:unknown):boolean;
+type ClaimRunner = (id:string,force:boolean,global:GlobalOptions,options:ClaimMutationOptions) => Promise<ClaimResult>;
 /** Documents the release result payload exchanged by command, SDK, and package integrations. */
 export interface ReleaseResult {
 /** Value that configures or reports item for this contract. */
-item: Record<string, unknown>;
+item:Record<string,unknown>;
 /** Ownership fields actually removed, or an empty list for an unclaimed item. */
-changed_fields?: string[];
+changed_fields?:string[];
 /** Value that configures or reports released by for this contract. */
-released_by: string;
+released_by:string;
 /** Value that configures or reports previous assignee for this contract. */
-previous_assignee: string | null;
+previous_assignee:string | null;
 /** Value that configures or reports forced for this contract. */
-forced: boolean;
+forced:boolean;
 /** Stable handoff diagnostics shared by CLI and MCP consumers. */
-warnings?: string[];
+warnings?:string[];
 /** Concrete recovery commands when releasing ownership leaves work in progress. */
-suggestions?: string[];
+suggestions?:string[];
+/** Evidence and queue transition recorded with the ownership release. */
+handoff?:{
+/** Lifecycle status observed under the item lock. */
+from_status:string;
+/** Project-defined queue receiving the unclaimed work. */
+to_status:string;
+/** Author-supplied evidence retained in the release history event. */
+message:string;
+};
 }
 /** Documents the claim mutation options payload exchanged by command, SDK, and package integrations. */
 export interface ClaimMutationOptions {
 /** Value that configures or reports author for this contract. */
-author?: string;
+author?:string;
 /** Human-readable explanation suitable for logs and agent-facing output. */
-message?: string;
+message?:string;
 /** Value that configures or reports if available for this contract. */
-ifAvailable?: boolean;
+ifAvailable?:boolean;
 /** Maximum ranked candidates attempted by `claim --next`. */
-maxAttempts?: string | number;
+maxAttempts?:string | number;
 }
 /** Documents the release mutation options payload exchanged by command, SDK, and package integrations. */
-export type ReleaseMutationOptions = ClaimMutationOptions;
+export interface ReleaseMutationOptions extends ClaimMutationOptions {
+/** Configured non-terminal queue to enter atomically with release. */
+handoff?:string;
+/** Pause composition, mutually exclusive with a handoff queue. */
+pause?:boolean;
+}
 /** Implements run claim for the public runtime surface of this module. */
-export declare function runClaim(id: string, force: boolean, global: GlobalOptions, options?: ClaimMutationOptions): Promise<ClaimResult>;
+export declare function runClaim(id:string,force:boolean,global:GlobalOptions,options?:ClaimMutationOptions):Promise<ClaimResult>;
 /** Selects ranked actionable work and claims the first candidate still available under the item lock. Conflicts caused by parallel claimers advance to the next candidate instead of returning a thundering-herd failure. */
-export declare function runClaimNext(force: boolean, global: GlobalOptions, options?: ClaimMutationOptions, nextOptions?: NextOptions): Promise<ClaimNextResult>;
+export declare function runClaimNext(force:boolean,global:GlobalOptions,options?:ClaimMutationOptions,nextOptions?:NextOptions):Promise<ClaimNextResult>;
 /** Parses the bounded candidate walk used by `claim --next`. */
-export declare function parseClaimNextAttempts(raw: string | number | undefined): number;
+export declare function parseClaimNextAttempts(raw:string | number | undefined):number;
 /** Claims the first still-available row from a pre-ranked recommendation set. */
-export declare function claimNextFromRecommendations(recommendations: NextRecommendation[], force: boolean, global: GlobalOptions, options?: ClaimMutationOptions, claimRunner?: ClaimRunner): Promise<ClaimNextResult>;
+export declare function claimNextFromRecommendations(recommendations:NextRecommendation[],force:boolean,global:GlobalOptions,options?:ClaimMutationOptions,claimRunner?:ClaimRunner):Promise<ClaimNextResult>;
 /** Implements run release for the public runtime surface of this module. */
-export declare function runRelease(id: string, force: boolean, global: GlobalOptions, options?: ReleaseMutationOptions): Promise<ReleaseResult>;
+export declare function runRelease(id:string,force:boolean,global:GlobalOptions,options?:ReleaseMutationOptions):Promise<ReleaseResult>;
 export {};

package/dist/sdk/lifecycle/claim.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ce03100c-3a4f-5ce4-a216-a3fabcfc655e")}catch{}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{resolveRuntimeStatusRegistry,statusIsTerminal,EXIT_CODE,PmCliError,toItemRecord,mutateItem,resolvePmRoot,readSettings,resolveAuthor,resolveClaimPrincipal,normalizeStatusForRegistry}from"../runtime-primitives.js";import{wrapOwnershipConflict}from"../annotations.js";import{describeItemOwnershipConflict}from"../ownership-source.js";import{runNext}from"../query/next.js";import{recordClaimSemanticAttribution,recordReleaseSemanticAttribution}from"../context/semantic-session-attribution.js";const NO_AVAILABLE_NEXT_ITEM_CODE="no_available_next_item";function isAlreadyClaimedError(error){if(!(error instanceof Error)||error.name!=="PmCliError")return!1;const context=error.context;return typeof context=="object"&&context!==null&&"code"in context&&context.code==="already_claimed_by"}async function runClaim(id,force,global2,options={}){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),statusRegistry=resolveRuntimeStatusRegistry(settings.schema),author=resolveAuthor(options.author,settings.author_default),claimPrincipal=resolveClaimPrincipal(author);let previousAssignee=null,skipped=!1;const mutationWarnings=[],result=await mutateItem({pmRoot,settings,id,op:"claim",author,message:options.message,force,skipNoop:!0,async mutate(document){const currentAssigneeText=document.metadata.assignee??"",currentClaimPrincipal=document.metadata.claim_principal?.trim()||currentAssigneeText;if(previousAssignee=currentAssigneeText.trim().length>0?currentAssigneeText:null,statusIsTerminal(document.metadata.status,statusRegistry)&&!force)throw new PmCliError(`Cannot claim terminal item ${document.metadata.id} without --force`,EXIT_CODE.CONFLICT);if(previousAssignee!==null&&currentClaimPrincipal!==claimPrincipal){if(options.ifAvailable===!0)return skipped=!0,mutationWarnings.push(`claim_skipped_held_by:${previousAssignee}`),{changedFields:[]};if(!force){const ownershipPhrase=await describeItemOwnershipConflict(pmRoot,document.metadata.id,currentAssigneeText);throw new PmCliError(`Item ${document.metadata.id} is already ${ownershipPhrase}. Use --force to take over, or --if-available to skip without failing.`,EXIT_CODE.CONFLICT,{code:"already_claimed_by",why:"Claim is an atomic test-and-set so parallel agents never proceed believing they own the same item.",nextSteps:["Run pm next to pick a different unclaimed item.","Re-run with --if-available to treat a held item as a no-op skip.","Re-run with --force only when taking over the item is coordinated."]})}mutationWarnings.push(`claim_takeover:${previousAssignee}->${author}`)}const ownership={assignee:author,claim_principal:claimPrincipal},changedFields=["assignee","claim_principal"].filter(field=>document.metadata[field]!==ownership[field]);return Object.assign(document.metadata,ownership),{changedFields,warnings:mutationWarnings}}});return skipped||await recordClaimSemanticAttribution({pmRoot,settings,principal:claimPrincipal,itemId:result.item.id}),{item:toItemRecord(result.item),changed_fields:result.changedFields,claimed_by:skipped&&previousAssignee!==null?previousAssignee:author,previous_assignee:previousAssignee,forced:force,...skipped?{skipped:!0}:{},...mutationWarnings.length>0?{warnings:mutationWarnings}:{}}}async function runClaimNext(force,global2,options={},nextOptions={}){const maxAttempts=parseClaimNextAttempts(options.maxAttempts),settings=await readSettings(resolvePmRoot(process.cwd(),global2.path)),claimOptions={...options,author:resolveAuthor(options.author,settings.author_default)},next=await runNext({...nextOptions,callerAuthor:claimOptions.author,limit:String(maxAttempts)},global2),recommendations=[next.recommended,...next.ready].filter(entry=>entry!==null).map(entry=>({...entry,reasons:"reasons"in entry?entry.reasons:["ranked ready candidate"]}));return claimNextFromRecommendations(recommendations.slice(0,maxAttempts),force,global2,claimOptions)}function parseClaimNextAttempts(raw){if(raw===void 0)return 10;const parsed=Number(raw);if(!Number.isSafeInteger(parsed)||parsed<1||parsed>100)throw new PmCliError("--max-attempts must be an integer from 1 to 100",EXIT_CODE.USAGE);return parsed}async function claimNextFromRecommendations(recommendations,force,global2,options={},claimRunner=runClaim){let attempts=0;for(const recommendation of recommendations){attempts+=1;try{const claimed=await claimRunner(recommendation.id,force,global2,options),result={...claimed,recommendation,attempts,available:!0};if(!claimed.skipped)return result}catch(error){if(!isAlreadyClaimedError(error))throw error}}if(options.ifAvailable===!0)return{available:!1,item:null,claimed_by:resolveAuthor(options.author,""),previous_assignee:null,forced:force,skipped:!0,recommendation:null,attempts,warnings:[NO_AVAILABLE_NEXT_ITEM_CODE]};const noCandidatesMatched=attempts===0;throw new PmCliError(noCandidatesMatched?"No actionable items matched the selection filters":"No actionable item remained available to claim",noCandidatesMatched?EXIT_CODE.NOT_FOUND:EXIT_CODE.CONFLICT,{code:NO_AVAILABLE_NEXT_ITEM_CODE,why:noCandidatesMatched?"No ready items matched the specified filters or selection criteria.":"Every ranked candidate was claimed by another agent before this atomic selection completed.",nextSteps:[noCandidatesMatched?"Verify the filters or run pm next to inspect all ready work.":"Run pm claim --next again to refresh the ranked candidate set."]})}async function runRelease(id,force,global2,options={}){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),author=resolveAuthor(options.author,settings.author_default),claimPrincipal=resolveClaimPrincipal(author),ownershipReleaseBypass=options.ownershipReleaseBypass===!0;let previousAssignee=null,result;try{result=await mutateItem({pmRoot,settings,id,op:"release",author,message:options.message,force,bypassAssigneeConflict:ownershipReleaseBypass,mutate(document){return previousAssignee=document.metadata.assignee??null,!previousAssignee&&!document.metadata.claim_principal?{changedFields:[]}:(delete document.metadata.assignee,delete document.metadata.claim_principal,{changedFields:["assignee","claim_principal"]})}})}catch(error){wrapOwnershipConflict(error,{required:"For approved non-owner handoffs, prefer the ownership-release bypass before considering --force.",examples:['pm release pm-a1b2 --author "reviewer" --force'],nextSteps:["Use the package-provided ownership-release bypass for handoffs that only clear assignee metadata.","Use --force only when an explicit override is approved for broader ownership conflicts."]})}await recordReleaseSemanticAttribution({pmRoot,principal:claimPrincipal,itemId:result.item.id});const statusRegistry=resolveRuntimeStatusRegistry(settings.schema),stillInProgress=normalizeStatusForRegistry(result.item.status,statusRegistry)===normalizeStatusForRegistry(statusRegistry.in_progress_status,statusRegistry);return{item:toItemRecord(result.item),released_by:author,changed_fields:result.changedFields,previous_assignee:previousAssignee,forced:force,...stillInProgress?{warnings:["released_unclaimed_in_progress"],suggestions:[`${result.item.id} remains ${result.item.status} and unclaimed. If work is paused, run pm release ${result.item.id} --pause to move it to ${statusRegistry.open_status}.`]}:{}}}export{NO_AVAILABLE_NEXT_ITEM_CODE,claimNextFromRecommendations,isAlreadyClaimedError,parseClaimNextAttempts,runClaim,runClaimNext,runRelease};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ca9fb199-0de6-5eea-bed8-7afac49123bc")}catch{}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{resolveRuntimeStatusRegistry,statusIsTerminal,EXIT_CODE,PmCliError,toItemRecord,mutateItem,resolvePmRoot,readSettings,resolveAuthor,resolveClaimPrincipal,normalizeStatusForRegistry}from"../runtime-primitives.js";import{wrapOwnershipConflict}from"../annotations.js";import{describeItemOwnershipConflict}from"../ownership-source.js";import{applyReleaseHandoff,resolveReleaseHandoff}from"./release-handoff.js";import{runNext}from"../query/next.js";import{recordClaimSemanticAttribution,recordReleaseSemanticAttribution}from"../context/semantic-session-attribution.js";const NO_AVAILABLE_NEXT_ITEM_CODE="no_available_next_item";function isAlreadyClaimedError(error){if(!(error instanceof Error)||error.name!=="PmCliError")return!1;const context=error.context;return typeof context=="object"&&context!==null&&"code"in context&&context.code==="already_claimed_by"}async function runClaim(id,force,global2,options={}){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),statusRegistry=resolveRuntimeStatusRegistry(settings.schema),author=resolveAuthor(options.author,settings.author_default),claimPrincipal=resolveClaimPrincipal(author);let previousAssignee=null,skipped=!1;const mutationWarnings=[],result=await mutateItem({pmRoot,settings,id,op:"claim",author,message:options.message,force,skipNoop:!0,async mutate(document){const currentAssigneeText=document.metadata.assignee??"",currentClaimPrincipal=document.metadata.claim_principal?.trim()||currentAssigneeText;if(previousAssignee=currentAssigneeText.trim().length>0?currentAssigneeText:null,statusIsTerminal(document.metadata.status,statusRegistry)&&!force)throw new PmCliError(`Cannot claim terminal item ${document.metadata.id} without --force`,EXIT_CODE.CONFLICT);if(previousAssignee!==null&&currentClaimPrincipal!==claimPrincipal){if(options.ifAvailable===!0)return skipped=!0,mutationWarnings.push(`claim_skipped_held_by:${previousAssignee}`),{changedFields:[]};if(!force){const ownershipPhrase=await describeItemOwnershipConflict(pmRoot,document.metadata.id,currentAssigneeText);throw new PmCliError(`Item ${document.metadata.id} is already ${ownershipPhrase}. Use --force to take over, or --if-available to skip without failing.`,EXIT_CODE.CONFLICT,{code:"already_claimed_by",why:"Claim is an atomic test-and-set so parallel agents never proceed believing they own the same item.",nextSteps:["Run pm next to pick a different unclaimed item.","Re-run with --if-available to treat a held item as a no-op skip.","Re-run with --force only when taking over the item is coordinated."]})}mutationWarnings.push(`claim_takeover:${previousAssignee}->${author}`)}const ownership={assignee:author,claim_principal:claimPrincipal},changedFields=["assignee","claim_principal"].filter(field=>document.metadata[field]!==ownership[field]);return Object.assign(document.metadata,ownership),{changedFields,warnings:mutationWarnings}}});return skipped||await recordClaimSemanticAttribution({pmRoot,settings,principal:claimPrincipal,itemId:result.item.id}),{item:toItemRecord(result.item),changed_fields:result.changedFields,claimed_by:skipped&&previousAssignee!==null?previousAssignee:author,previous_assignee:previousAssignee,forced:force,...skipped?{skipped:!0}:{},...mutationWarnings.length>0?{warnings:mutationWarnings}:{}}}async function runClaimNext(force,global2,options={},nextOptions={}){const maxAttempts=parseClaimNextAttempts(options.maxAttempts),settings=await readSettings(resolvePmRoot(process.cwd(),global2.path)),claimOptions={...options,author:resolveAuthor(options.author,settings.author_default)},next=await runNext({...nextOptions,callerAuthor:claimOptions.author,limit:String(maxAttempts)},global2),recommendations=[next.recommended,...next.ready].filter(entry=>entry!==null).map(entry=>({...entry,reasons:"reasons"in entry?entry.reasons:["ranked ready candidate"]}));return claimNextFromRecommendations(recommendations.slice(0,maxAttempts),force,global2,claimOptions)}function parseClaimNextAttempts(raw){if(raw===void 0)return 10;const parsed=Number(raw);if(!Number.isSafeInteger(parsed)||parsed<1||parsed>100)throw new PmCliError("--max-attempts must be an integer from 1 to 100",EXIT_CODE.USAGE);return parsed}async function claimNextFromRecommendations(recommendations,force,global2,options={},claimRunner=runClaim){let attempts=0;for(const recommendation of recommendations){attempts+=1;try{const claimed=await claimRunner(recommendation.id,force,global2,options),result={...claimed,recommendation,attempts,available:!0};if(!claimed.skipped)return result}catch(error){if(!isAlreadyClaimedError(error))throw error}}if(options.ifAvailable===!0)return{available:!1,item:null,claimed_by:resolveAuthor(options.author,""),previous_assignee:null,forced:force,skipped:!0,recommendation:null,attempts,warnings:[NO_AVAILABLE_NEXT_ITEM_CODE]};const noCandidatesMatched=attempts===0;throw new PmCliError(noCandidatesMatched?"No actionable items matched the selection filters":"No actionable item remained available to claim",noCandidatesMatched?EXIT_CODE.NOT_FOUND:EXIT_CODE.CONFLICT,{code:NO_AVAILABLE_NEXT_ITEM_CODE,why:noCandidatesMatched?"No ready items matched the specified filters or selection criteria.":"Every ranked candidate was claimed by another agent before this atomic selection completed.",nextSteps:[noCandidatesMatched?"Verify the filters or run pm next to inspect all ready work.":"Run pm claim --next again to refresh the ranked candidate set."]})}async function runRelease(id,force,global2,options={}){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),author=resolveAuthor(options.author,settings.author_default),claimPrincipal=resolveClaimPrincipal(author),ownershipReleaseBypass=options.ownershipReleaseBypass===!0;let previousAssignee=null;const statusRegistry=resolveRuntimeStatusRegistry(settings.schema),handoffStatus=resolveReleaseHandoff(options,statusRegistry);if(handoffStatus!==void 0&&ownershipReleaseBypass)throw new PmCliError("Ownership-release bypass only clears ownership; it cannot change a handoff status.",EXIT_CODE.USAGE);let handoff,result;try{result=await mutateItem({pmRoot,settings,id,op:"release",author,message:options.message,force,bypassAssigneeConflict:ownershipReleaseBypass,mutate(document){previousAssignee=document.metadata.assignee??null;const transition=handoffStatus===void 0?void 0:applyReleaseHandoff(document.metadata,handoffStatus,settings,statusRegistry,options.message);return handoff=transition?.receipt,!previousAssignee&&!document.metadata.claim_principal?{changedFields:[]}:(delete document.metadata.assignee,delete document.metadata.claim_principal,{changedFields:["assignee","claim_principal",...transition?.changedFields??[]],warnings:transition?.warnings})}})}catch(error){wrapOwnershipConflict(error,{required:"For approved non-owner handoffs, prefer the ownership-release bypass before considering --force.",examples:['pm release pm-a1b2 --author "reviewer" --force'],nextSteps:["Use the package-provided ownership-release bypass for handoffs that only clear assignee metadata.","Use --force only when an explicit override is approved for broader ownership conflicts."]})}await recordReleaseSemanticAttribution({pmRoot,principal:claimPrincipal,itemId:result.item.id});const stillInProgress=normalizeStatusForRegistry(result.item.status,statusRegistry)===normalizeStatusForRegistry(statusRegistry.in_progress_status,statusRegistry);return{item:toItemRecord(result.item),released_by:author,changed_fields:result.changedFields,previous_assignee:previousAssignee,forced:force,...handoff===void 0?{}:{handoff},...result.warnings.length>0||stillInProgress?{warnings:[...result.warnings,...stillInProgress?["released_unclaimed_in_progress"]:[]]}:{},...stillInProgress?{suggestions:[`${result.item.id} remains ${result.item.status} and unclaimed. If work is paused, run pm release ${result.item.id} --pause to move it to ${statusRegistry.open_status}.`]}:{}}}export{NO_AVAILABLE_NEXT_ITEM_CODE,claimNextFromRecommendations,isAlreadyClaimedError,parseClaimNextAttempts,runClaim,runClaimNext,runRelease};
 //# sourceMappingURL=claim.js.map

package/dist/sdk/lifecycle/close-many.d.ts

@@ -1,123 +1,123 @@
-import { type GlobalOptions, readSettings } from "../runtime-primitives.js";
+import { type GlobalOptions,readSettings } from "../runtime-primitives.js";
 import { type ListOptions } from "../query/list.js";
 import { type PmCommandEffectReceipt } from "../cli-contracts/command-exit-contracts.js";
 /** Documents the close many command options payload exchanged by command, SDK, and package integrations. */
 export interface CloseManyCommandOptions {
 /** Lifecycle state reported for status. */
-status?: string;
+status?:string;
 /** Value that configures or reports list for this contract. */
-list?: ListOptions;
+list?:ListOptions;
 /** Value that configures or reports reason for this contract. */
-reason?: string;
+reason?:string;
 /** Actual completion time shared by every matched close. */
-completedAt?: string;
+completedAt?:string;
 /** Value that configures or reports resolution for this contract. */
-resolution?: string;
+resolution?:string;
 /** Structured result returned by the expected operation. */
-expectedResult?: string;
+expectedResult?:string;
 /** Structured result returned by the actual operation. */
-actualResult?: string;
+actualResult?:string;
 /** Value that configures or reports validate close for this contract. */
-validateClose?: string;
+validateClose?:string;
 /** Value that configures or reports author for this contract. */
-author?: string;
+author?:string;
 /** Human-readable explanation suitable for logs and agent-facing output. */
-message?: string;
+message?:string;
 /** Value that configures or reports force for this contract. */
-force?: boolean;
+force?:boolean;
 /** Value that configures or reports dry run for this contract. */
-dryRun?: boolean;
+dryRun?:boolean;
 /** Value that configures or reports rollback for this contract. */
-rollback?: string;
+rollback?:string;
 /** Value that configures or reports checkpoint for this contract. */
-checkpoint?: boolean;
+checkpoint?:boolean;
 }
 /** Presentation-neutral input accepted by the SDK-owned bulk close operation. */
 export type CloseManyOperationOptions = CloseManyCommandOptions;
 interface CloseManyPlanRow {
-id: string;
-title: string;
-status: string;
-action: "close" | "skip";
-skip_reason?: string;
-active_child_ids?: string[];
+id:string;
+title:string;
+status:string;
+action:"close" | "skip";
+skip_reason?:string;
+active_child_ids?:string[];
 }
 interface CloseManyApplyRow {
-id: string;
-status: "closed" | "skipped" | "failed";
-skip_reason?: string;
-changed_fields?: string[];
-warnings?: string[];
-error?: string;
+id:string;
+status:"closed" | "skipped" | "failed";
+skip_reason?:string;
+changed_fields?:string[];
+warnings?:string[];
+error?:string;
 }
 /** Documents the close many result payload exchanged by command, SDK, and package integrations. */
 export interface CloseManyResult extends PmCommandEffectReceipt {
 /** Value that configures or reports mode for this contract. */
-mode: "dry_run" | "apply" | "rollback";
+mode:"dry_run" | "apply" | "rollback";
 /** Number of matched entries represented by this result. */
-matched_count: number;
+matched_count:number;
 /** Value that configures or reports dry run for this contract. */
-dry_run: boolean;
+dry_run:boolean;
 /** Value that configures or reports reason for this contract. */
-reason?: string;
+reason?:string;
 /** Value that configures or reports filters for this contract. */
-filters?: Record<string, unknown>;
+filters?:Record<string,unknown>;
 /** Value that configures or reports validate close for this contract. */
-validate_close?: string;
+validate_close?:string;
 /** Value that configures or reports item plans for this contract. */
-item_plans?: CloseManyPlanRow[];
+item_plans?:CloseManyPlanRow[];
 /** Value that configures or reports checkpoint for this contract. */
-checkpoint?: {
-id: string;
-created_at: string;
-path: string;
-rollback_command: string;
+checkpoint?:{
+id:string;
+created_at:string;
+path:string;
+rollback_command:string;
 };
 /** Number of closed entries represented by this result. */
-closed_count?: number;
+closed_count?:number;
 /** Number of skipped entries represented by this result. */
-skipped_count?: number;
+skipped_count?:number;
 /** Number of failed entries represented by this result. */
-failed_count?: number;
+failed_count?:number;
 /** Number of restored entries represented by this result. */
-restored_count?: number;
+restored_count?:number;
 /** Value that configures or reports rollback checkpoint id for this contract. */
-rollback_checkpoint_id?: string;
+rollback_checkpoint_id?:string;
 /** Value that configures or reports rows for this contract. */
-rows?: CloseManyApplyRow[] | Array<{
-id: string;
-status: "restored" | "failed";
-changed_fields?: string[];
-warnings?: string[];
-error?: string;
+rows?:CloseManyApplyRow[] | Array<{
+id:string;
+status:"restored" | "failed";
+changed_fields?:string[];
+warnings?:string[];
+error?:string;
 }>;
 /** Value that configures or reports ids for this contract. */
-ids: string[];
+ids:string[];
 /** Explicitly requested --ids values that matched no selected item. */
-unmatched_ids?: string[];
+unmatched_ids?:string[];
 /** Number of explicitly requested --ids values that matched no selected item. */
-unmatched_count?: number;
+unmatched_count?:number;
 }
-declare function hasCloseManyFilters(list: ListOptions | undefined, status: string | undefined): boolean;
-declare function hasCloseManyRollbackConflicts(list: ListOptions | undefined, status: string | undefined): boolean;
-declare function rejectBlankIdsFilter(list: ListOptions | undefined): void;
-declare function activeListOptions(list: ListOptions | undefined): ListOptions;
-declare function resolveReason(reason: unknown, required: boolean): string | undefined;
-declare function buildActiveChildrenByParent(pmRoot: string, settings: Awaited<ReturnType<typeof readSettings>>): Promise<{
-childrenByParent: Map<string, string[]>;
-parentByChild: Map<string, string>;
+declare function hasCloseManyFilters(list:ListOptions | undefined,status:string | undefined):boolean;
+declare function hasCloseManyRollbackConflicts(list:ListOptions | undefined,status:string | undefined):boolean;
+declare function rejectBlankIdsFilter(list:ListOptions | undefined):void;
+declare function activeListOptions(list:ListOptions | undefined):ListOptions;
+declare function resolveReason(reason:unknown,required:boolean):string | undefined;
+declare function buildActiveChildrenByParent(pmRoot:string,settings:Awaited<ReturnType<typeof readSettings>>):Promise<{
+childrenByParent:Map<string,string[]>;
+parentByChild:Map<string,string>;
 }>;
-declare function hierarchyDepth(id: string, parentByChild: Map<string, string>, cache?: Map<string, number>): number;
+declare function hierarchyDepth(id:string,parentByChild:Map<string,string>,cache?:Map<string,number>):number;
 /** Implements run close many for the public runtime surface of this module. */
-export declare function runCloseMany(options: CloseManyCommandOptions, global: GlobalOptions): Promise<CloseManyResult>;
+export declare function runCloseMany(options:CloseManyCommandOptions,global:GlobalOptions):Promise<CloseManyResult>;
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
-export declare const _testOnly: {
-activeListOptions: typeof activeListOptions;
-buildActiveChildrenByParent: typeof buildActiveChildrenByParent;
-hasCloseManyFilters: typeof hasCloseManyFilters;
-hasCloseManyRollbackConflicts: typeof hasCloseManyRollbackConflicts;
-hierarchyDepth: typeof hierarchyDepth;
-rejectBlankIdsFilter: typeof rejectBlankIdsFilter;
-resolveReason: typeof resolveReason;
+export declare const _testOnly:{
+activeListOptions:typeof activeListOptions;
+buildActiveChildrenByParent:typeof buildActiveChildrenByParent;
+hasCloseManyFilters:typeof hasCloseManyFilters;
+hasCloseManyRollbackConflicts:typeof hasCloseManyRollbackConflicts;
+hierarchyDepth:typeof hierarchyDepth;
+rejectBlankIdsFilter:typeof rejectBlankIdsFilter;
+resolveReason:typeof resolveReason;
 };
 export {};

package/dist/sdk/lifecycle/close.d.ts

@@ -1,49 +1,43 @@
-/**
- * @module sdk/lifecycle/close
- *
- * Implements the pm close command surface and its agent-facing runtime behavior.
- */
-import type { PmCliErrorRecoveryPayload } from "../../core/shared/errors.js";
 import { type GlobalOptions } from "../runtime-primitives.js";
 import { collectBlockedByIds } from "../actionability.js";
-import { type CloseOperationOptions, type CloseOperationResult } from "../lifecycle-policy.js";
+import { type CloseOperationOptions,type CloseOperationResult,type CloseEvidenceFollowUp } from "../lifecycle-policy.js";
 /** Compatibility options for command-shaped close consumers. */
 export interface CloseCommandOptions {
 /** Mutation author. */
-author?: string;
+author?:string;
 /** Immutable history message. */
-message?: string;
+message?:string;
 /** Closure validation mode. */
-validateClose?: string;
+validateClose?:string;
 /** Permit repeat closure. */
-force?: boolean;
+force?:boolean;
 /** Structured resolution evidence. */
-resolution?: string;
+resolution?:string;
 /** Expected outcome evidence. */
-expectedResult?: string;
+expectedResult?:string;
 /** Actual outcome evidence. */
-actualResult?: string;
+actualResult?:string;
 /** Canonical duplicate target. */
-duplicateOf?: string;
+duplicateOf?:string;
 /** Actual completion time. */
-completedAt?: string;
+completedAt?:string;
 }
 /** Compatibility result for command-shaped close consumers. */
 export interface CloseResult {
 /** Closed item record. */
-item: Record<string, unknown>;
+item:Record<string,unknown>;
 /** Changed metadata fields. */
-changed_fields: string[];
+changed_fields:string[];
 /** Evidence-only update guidance when acceptance fields are missing. */
-recovery?: PmCliErrorRecoveryPayload;
+follow_up?:CloseEvidenceFollowUp;
 /** Validation and lifecycle receipts. */
-warnings: string[];
+warnings:string[];
 }
 /** Public contract for test only close command, shared by SDK and presentation-layer consumers. */
-export declare const _testOnlyCloseCommand: {
-blockedByIds: typeof collectBlockedByIds;
+export declare const _testOnlyCloseCommand:{
+blockedByIds:typeof collectBlockedByIds;
 };
 /** Close one item through the SDK-owned lifecycle transaction and policy. */
-export declare function closeItem(id: string, closeReasonText: string | undefined, options: CloseOperationOptions, global: GlobalOptions): Promise<CloseOperationResult>;
+export declare function closeItem(id:string,closeReasonText:string | undefined,options:CloseOperationOptions,global:GlobalOptions):Promise<CloseOperationResult>;
 /** Compatibility command-shaped wrapper over the SDK-owned close operation. */
-export declare function runClose(id: string, closeReasonText: string | undefined, options: CloseCommandOptions, global: GlobalOptions): Promise<CloseResult>;
+export declare function runClose(id:string,closeReasonText:string | undefined,options:CloseCommandOptions,global:GlobalOptions):Promise<CloseResult>;

package/dist/sdk/lifecycle/close.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ab15186d-b8bc-5740-bc16-d5af1eeeaa02")}catch{}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{toItemRecord,isTerminalStatus,resolveItemTypeRegistry,resolveRuntimeStatusRegistry,EXIT_CODE,PmCliError,buildItemNotFoundError,listAllItemMetadataLight,locateItem,mutateItem,readLocatedItem,resolvePmRoot,readSettings,resolveAuthor,resolveIsoOrRelative,shouldCompletePlanOnClose,getActiveExtensionRegistrations}from"../runtime-primitives.js";import{collectBlockedByIds,indexBlockedByIds}from"../actionability.js";import{applyTerminalOrderingPolicy,requireTerminalReason}from"../lifecycle-policy.js";import{nowIso}from"../../core/shared/time.js";import{renderPmCommand}from"../command-line.js";const CLOSE_VALIDATION_FIELDS=[{key:"resolution",label:"resolution (--resolution)"},{key:"expected_result",label:"expected_result (--expected-result)"},{key:"actual_result",label:"actual_result (--actual-result)"}];function parseValidateCloseMode(raw){if(raw===void 0)return;const normalized=raw.trim().toLowerCase();if(normalized.length===0||normalized==="warn")return"warn";if(normalized==="off"||normalized==="none"||normalized==="disabled")return"off";if(normalized==="strict")return"strict";throw new PmCliError(`Invalid --validate-close mode "${raw}" (expected "off", "warn", or "strict")`,EXIT_CODE.USAGE)}function findMissingCloseValidationFields(itemMetadata){const missing=[];for(const field of CLOSE_VALIDATION_FIELDS){const rawValue=itemMetadata[field.key];(typeof rawValue!="string"||rawValue.trim().length===0)&&missing.push(field)}return missing}function closeEvidenceRecovery(metadata,pmRoot,options={}){const missing=findMissingCloseValidationFields(metadata);if(missing.length===0)return;const values={resolution:options.resolution,expected_result:options.expectedResult,actual_result:options.actualResult},missingFlags=missing.map(field=>`--${field.key.replaceAll("_","-")}`),args=["--pm-path",pmRoot,"update",metadata.id,...missing.flatMap((field,index)=>[missingFlags[index],values[field.key]?.trim()||"<value>"])];return{missing:missingFlags,suggested_retry:renderPmCommand(args),suggested_retry_args:args}}async function duplicateChainReferencesClosingItem(loadItemById,initialDuplicateOf,closingId){const visited=new Set;let current=initialDuplicateOf;for(;typeof current=="string"&&current.trim().length>0;){const currentId=current.trim();if(currentId===closingId)return!0;if(visited.has(currentId))return!1;visited.add(currentId),current=(await loadItemById(currentId))?.duplicate_of}return!1}function shouldApplyDuplicateFallback(value){return typeof value!="string"||value.trim().length===0}async function assertDuplicateTargetExists(pmRoot,settings,duplicateOf,closingId){const rawTarget=duplicateOf?.trim();if(!rawTarget)return;if(rawTarget===closingId)throw new PmCliError("An item cannot be closed as a duplicate of itself.",EXIT_CODE.USAGE,{code:"duplicate_target_self",why:"--duplicate-of must identify the canonical item that should remain open or already represent the work."});const typeRegistry=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations()),itemCache=new Map,loadItemById=async id=>{if(itemCache.has(id))return itemCache.get(id)??null;const located=await locateItem(pmRoot,id,settings.id_prefix,settings.item_format,typeRegistry.type_to_folder);if(!located)return itemCache.set(id,null),null;const{document}=await readLocatedItem(located,{schema:settings.schema});return itemCache.set(id,document.metadata),document.metadata},target=await loadItemById(rawTarget);if(!target)throw new PmCliError(`Duplicate target "${rawTarget}" was not found. Create or locate the canonical item first.`,EXIT_CODE.USAGE,{code:"duplicate_target_missing",why:"Duplicate closure should point at a real canonical pm item so future dedupe and changelog tooling can trace the relationship.",examples:[`pm close ${closingId} "Duplicate of ${rawTarget}" --duplicate-of ${rawTarget}`],nextSteps:["Run pm search/list to find the canonical item, then retry with --duplicate-of <id>."]});if(await duplicateChainReferencesClosingItem(loadItemById,target.duplicate_of,closingId))throw new PmCliError(`Circular duplicate reference detected. Target "${rawTarget}" points back to "${closingId}".`,EXIT_CODE.USAGE,{code:"duplicate_target_circular",why:"Circular duplicate relationships create loops for dedupe and status propagation tooling.",nextSteps:["Choose the existing canonical item, or clear the target duplicate_of metadata before closing this item as a duplicate."]});if(typeof target.duplicate_of=="string"&&target.duplicate_of.trim().length>0)throw new PmCliError(`Duplicate target "${rawTarget}" is already marked as a duplicate of "${target.duplicate_of.trim()}".`,EXIT_CODE.USAGE,{code:"duplicate_target_is_duplicate",why:"Duplicate closure should point directly at the canonical item, not another duplicate.",examples:[`pm close ${closingId} "Duplicate of ${target.duplicate_of.trim()}" --duplicate-of ${target.duplicate_of.trim()}`],nextSteps:["Use the canonical item referenced by duplicate_of as the --duplicate-of target."]});return target.id}function findActiveChildIds(items,parentId,statusRegistry){return items.filter(item=>item.parent===parentId&&!isTerminalStatus(item.status,statusRegistry)).map(item=>item.id).sort((left,right)=>left.localeCompare(right))}function findAutoUnblockCandidates(items,closedId,statusRegistry){const itemsById=new Map(items.map(item=>[item.id.trim().toLowerCase(),item])),blockerIdsByItem=indexBlockedByIds(items),normalizedClosedId=closedId.trim().toLowerCase(),blockedStatuses=statusRegistry.blocked_statuses;return items.filter(item=>blockedStatuses.has(item.status)).map(item=>({item,blockerIds:blockerIdsByItem.get(item.id.trim().toLowerCase())})).filter(({blockerIds})=>blockerIds.includes(normalizedClosedId)).filter(({blockerIds})=>blockerIds.every(blockerId=>{if(blockerId===normalizedClosedId)return!0;const blocker=itemsById.get(blockerId);return blocker!==void 0&&isTerminalStatus(blocker.status,statusRegistry)})).map(({item,blockerIds})=>({id:item.id,blocker_ids:blockerIds})).sort((left,right)=>left.id.localeCompare(right.id))}async function autoUnblockResolvedDependents(pmRoot,settings,items,closedId,author,statusRegistry){const candidates=findAutoUnblockCandidates(items,closedId,statusRegistry),warnings=[];for(const candidate of candidates)try{const unblocked=await mutateItem({pmRoot,settings,id:candidate.id,op:"update",author,message:`Auto-unblocked after blocker ${closedId} closed`,mutate(document){const dependencies=document.metadata.dependencies??[],remainingDependencies=dependencies.filter(dependency=>{const dependencyId=dependency.id.trim().toLowerCase();return dependency.kind!=="blocked_by"||!candidate.blocker_ids.includes(dependencyId)});document.metadata.status=statusRegistry.open_status,delete document.metadata.blocked_by,delete document.metadata.blocked_reason,document.metadata.unblock_note=`Auto-unblocked after blocker ${closedId} closed; all blockers resolved (${candidate.blocker_ids.join(", ")}).`,remainingDependencies.length>0?document.metadata.dependencies=remainingDependencies:delete document.metadata.dependencies;const changedFields=["status","blocked_by","blocked_reason","unblock_note"];return remainingDependencies.length!==dependencies.length&&changedFields.push("dependencies"),{changedFields}}});warnings.push(`auto_unblocked:${unblocked.item.id}:resolved_blockers=${candidate.blocker_ids.join(",")}`)}catch(error){const reason=error instanceof Error?error.message.replace(/\s+/g," ").trim():"unknown";warnings.push(`auto_unblock_failed:${candidate.id}:${reason}`)}return warnings}function applyInlineCloseFields(metadata,options){const changedFields=[],inlineCloseFields=[{option:options.resolution,key:"resolution"},{option:options.expectedResult,key:"expected_result"},{option:options.actualResult,key:"actual_result"}];for(const{option,key}of inlineCloseFields){if(typeof option!="string")continue;const trimmed=option.trim();trimmed.length!==0&&(metadata[key]=trimmed,changedFields.push(key))}return changedFields}function applyDuplicateCloseMetadata(metadata,duplicateOf){if(duplicateOf===void 0)return[];metadata.duplicate_of=duplicateOf;const duplicateFallbackFields=[],fallbackValues=[{key:"resolution",value:`Duplicate of ${duplicateOf}`},{key:"expected_result",value:`Canonical item ${duplicateOf} tracks the work.`},{key:"actual_result",value:`Closed as duplicate of ${duplicateOf}.`}];for(const{key,value}of fallbackValues)shouldApplyDuplicateFallback(metadata[key])&&(metadata[key]=value,duplicateFallbackFields.push(key));return duplicateFallbackFields}function collectCloseValidationWarnings(metadata,validateCloseMode,activeChildIds,pmRoot){const warnings=[];if(validateCloseMode!=="off"){const missingFields=findMissingCloseValidationFields(metadata);if(missingFields.length>0){const missingLabels=missingFields.map(field=>field.label);if(validateCloseMode==="strict"){const missingFlags=missingFields.map(field=>`--${field.key.replaceAll("_","-")}`),updateTokens=["--pm-path",pmRoot,"update",metadata.id,...missingFlags.flatMap(flag=>[flag,"<value>"])];throw new PmCliError(`Cannot close item ${metadata.id}: missing ${missingLabels.join(", ")}. Populate fields or use --validate-close warn.`,EXIT_CODE.USAGE,{code:"close_validation_missing_fields",recovery:{missing:missingFlags,suggested_retry:renderPmCommand(updateTokens)},nextSteps:["Run the suggested pm update, then retry the original pm close invocation.","Use --validate-close warn only when governance permits an evidenced exception."]})}warnings.push(`close_validation_missing_fields:${metadata.id}:${missingLabels.join(",")}`)}if(activeChildIds.length>0){if(validateCloseMode==="strict")throw new PmCliError(`Cannot close item ${metadata.id}: active child items remain open (${activeChildIds.join(", ")}). Close, cancel, or re-parent them first, or use --validate-close warn.`,EXIT_CODE.USAGE);warnings.push(`close_validation_active_children:${metadata.id}:${activeChildIds.join(",")}`)}return warnings}return activeChildIds.length>0&&warnings.push(`closed_with_active_children:${metadata.id}:${activeChildIds.join(",")}`),warnings}function applyCloseReason(metadata,closeReason){return closeReason!==void 0?(metadata.close_reason=closeReason,["close_reason"]):[]}function clearCloseAssignee(metadata){return metadata.assignee===void 0?[]:(delete metadata.assignee,["assignee"])}function mutateCloseMetadata(metadata,context){if(isTerminalStatus(metadata.status,context.statusRegistry)&&!context.force)throw new PmCliError(`Item ${metadata.id} is already terminal; use pm update to append acceptance evidence, or --force only for an intentional repeat closure.`,EXIT_CODE.CONFLICT,{recovery:closeEvidenceRecovery(metadata,context.pmRoot,context.options)});const inlineChangedFields=applyInlineCloseFields(metadata,context.options),duplicateFallbackFields=applyDuplicateCloseMetadata(metadata,context.duplicateOf),mutationWarnings=collectCloseValidationWarnings(metadata,context.validateCloseMode,context.activeChildIds,context.pmRoot);metadata.status=context.statusRegistry.close_status,metadata.closed_at=context.closedAt;const shouldWriteCompletedAt=context.options.completedAt!==void 0||metadata.completed_at===void 0;shouldWriteCompletedAt&&(metadata.completed_at=context.completedAt);const changedFields=["status","closed_at",...shouldWriteCompletedAt?["completed_at"]:[],...applyCloseReason(metadata,context.closeReason),...inlineChangedFields];if(shouldCompletePlanOnClose(metadata)&&(metadata.plan_mode="completed",changedFields.push("plan_mode")),context.duplicateOf!==void 0){changedFields.push("duplicate_of");for(const key of duplicateFallbackFields)changedFields.includes(key)||changedFields.push(key)}changedFields.push(...clearCloseAssignee(metadata));const blockerCleanup=applyTerminalOrderingPolicy(metadata,context.lifecyclePolicy);return changedFields.push(...blockerCleanup.changedFields),mutationWarnings.push(...blockerCleanup.warnings),{changedFields,...mutationWarnings.length>0?{warnings:mutationWarnings}:{}}}const _testOnlyCloseCommand={blockedByIds:collectBlockedByIds};async function closeItem(id,closeReasonText,options,global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),statusRegistry=resolveRuntimeStatusRegistry(settings.schema),author=resolveAuthor(options.author,settings.author_default),typeToFolder=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations()).type_to_folder,located=await locateItem(pmRoot,id,settings.id_prefix,settings.item_format,typeToFolder);if(!located)throw await buildItemNotFoundError(pmRoot,id,settings.id_prefix,typeToFolder);const duplicateOf=await assertDuplicateTargetExists(pmRoot,settings,options.duplicateOf,located.id),lifecyclePolicy={requireCloseReason:options.lifecyclePolicy?.requireCloseReason??settings.governance.require_close_reason,orderingEdges:options.lifecyclePolicy?.orderingEdges??"preserve"},closeReason=requireTerminalReason({explicit:closeReasonText,duplicateOf,resolution:options.resolution,message:options.message},lifecyclePolicy.requireCloseReason).closeReason,validateCloseMode=parseValidateCloseMode(options.validateClose)??settings.governance.close_validation_default,trackerItems=await listAllItemMetadataLight(pmRoot,settings.item_format,typeToFolder,void 0,settings.schema),activeChildIds=findActiveChildIds(trackerItems,located.id,statusRegistry),closedAt=nowIso(),completedAt=options.completedAt===void 0?closedAt:resolveIsoOrRelative(options.completedAt,new Date(closedAt),"completed-at"),result=await mutateItem({pmRoot,settings,id:located.id,op:"close",author,message:options.message,force:options.force,mutate(document){return mutateCloseMetadata(document.metadata,{pmRoot,statusRegistry,force:options.force,options,duplicateOf,validateCloseMode,activeChildIds,closeReason,closedAt,completedAt,lifecyclePolicy})}}),recovery=validateCloseMode==="warn"?closeEvidenceRecovery(result.item,pmRoot):void 0;return{item:toItemRecord(result.item),changed_fields:result.changedFields,...recovery?{recovery}:{},warnings:[...result.warnings,...await autoUnblockResolvedDependents(pmRoot,settings,trackerItems,located.id,author,statusRegistry)]}}function runClose(id,closeReasonText,options,global2){return closeItem(id,closeReasonText,options,global2)}export{_testOnlyCloseCommand,closeItem,runClose};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6b7f5ee8-94ca-574f-b660-963eb574d571")}catch{}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{toItemRecord,isTerminalStatus,resolveItemTypeRegistry,resolveRuntimeStatusRegistry,EXIT_CODE,PmCliError,buildItemNotFoundError,listAllItemMetadataLight,locateItem,mutateItem,readLocatedItem,resolvePmRoot,readSettings,resolveAuthor,resolveIsoOrRelative,shouldCompletePlanOnClose,getActiveExtensionRegistrations}from"../runtime-primitives.js";import{collectBlockedByIds,indexBlockedByIds}from"../actionability.js";import{applyTerminalOrderingPolicy,requireTerminalReason}from"../lifecycle-policy.js";import{nowIso}from"../../core/shared/time.js";import{renderPmCommand}from"../command-line.js";const CLOSE_VALIDATION_FIELDS=[{key:"resolution",label:"resolution (--resolution)"},{key:"expected_result",label:"expected_result (--expected-result)"},{key:"actual_result",label:"actual_result (--actual-result)"}];function parseValidateCloseMode(raw){if(raw===void 0)return;const normalized=raw.trim().toLowerCase();if(normalized.length===0||normalized==="warn")return"warn";if(normalized==="off"||normalized==="none"||normalized==="disabled")return"off";if(normalized==="strict")return"strict";throw new PmCliError(`Invalid --validate-close mode "${raw}" (expected "off", "warn", or "strict")`,EXIT_CODE.USAGE)}function findMissingCloseValidationFields(itemMetadata){const missing=[];for(const field of CLOSE_VALIDATION_FIELDS){const rawValue=itemMetadata[field.key];(typeof rawValue!="string"||rawValue.trim().length===0)&&missing.push(field)}return missing}function closeEvidenceRecovery(metadata,pmRoot,options={}){const missing=findMissingCloseValidationFields(metadata);if(missing.length===0)return;const values={resolution:options.resolution,expected_result:options.expectedResult,actual_result:options.actualResult},missingFlags=missing.map(field=>`--${field.key.replaceAll("_","-")}`),args=["--pm-path",pmRoot,"update",metadata.id,...missing.flatMap((field,index)=>[missingFlags[index],values[field.key]?.trim()||"<value>"])];return{missing:missingFlags,suggested_retry:renderPmCommand(args),suggested_retry_args:args}}async function duplicateChainReferencesClosingItem(loadItemById,initialDuplicateOf,closingId){const visited=new Set;let current=initialDuplicateOf;for(;typeof current=="string"&&current.trim().length>0;){const currentId=current.trim();if(currentId===closingId)return!0;if(visited.has(currentId))return!1;visited.add(currentId),current=(await loadItemById(currentId))?.duplicate_of}return!1}function shouldApplyDuplicateFallback(value){return typeof value!="string"||value.trim().length===0}async function assertDuplicateTargetExists(pmRoot,settings,duplicateOf,closingId){const rawTarget=duplicateOf?.trim();if(!rawTarget)return;if(rawTarget===closingId)throw new PmCliError("An item cannot be closed as a duplicate of itself.",EXIT_CODE.USAGE,{code:"duplicate_target_self",why:"--duplicate-of must identify the canonical item that should remain open or already represent the work."});const typeRegistry=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations()),itemCache=new Map,loadItemById=async id=>{if(itemCache.has(id))return itemCache.get(id)??null;const located=await locateItem(pmRoot,id,settings.id_prefix,settings.item_format,typeRegistry.type_to_folder);if(!located)return itemCache.set(id,null),null;const{document}=await readLocatedItem(located,{schema:settings.schema});return itemCache.set(id,document.metadata),document.metadata},target=await loadItemById(rawTarget);if(!target)throw new PmCliError(`Duplicate target "${rawTarget}" was not found. Create or locate the canonical item first.`,EXIT_CODE.USAGE,{code:"duplicate_target_missing",why:"Duplicate closure should point at a real canonical pm item so future dedupe and changelog tooling can trace the relationship.",examples:[`pm close ${closingId} "Duplicate of ${rawTarget}" --duplicate-of ${rawTarget}`],nextSteps:["Run pm search/list to find the canonical item, then retry with --duplicate-of <id>."]});if(await duplicateChainReferencesClosingItem(loadItemById,target.duplicate_of,closingId))throw new PmCliError(`Circular duplicate reference detected. Target "${rawTarget}" points back to "${closingId}".`,EXIT_CODE.USAGE,{code:"duplicate_target_circular",why:"Circular duplicate relationships create loops for dedupe and status propagation tooling.",nextSteps:["Choose the existing canonical item, or clear the target duplicate_of metadata before closing this item as a duplicate."]});if(typeof target.duplicate_of=="string"&&target.duplicate_of.trim().length>0)throw new PmCliError(`Duplicate target "${rawTarget}" is already marked as a duplicate of "${target.duplicate_of.trim()}".`,EXIT_CODE.USAGE,{code:"duplicate_target_is_duplicate",why:"Duplicate closure should point directly at the canonical item, not another duplicate.",examples:[`pm close ${closingId} "Duplicate of ${target.duplicate_of.trim()}" --duplicate-of ${target.duplicate_of.trim()}`],nextSteps:["Use the canonical item referenced by duplicate_of as the --duplicate-of target."]});return target.id}function findActiveChildIds(items,parentId,statusRegistry){return items.filter(item=>item.parent===parentId&&!isTerminalStatus(item.status,statusRegistry)).map(item=>item.id).sort((left,right)=>left.localeCompare(right))}function findAutoUnblockCandidates(items,closedId,statusRegistry){const itemsById=new Map(items.map(item=>[item.id.trim().toLowerCase(),item])),blockerIdsByItem=indexBlockedByIds(items),normalizedClosedId=closedId.trim().toLowerCase(),blockedStatuses=statusRegistry.blocked_statuses;return items.filter(item=>blockedStatuses.has(item.status)).map(item=>({item,blockerIds:blockerIdsByItem.get(item.id.trim().toLowerCase())})).filter(({blockerIds})=>blockerIds.includes(normalizedClosedId)).filter(({blockerIds})=>blockerIds.every(blockerId=>{if(blockerId===normalizedClosedId)return!0;const blocker=itemsById.get(blockerId);return blocker!==void 0&&isTerminalStatus(blocker.status,statusRegistry)})).map(({item,blockerIds})=>({id:item.id,blocker_ids:blockerIds})).sort((left,right)=>left.id.localeCompare(right.id))}async function autoUnblockResolvedDependents(pmRoot,settings,items,closedId,author,statusRegistry){const candidates=findAutoUnblockCandidates(items,closedId,statusRegistry),warnings=[];for(const candidate of candidates)try{const unblocked=await mutateItem({pmRoot,settings,id:candidate.id,op:"update",author,message:`Auto-unblocked after blocker ${closedId} closed`,mutate(document){const dependencies=document.metadata.dependencies??[],remainingDependencies=dependencies.filter(dependency=>{const dependencyId=dependency.id.trim().toLowerCase();return dependency.kind!=="blocked_by"||!candidate.blocker_ids.includes(dependencyId)});document.metadata.status=statusRegistry.open_status,delete document.metadata.blocked_by,delete document.metadata.blocked_reason,document.metadata.unblock_note=`Auto-unblocked after blocker ${closedId} closed; all blockers resolved (${candidate.blocker_ids.join(", ")}).`,remainingDependencies.length>0?document.metadata.dependencies=remainingDependencies:delete document.metadata.dependencies;const changedFields=["status","blocked_by","blocked_reason","unblock_note"];return remainingDependencies.length!==dependencies.length&&changedFields.push("dependencies"),{changedFields}}});warnings.push(`auto_unblocked:${unblocked.item.id}:resolved_blockers=${candidate.blocker_ids.join(",")}`)}catch(error){const reason=error instanceof Error?error.message.replace(/\s+/g," ").trim():"unknown";warnings.push(`auto_unblock_failed:${candidate.id}:${reason}`)}return warnings}function applyInlineCloseFields(metadata,options){const changedFields=[],inlineCloseFields=[{option:options.resolution,key:"resolution"},{option:options.expectedResult,key:"expected_result"},{option:options.actualResult,key:"actual_result"}];for(const{option,key}of inlineCloseFields){if(typeof option!="string")continue;const trimmed=option.trim();trimmed.length!==0&&(metadata[key]=trimmed,changedFields.push(key))}return changedFields}function applyDuplicateCloseMetadata(metadata,duplicateOf){if(duplicateOf===void 0)return[];metadata.duplicate_of=duplicateOf;const duplicateFallbackFields=[],fallbackValues=[{key:"resolution",value:`Duplicate of ${duplicateOf}`},{key:"expected_result",value:`Canonical item ${duplicateOf} tracks the work.`},{key:"actual_result",value:`Closed as duplicate of ${duplicateOf}.`}];for(const{key,value}of fallbackValues)shouldApplyDuplicateFallback(metadata[key])&&(metadata[key]=value,duplicateFallbackFields.push(key));return duplicateFallbackFields}function collectCloseValidationWarnings(metadata,validateCloseMode,activeChildIds,pmRoot){const warnings=[];if(validateCloseMode!=="off"){const missingFields=findMissingCloseValidationFields(metadata);if(missingFields.length>0){const missingLabels=missingFields.map(field=>field.label);if(validateCloseMode==="strict"){const missingFlags=missingFields.map(field=>`--${field.key.replaceAll("_","-")}`),updateTokens=["--pm-path",pmRoot,"update",metadata.id,...missingFlags.flatMap(flag=>[flag,"<value>"])];throw new PmCliError(`Cannot close item ${metadata.id}: missing ${missingLabels.join(", ")}. Populate fields or use --validate-close warn.`,EXIT_CODE.USAGE,{code:"close_validation_missing_fields",recovery:{missing:missingFlags,suggested_retry:renderPmCommand(updateTokens)},nextSteps:["Run the suggested pm update, then retry the original pm close invocation.","Use --validate-close warn only when governance permits an evidenced exception."]})}warnings.push(`close_validation_missing_fields:${metadata.id}:${missingLabels.join(",")}`)}if(activeChildIds.length>0){if(validateCloseMode==="strict")throw new PmCliError(`Cannot close item ${metadata.id}: active child items remain open (${activeChildIds.join(", ")}). Close, cancel, or re-parent them first, or use --validate-close warn.`,EXIT_CODE.USAGE);warnings.push(`close_validation_active_children:${metadata.id}:${activeChildIds.join(",")}`)}return warnings}return activeChildIds.length>0&&warnings.push(`closed_with_active_children:${metadata.id}:${activeChildIds.join(",")}`),warnings}function applyCloseReason(metadata,closeReason){return closeReason!==void 0?(metadata.close_reason=closeReason,["close_reason"]):[]}function clearCloseAssignee(metadata){return metadata.assignee===void 0?[]:(delete metadata.assignee,["assignee"])}function mutateCloseMetadata(metadata,context){if(isTerminalStatus(metadata.status,context.statusRegistry)&&!context.force)throw new PmCliError(`Item ${metadata.id} is already terminal; use pm update to append acceptance evidence, or --force only for an intentional repeat closure.`,EXIT_CODE.CONFLICT,{recovery:closeEvidenceRecovery(metadata,context.pmRoot,context.options)});const inlineChangedFields=applyInlineCloseFields(metadata,context.options),duplicateFallbackFields=applyDuplicateCloseMetadata(metadata,context.duplicateOf),mutationWarnings=collectCloseValidationWarnings(metadata,context.validateCloseMode,context.activeChildIds,context.pmRoot);metadata.status=context.statusRegistry.close_status,metadata.closed_at=context.closedAt;const shouldWriteCompletedAt=context.options.completedAt!==void 0||metadata.completed_at===void 0;shouldWriteCompletedAt&&(metadata.completed_at=context.completedAt);const changedFields=["status","closed_at",...shouldWriteCompletedAt?["completed_at"]:[],...applyCloseReason(metadata,context.closeReason),...inlineChangedFields];if(shouldCompletePlanOnClose(metadata)&&(metadata.plan_mode="completed",changedFields.push("plan_mode")),context.duplicateOf!==void 0){changedFields.push("duplicate_of");for(const key of duplicateFallbackFields)changedFields.includes(key)||changedFields.push(key)}changedFields.push(...clearCloseAssignee(metadata));const blockerCleanup=applyTerminalOrderingPolicy(metadata,context.lifecyclePolicy);return changedFields.push(...blockerCleanup.changedFields),mutationWarnings.push(...blockerCleanup.warnings),{changedFields,...mutationWarnings.length>0?{warnings:mutationWarnings}:{}}}const _testOnlyCloseCommand={blockedByIds:collectBlockedByIds};async function closeItem(id,closeReasonText,options,global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),statusRegistry=resolveRuntimeStatusRegistry(settings.schema),author=resolveAuthor(options.author,settings.author_default),typeToFolder=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations()).type_to_folder,located=await locateItem(pmRoot,id,settings.id_prefix,settings.item_format,typeToFolder);if(!located)throw await buildItemNotFoundError(pmRoot,id,settings.id_prefix,typeToFolder);const duplicateOf=await assertDuplicateTargetExists(pmRoot,settings,options.duplicateOf,located.id),lifecyclePolicy={requireCloseReason:options.lifecyclePolicy?.requireCloseReason??settings.governance.require_close_reason,orderingEdges:options.lifecyclePolicy?.orderingEdges??"preserve"},closeReason=requireTerminalReason({explicit:closeReasonText,duplicateOf,resolution:options.resolution,message:options.message},lifecyclePolicy.requireCloseReason).closeReason,validateCloseMode=parseValidateCloseMode(options.validateClose)??settings.governance.close_validation_default,trackerItems=await listAllItemMetadataLight(pmRoot,settings.item_format,typeToFolder,void 0,settings.schema),activeChildIds=findActiveChildIds(trackerItems,located.id,statusRegistry),closedAt=nowIso(),completedAt=options.completedAt===void 0?closedAt:resolveIsoOrRelative(options.completedAt,new Date(closedAt),"completed-at"),result=await mutateItem({pmRoot,settings,id:located.id,op:"close",author,message:options.message,force:options.force,mutate(document){return mutateCloseMetadata(document.metadata,{pmRoot,statusRegistry,force:options.force,options,duplicateOf,validateCloseMode,activeChildIds,closeReason,closedAt,completedAt,lifecyclePolicy})}}),evidence=validateCloseMode==="warn"?closeEvidenceRecovery(result.item,pmRoot):void 0;return{item:toItemRecord(result.item),changed_fields:result.changedFields,...evidence?{follow_up:{kind:"complete_close_evidence",missing:evidence.missing,suggested_command:evidence.suggested_retry,suggested_command_args:evidence.suggested_retry_args}}:{},warnings:[...result.warnings,...await autoUnblockResolvedDependents(pmRoot,settings,trackerItems,located.id,author,statusRegistry)]}}function runClose(id,closeReasonText,options,global2){return closeItem(id,closeReasonText,options,global2)}export{_testOnlyCloseCommand,closeItem,runClose};
 //# sourceMappingURL=close.js.map

package/dist/sdk/lifecycle/copy.d.ts

@@ -4,26 +4,26 @@ import type { ItemMetadata } from "../../types/index.js";
 /** Documents the copy options payload exchanged by command, SDK, and package integrations. */
 export interface CopyOptions {
 /** Value that configures or reports title for this contract. */
-title?: string;
+title?:string;
 /** Value that configures or reports author for this contract. */
-author?: string;
+author?:string;
 /** Human-readable explanation suitable for logs and agent-facing output. */
-message?: string;
+message?:string;
 /** Explicitly permit a likely duplicate when strict governance is enabled. */
-allowDuplicate?: boolean;
+allowDuplicate?:boolean;
 }
 /** Documents the copy result payload exchanged by command, SDK, and package integrations. */
 export interface CopyResult {
 /** Value that configures or reports source id for this contract. */
-source_id: string;
+source_id:string;
 /** Value that configures or reports item for this contract. */
-item: ItemMetadata;
+item:ItemMetadata;
 /** Value that configures or reports changed fields for this contract. */
-changed_fields: string[];
+changed_fields:string[];
 /** Value that configures or reports warnings for this contract. */
-warnings: string[];
+warnings:string[];
 /** Likely existing items found before the mutation committed. */
-similarity_advisory?: SimilarityAdvisory;
+similarity_advisory?:SimilarityAdvisory;
 }
 /** Implements run copy for the public runtime surface of this module. */
-export declare function runCopy(sourceId: string, options: CopyOptions, global: GlobalOptions): Promise<CopyResult>;
+export declare function runCopy(sourceId:string,options:CopyOptions,global:GlobalOptions):Promise<CopyResult>;

package/dist/sdk/lifecycle/core-field-recovery.d.ts

@@ -4,4 +4,4 @@
  */
 import type { PmCliErrorContext } from "../../core/shared/errors.js";
 /** Name only declared mutation routes; storage keys never imply CLI flags. */
-export declare function resolveCoreFieldRecovery(field: string): Pick<PmCliErrorContext, "recovery" | "nextSteps">;
+export declare function resolveCoreFieldRecovery(field:string):Pick<PmCliErrorContext,"recovery" | "nextSteps">;

package/dist/sdk/lifecycle/core-item-fields.d.ts

@@ -0,0 +1,6 @@
+/** Core item document fields; extension metadata retains its independently declared spelling. */
+export declare const CORE_ITEM_FIELD_KEYS:ReadonlySet<string>;
+/** Normalize only known core option targets; preserve unrelated extension metadata keys verbatim. */
+export declare function resolveCoreUpsertMetadataKey(key:string):string;
+/** Preserve an omitted key while normalizing a supplied core option target. */
+export declare function resolveCoreUpsertMetadataKey(key:string | undefined):string | undefined;

package/dist/sdk/lifecycle/core-item-fields.js

@@ -0,0 +1,2 @@
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="01728cbc-2037-50d2-8318-5f106714b8da")}catch{}})();import{ITEM_PROJECT_CONTEXT_KEYS}from"../../core/shared/constants.js";const CORE_ITEM_FIELD_KEYS=new Set(["id","title","description","type","status","priority","tags","body","deadline","estimated_minutes","acceptance_criteria","definition_of_ready","order","rank","assignee",...ITEM_PROJECT_CONTEXT_KEYS,"affected_version","fixed_version","component","regression","customer_impact","close_reason","completed_at","dependencies","comments","notes","learnings","files","tests","docs","reminders","events","type_options"]);function resolveCoreUpsertMetadataKey(key){if(key===void 0)return;const stored=key.replace(/[A-Z]/gu,letter=>`_${letter.toLowerCase()}`);return CORE_ITEM_FIELD_KEYS.has(stored)?stored:key}export{CORE_ITEM_FIELD_KEYS,resolveCoreUpsertMetadataKey};
+//# sourceMappingURL=core-item-fields.js.map