@unbrained/pm-cli 2026.10.14 → 2026.10.17

package/dist/sdk/graph/scheduling.d.ts

@@ -2,48 +2,48 @@ import { RelationshipGraph } from "../relationships.js";
 /** One scheduled task row with its earliest/latest window and total float. */
 export interface RelationshipScheduleRow {
 /** Scheduled task id. */
-id: string;
+id:string;
 /** Longest prerequisite distance from any source (earliest start). */
-earliestStart: number;
+earliestStart:number;
 /** Earliest start plus the unit task duration. */
-earliestFinish: number;
+earliestFinish:number;
 /** Latest start that still preserves the makespan. */
-latestStart: number;
+latestStart:number;
 /** Latest finish that still preserves the makespan. */
-latestFinish: number;
+latestFinish:number;
 /** Total float: latest start minus earliest start. */
-slack: number;
+slack:number;
 /** Whether the task has zero slack and lies on a critical path. */
-critical: boolean;
+critical:boolean;
 }
 /** Bounded schedule-analysis controls. */
 export interface GraphScheduleOptions {
 /** Abort signal checked once at entry, before the forward pass. */
-signal?: AbortSignal;
+signal?:AbortSignal;
 }
 /** Deterministic critical-path schedule of the order-bearing subgraph. */
 export interface RelationshipScheduleAnalysis {
 /** Whether the result is exact rather than sampled or approximate. */
-exact: true;
+exact:true;
 /** Whether the order-bearing graph is acyclic. */
-acyclic: boolean;
+acyclic:boolean;
 /** Total makespan in unit task durations; zero when nothing is scheduled. */
-makespan: number;
+makespan:number;
 /** Number of tasks participating in the order-bearing DAG. */
-scheduledCount: number;
+scheduledCount:number;
 /** Longest deterministic execution path — a canonical zero-slack chain. */
-criticalPath: string[];
+criticalPath:string[];
 /** Edge count of the critical path. */
-criticalPathLength: number;
+criticalPathLength:number;
 /** Genuine ordering cycles, excluded from scheduling. */
-cycles: string[][];
+cycles:string[][];
 /** Scheduled rows sorted by ascending slack, then earliest start, then id. */
-rows: RelationshipScheduleRow[];
+rows:RelationshipScheduleRow[];
 /** Semantic provenance for the analysis. */
-provenance: {
-algorithm: "critical-path-method";
-edgeFamily: "ordering";
-weighting: "unit";
+provenance:{
+algorithm:"critical-path-method";
+edgeFamily:"ordering";
+weighting:"unit";
 };
 }
 /**
@@ -56,4 +56,4 @@ weighting: "unit";
  * cycle, and tasks transitively gated by a cycle (excluded from Kahn's partial
  * order) are all omitted from `rows`; genuine cycles are reported in `cycles`.
  */
-export declare function analyzeRelationshipSchedule(graph: RelationshipGraph, options?: GraphScheduleOptions): RelationshipScheduleAnalysis;
+export declare function analyzeRelationshipSchedule(graph:RelationshipGraph,options?:GraphScheduleOptions):RelationshipScheduleAnalysis;

package/dist/sdk/graph/traversal.d.ts

@@ -8,41 +8,41 @@
  * reports exact cost and truncation metadata so agents can budget follow-up
  * calls without re-reading the workspace.
  */
-import { RelationshipGraph, type RelationshipEdge, type RelationshipKindDefinition, type RelationshipQueryOptions, type RelationshipQueryResult } from "../relationships.js";
+import { RelationshipGraph,type RelationshipEdge,type RelationshipKindDefinition,type RelationshipQueryOptions,type RelationshipQueryResult } from "../relationships.js";
 /**
  * Shared bounded-traversal controls extended with deterministic resumption.
  * Semantic hierarchy and ordering orientation comes from the relationship-kind
  * registry, so callers cannot supply the generic graph `direction` option.
  */
-export interface GraphTraversalOptions extends Omit<RelationshipQueryOptions, "direction"> {
+export interface GraphTraversalOptions extends Omit<RelationshipQueryOptions,"direction"> {
 /**
      * Resume emission after this previously returned node identifier. The
      * traversal re-walks the same deterministic sequence and starts emitting
      * after the cursor node; an identifier the sequence never reaches fails fast
      * instead of silently returning an empty page.
      */
-after?: string;
+after?:string;
 }
 /** One enumerated simple path between two nodes. */
 export interface RelationshipPath {
 /** Ordered node identifiers from source to target inclusive. */
-nodes: string[];
+nodes:string[];
 /** Edges connecting consecutive path nodes, in traversal order. */
-edges: RelationshipEdge[];
+edges:RelationshipEdge[];
 /** Number of edges in the path. */
-length: number;
+length:number;
 }
 /** Bounded-path enumeration controls. */
 export interface GraphPathOptions extends RelationshipQueryOptions {
 /** Maximum number of returned paths; defaults to 5. */
-maxPaths?: number;
+maxPaths?:number;
 /** Safety bound on expanded partial paths before truncation; defaults to 10000. */
-maxVisitedPaths?: number;
+maxVisitedPaths?:number;
 }
 /** Endpoint of a hierarchy edge that represents the structural parent. */
-export declare function hierarchyParentEndpoint(edge: RelationshipEdge, definition: RelationshipKindDefinition): string;
+export declare function hierarchyParentEndpoint(edge:RelationshipEdge,definition:RelationshipKindDefinition):string;
 /** Endpoint of an ordering edge that must finish first. */
-export declare function orderingPredecessorEndpoint(edge: RelationshipEdge, definition: RelationshipKindDefinition): string;
+export declare function orderingPredecessorEndpoint(edge:RelationshipEdge,definition:RelationshipKindDefinition):string;
 /**
  * Orient one ordering edge into its execution direction — the predecessor that
  * must finish first and the successor it gates — honoring the kind's declared
@@ -50,39 +50,39 @@ export declare function orderingPredecessorEndpoint(edge: RelationshipEdge, defi
  * single ordering-orientation primitive shared by scheduling and degree
  * analytics.
  */
-export declare function orientOrderingEdge(edge: RelationshipEdge, definition: RelationshipKindDefinition): {
-predecessor: string;
-successor: string;
+export declare function orientOrderingEdge(edge:RelationshipEdge,definition:RelationshipKindDefinition):{
+predecessor:string;
+successor:string;
 };
 /**
  * Return the bounded transitive hierarchy ancestors of one node in
  * breadth-first discovery order, honoring each hierarchy kind's declared
  * parent endpoint (so `parent` and inverse `child` spellings agree).
  */
-export declare function hierarchyAncestors(graph: RelationshipGraph, id: string, options?: GraphTraversalOptions): RelationshipQueryResult<string[]>;
+export declare function hierarchyAncestors(graph:RelationshipGraph,id:string,options?:GraphTraversalOptions):RelationshipQueryResult<string[]>;
 /**
  * Return the bounded transitive hierarchy descendants of one node in
  * breadth-first discovery order, honoring each hierarchy kind's declared
  * parent endpoint.
  */
-export declare function hierarchyDescendants(graph: RelationshipGraph, id: string, options?: GraphTraversalOptions): RelationshipQueryResult<string[]>;
+export declare function hierarchyDescendants(graph:RelationshipGraph,id:string,options?:GraphTraversalOptions):RelationshipQueryResult<string[]>;
 /**
  * Return the bounded transitive execution predecessors of one node — the work
  * that must finish before it — in breadth-first discovery order, honoring each
  * ordering kind's declared precedence (so `blocked_by` and inverse `blocks`
  * spellings agree).
  */
-export declare function orderingPredecessors(graph: RelationshipGraph, id: string, options?: GraphTraversalOptions): RelationshipQueryResult<string[]>;
+export declare function orderingPredecessors(graph:RelationshipGraph,id:string,options?:GraphTraversalOptions):RelationshipQueryResult<string[]>;
 /**
  * Return the bounded transitive execution successors of one node — the work
  * this node gates — in breadth-first discovery order, honoring each ordering
  * kind's declared precedence.
  */
-export declare function orderingSuccessors(graph: RelationshipGraph, id: string, options?: GraphTraversalOptions): RelationshipQueryResult<string[]>;
+export declare function orderingSuccessors(graph:RelationshipGraph,id:string,options?:GraphTraversalOptions):RelationshipQueryResult<string[]>;
 /**
  * Enumerate bounded simple paths between two nodes, shortest first and
  * lexicographic within equal length. Traversal honors direction and kind
  * filters, caps returned paths, and reports truncation when depth, path-count,
  * or the expansion-safety bound stops the search early.
  */
-export declare function enumerateRelationshipPaths(graph: RelationshipGraph, source: string, target: string, options?: GraphPathOptions): RelationshipQueryResult<RelationshipPath[]>;
+export declare function enumerateRelationshipPaths(graph:RelationshipGraph,source:string,target:string,options?:GraphPathOptions):RelationshipQueryResult<RelationshipPath[]>;

package/dist/sdk/graph/workspace-relationship-kind-registry.d.ts

@@ -5,4 +5,4 @@ import { type RelationshipKindRegistry } from "../relationships.js";
  * Callers that omit an explicit registry must still recognize extension-owned
  * hierarchy and ordering kinds instead of silently falling back to built-ins.
  */
-export declare function resolveWorkspaceRelationshipKindRegistry(): RelationshipKindRegistry;
+export declare function resolveWorkspaceRelationshipKindRegistry():RelationshipKindRegistry;

package/dist/sdk/guide-topics.d.ts

@@ -1,47 +1,47 @@
 /** Describes one documentation file surfaced by a progressive-disclosure guide topic. */
 export interface GuideDocReference {
 /** Filesystem path used for path resolution. */
-path: string;
+path:string;
 /** Value that configures or reports purpose for this contract. */
-purpose: string;
+purpose:string;
 /** Value that configures or reports optional for this contract. */
-optional?: boolean;
+optional?:boolean;
 }
 /** Documents the guide workflow template payload exchanged by command, SDK, and package integrations. */
 export interface GuideWorkflowTemplate {
 /** Value that configures or reports name for this contract. */
-name: string;
+name:string;
 /** Value that configures or reports goal for this contract. */
-goal: string;
+goal:string;
 /** Value that configures or reports prompt for this contract. */
-prompt: string;
+prompt:string;
 /** Value that configures or reports commands for this contract. */
-commands: string[];
+commands:string[];
 }
 /** Documents the guide topic definition payload exchanged by command, SDK, and package integrations. */
 export interface GuideTopicDefinition {
 /** Stable identifier used to reference this record across commands and storage. */
-id: string;
+id:string;
 /** Value that configures or reports aliases for this contract. */
-aliases: string[];
+aliases:string[];
 /** Value that configures or reports title for this contract. */
-title: string;
+title:string;
 /** Value that configures or reports summary for this contract. */
-summary: string;
+summary:string;
 /** Value that configures or reports intent for this contract. */
-intent: string;
+intent:string;
 /** Value that configures or reports commands for this contract. */
-commands: string[];
+commands:string[];
 /** Value that configures or reports workflows for this contract. */
-workflows: GuideWorkflowTemplate[];
+workflows:GuideWorkflowTemplate[];
 /** Value that configures or reports docs for this contract. */
-docs: GuideDocReference[];
+docs:GuideDocReference[];
 /** Value that configures or reports related for this contract. */
-related: string[];
+related:string[];
 }
 /** Implements list guide topics for the public runtime surface of this module. */
-export declare function listGuideTopics(): GuideTopicDefinition[];
+export declare function listGuideTopics():GuideTopicDefinition[];
 /** Implements list guide topic ids for the public runtime surface of this module. */
-export declare function listGuideTopicIds(): string[];
+export declare function listGuideTopicIds():string[];
 /** Implements resolve guide topic for the public runtime surface of this module. */
-export declare function resolveGuideTopic(rawTopic: string | undefined): GuideTopicDefinition | null;
+export declare function resolveGuideTopic(rawTopic:string | undefined):GuideTopicDefinition | null;

package/dist/sdk/guide-topics.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]="f5ba86ac-336e-5fdb-a8fb-d8d7e7c1a504")}catch{}})();import{listPmCommandCapabilityGroups}from"./agent-capability-contracts.js";function normalizeTopicToken(value){return value.trim().toLowerCase().replaceAll("_","-")}const GUIDE_TOPICS=[{id:"capabilities",aliases:["capability-map","families","routing"],title:"Generated Capability Routing",summary:"Route work through command families generated from the canonical agent capability contract.",intent:"Use this as the drift-free entrypoint when selecting a CLI, MCP, completion, documentation, or extension command surface.",commands:listPmCommandCapabilityGroups().flatMap(({commands})=>commands.map(command=>`pm ${command}`)),workflows:[],docs:[{path:"docs/generated/AGENT_CAPABILITY_ROUTING.md",purpose:"Generated command-to-family routing table."},{path:"docs/generated/AGENT_COMMAND_SURFACE.md",purpose:"Generated visibility-tier and family table."}],related:["commands","workflows","extensions"]},{id:"quickstart",aliases:["start","getting-started","bootstrap"],title:"Quickstart",summary:"Initialize a tracker and run the shortest safe plan -> execute -> close loop.",intent:"Use this when a human or agent needs to start productive work quickly with minimal context load.",commands:["pm workspace init","pm workspace config --help","pm workspace schema --help","pm workspace profile --help","pm context --limit 10","pm list --status open --limit 20",'pm create --create-mode progressive --title "..." --description "..." --type Task',"pm claim <ID>","pm update <ID> --status in_progress",'pm close <ID> "<reason with evidence>" --validate-close warn'],workflows:[{name:"Start Session Safely",goal:"Bootstrap without mutating unrelated state.",prompt:"You are bootstrapping pm work. Use a token-efficient context snapshot first, then select one open item, claim it, and only then mutate.",commands:["pm context --limit 10","pm list --status open --limit 20","pm claim <ID>"]}],docs:[{path:"README.md",purpose:"High-level project and install entrypoint."},{path:"docs/QUICKSTART.md",purpose:"Short setup and first-command walkthrough."},{path:"docs/COMMANDS.md",purpose:"Task-oriented command recipes."}],related:["commands","workflows","release"]},{id:"commands",aliases:["cli","operations","reference"],title:"CLI Command Routing",summary:"Find the right command family quickly and use command-scoped help/contracts output.",intent:"Use this when selecting command paths, flags, and output formats for implementation or automation.",commands:["pm --help","pm <command> --help","pm <command> --help --explain","pm contracts --command <command> --flags-only","pm contracts --command <command> --availability-only --runtime-only","pm completion <bash|zsh|fish>"],workflows:[{name:"Flag Discovery",goal:"Resolve command flags deterministically before mutations.",prompt:"You are preparing to run a command. Use help and contracts surfaces to verify required/optional flags before execution.",commands:["pm <command> --help --explain","pm contracts --command <command> --flags-only"]}],docs:[{path:"docs/COMMANDS.md",purpose:"Command grouping and examples."},{path:"docs/CONFIGURATION.md",purpose:"Project/global settings and policy controls."},{path:"docs/TESTING.md",purpose:"Linked-test orchestration and safety guidance."}],related:["quickstart","workflows","sdk","extensions"]},{id:"workflows",aliases:["developer","maintainer","agent"],title:"Developer and Agent Workflows",summary:"Apply canonical claim -> execute -> verify -> close workflows with append-only evidence.",intent:"Use this for day-to-day coding-agent execution loops and handoff-safe updates.",commands:["pm claim <ID>","pm update <ID> --status in_progress","pm files <ID> --add ...","pm test <ID> --add ...",'pm comments <ID> "..."',"pm validate --check-resolution --check-history-drift","pm release <ID>"],workflows:[{name:"Execution Loop",goal:"Keep code, tests, and tracker evidence synchronized.",prompt:"You are implementing a scoped change. Claim first, link files/tests/docs as you go, append evidence comments, and close only after validation.",commands:["pm claim <ID>","pm update <ID> --status in_progress","pm files <ID> --add path=<file>,scope=project","pm test <ID> --run --progress",'pm close <ID> "<evidence>" --validate-close warn']}],docs:[{path:"AGENTS.md",purpose:"Repository operating rules and required workflow."},{path:"docs/AGENT_GUIDE.md",purpose:"Agent-oriented usage and context strategy."},{path:"docs/TESTING.md",purpose:"Sandbox-safe test execution rules."}],related:["quickstart","commands","skills"]},{id:"sdk",aliases:["api","typescript-sdk"],title:"SDK and Integrations",summary:"Use the published SDK surface for extension authoring and contract-safe integrations.",intent:"Use this when building or reviewing programmatic integrations against @unbrained/pm-cli/sdk.",commands:["pm contracts --schema-only","pm contracts --command extension --flags-only","pm contracts --runtime-only --availability-only"],workflows:[{name:"Integration Contract Check",goal:"Confirm action schemas and runtime availability before coding.",prompt:"You are wiring an integration. Capture schema + runtime availability first, then map your adapter payload fields to contract keys.",commands:["pm contracts --schema-only","pm contracts --availability-only --runtime-only","pm contracts --command <command> --flags-only"]}],docs:[{path:"docs/SDK.md",purpose:"Public SDK exports and extension authoring references."},{path:"docs/ARCHITECTURE.md",purpose:"Core runtime composition and extension load flow."}],related:["extensions","commands"]},{id:"extensions",aliases:["plugins","extension-authoring","packages","package-authoring"],title:"Packages and Extensions",summary:"Install, author, and diagnose packages/extensions with deterministic lifecycle controls.",intent:"Use this for package management, extension capability registration, and runtime diagnostics.",commands:["pm package install <target> --project","pm package upgrade --dry-run","pm package explore --project","pm package manage --detail summary","pm package doctor --detail deep","pm package activate <target> --project","pm package deactivate <target> --project"],workflows:[{name:"Lifecycle Triage",goal:"Diagnose extension state before forceful lifecycle actions.",prompt:"You are debugging package behavior. Inspect managed state first, then run doctor diagnostics, then apply install/adopt/activate actions.",commands:["pm package explore --project","pm package manage --detail summary","pm package doctor --detail deep","pm package upgrade --packages-only --dry-run"]}],docs:[{path:"docs/EXTENSIONS.md",purpose:"Capability model and lifecycle command usage."},{path:"docs/examples/starter-extension/README.md",purpose:"Starter extension scaffold and local development path."},{path:"docs/SDK.md",purpose:"SDK contracts used by extension implementations."}],related:["sdk","commands","skills"]},{id:"skills",aliases:["agent-skills","agentskills"],title:"Agent Skills",summary:"Skill bundles for developer, user, extensions, and sdk workflows aligned to the current CLI.",intent:"Use this when an agent needs reproducible prompts/workflows with strict compatibility metadata.",commands:["pm guide skills --depth deep","pm contracts --command guide --flags-only","pm validate --check-command-references"],workflows:[{name:"Skill Selection",goal:"Pick the narrowest compatible skill first to minimize context usage.",prompt:"Select a pm skill based on the task intent, then execute only the workflow section needed for the current change.",commands:["pm guide skills","pm guide skills --depth deep"]}],docs:[{path:"docs/AGENT_GUIDE.md",purpose:"Agent-first usage and context model."},{path:"docs/README.md",purpose:"Documentation routing with progressive disclosure."},{path:".agents/skills/README.md",purpose:"Agent skills index and routing overview."},{path:".agents/skills/pm-developer/SKILL.md",purpose:"Developer-oriented pm skill workflow."},{path:".agents/skills/pm-user/SKILL.md",purpose:"User/operator pm skill workflow."},{path:".agents/skills/pm-extensions/SKILL.md",purpose:"Extension-focused pm skill workflow."},{path:".agents/skills/pm-sdk/SKILL.md",purpose:"SDK integration pm skill workflow."}],related:["workflows","harnesses","commands"]},{id:"harnesses",aliases:["compatibility","agent-compatibility"],title:"Agent Harness Compatibility",summary:"Cross-harness compatibility guidance for docs routing.",intent:"Use this when adapting pm docs and SDK contracts for an external automation harness.",commands:["pm guide skills","pm guide commands","pm contracts --runtime-only --availability-only"],workflows:[{name:"Harness Mapping",goal:"Route each harness to the same canonical skill/docs sources.",prompt:"Map harness-specific entrypoints to the same pm guide topics and .agents/skills workflows without adding runtime harness-specific code.",commands:["pm guide harnesses --depth standard","pm guide skills --depth deep"]}],docs:[{path:"docs/AGENT_GUIDE.md",purpose:"Agent context and output-mode conventions."},{path:"docs/README.md",purpose:"Single-source documentation routing entrypoint."},{path:".agents/skills/HARNESS_COMPATIBILITY.md",purpose:"Harness compatibility matrix and usage notes."}],related:["skills","workflows"]},{id:"release",aliases:["gates","ship","release-readiness"],title:"Release and Staleness Gates",summary:"Run release gates and docs/skills freshness checks before publishing.",intent:"Use this when validating release readiness and preventing docs/skills drift.",commands:["pnpm build","pnpm test:coverage","pnpm quality:static","node scripts/release/run-gates.mjs --telemetry-mode best-effort","pnpm security:scan"],workflows:[{name:"Pre-Release Gate Sweep",goal:"Ensure code, docs, and skills are all green before publish.",prompt:"Run release gates in deterministic order and treat docs/skills freshness failures as release blockers.",commands:["pnpm build","pnpm test:coverage","node scripts/release/run-gates.mjs --telemetry-mode best-effort"]}],docs:[{path:"docs/RELEASING.md",purpose:"Release flow and safety checks."},{path:"CHANGELOG.md",purpose:"Versioned release history and unreleased notes."},{path:"scripts/release/run-gates.mjs",purpose:"Source of truth for release gate ordering."}],related:["commands","skills","workflows"]},{id:"tokens",aliases:["output","budget","context-cost","projections"],title:"Read Output and Token Budgets",summary:"Bound what a read costs before it is emitted, and resume the part a budget withheld.",intent:"Use this when an agent must keep context small: every read declares a token ceiling, degrades deterministically, and reports what it omitted.",commands:["pm contracts --summary --json","pm list --status open --output-limit 20","pm get <ID> --output-include id,title,status,dependencies","pm context --limit 10 --token-accounting","pm notes <ID> --output-cursor <cursor>","pm list --status closed --output-budget unbounded"],workflows:[{name:"Bound A Read Before Emitting It",goal:"Never pay for rows the task does not need.",prompt:"Choose the narrowest projection first, then a row limit, then a token budget. Read the omission receipt before concluding the result is complete.",commands:["pm contracts --command list --flags-only --json","pm list --status open --output-limit 20 --output-format toon","pm list --status open --token-accounting"]},{name:"Recover A Truncated Read",goal:"Continue a bounded read instead of re-running it unbounded.",prompt:"When output_budget_truncation appears, prefer the declared continuation cursor. Only widen the budget when the response declares no cursor.",commands:["pm notes <ID> --output-cursor <cursor>","pm get <ID> --output-budget 20000"]}],docs:[{path:"docs/READ_OUTPUT_CONTRACTS.md",purpose:"Budget, truncation, continuation, and omission receipts."},{path:"docs/OUTPUT_PROJECTION_CONTRACTS.md",purpose:"Field and section projection grammar for every read."},{path:"docs/OUTPUT_TOKEN_ACCOUNTING.md",purpose:"Per-section token cost receipts."},{path:"docs/ITEM_READ_PROJECTIONS.md",purpose:"Item-level projection defaults and restore hints."}],related:["commands","workflows","quickstart"]},{id:"graph",aliases:["relationships","deps","dependencies","analytics"],title:"Relationship Graph and Planning Analytics",summary:"Type the relationships between items, then read the project as a graph rather than as a list.",intent:"Use this when the question is about lineage, ordering, blast radius, bottlenecks, or which work reaches a declared outcome.",commands:["pm deps <ID>",'pm update <ID> --dep "id=<other>,kind=implements"',"pm graph analyze","pm graph impact <ID> --direction downstream","pm graph paths <ID> <ID>","pm graph audit"],workflows:[{name:"Place New Work In The Ladder",goal:"Every item resolves to an outcome through a typed, explainable path.",prompt:"Set parent lineage first, then add typed edges that cite durable evidence. Never add an edge to satisfy a count.",commands:['pm search "<topic>" --limit 10','pm update <ID> --dep "id=<parent-goal>,kind=implements"',"pm graph ancestors <ID>"]},{name:"Assess Blast Radius Before Changing Something",goal:"Know what derives from an item before touching it.",prompt:"Walk the directed graph downstream from the item, then check whether any bottleneck node sits on the path.",commands:["pm graph impact <ID> --direction downstream","pm graph dominators <ID>","pm graph articulation"]}],docs:[{path:"docs/RELATIONSHIP_GRAPH.md",purpose:"Graph model, traversal verbs, and analytics surface."},{path:"docs/DEPENDENCY_KIND_CONTRACT.md",purpose:"Every typed edge kind, its direction, and its semantics."}],related:["commands","workflows","assurance"]},{id:"assurance",aliases:["gates","invariants","measurements","quality"],title:"Declared Invariants and Gates",summary:"Express a project's own quality rules as tracked data the SDK evaluates, instead of as scripts.",intent:"Use this when a rule must hold over the record itself \u2014 a floor, a ceiling, or a monotone property \u2014 and must fail closed in CI.",commands:["pm assurance list","pm assurance run <gate-id> --trigger ci --dry-run","pm validate --check-resolution --check-history-drift","pm health --summary"],workflows:[{name:"Add An Invariant Rather Than A Script",goal:"A new enforcement gap becomes declared data, not a new bespoke gate script.",prompt:"Define the measurement, bind an assertion with an explicit bound and polarity, prove a negative control, then attach it to a trigger.",commands:["pm assurance list --json","pm assurance run <gate-id> --trigger ci --dry-run --json"]},{name:"Read A Verdict Before Believing It",goal:"Know which population a passing assertion speaks for.",prompt:"Read population_size and scope on every assertion. A gate that cannot fail for the reason it exists is not evidence.",commands:["pm assurance run <gate-id> --trigger ci --dry-run --json --output-budget unbounded"]}],docs:[{path:"docs/ASSURANCE.md",purpose:"Measurement, assertion, gate, and trigger vocabulary."},{path:"docs/MUTATION_INTEGRITY.md",purpose:"What every mutation must record to remain provable."}],related:["release","graph","workflows"]},{id:"merge",aliases:["branches","concurrency","multi-agent","fleet"],title:"Branching, Merging, and Concurrent Agents",summary:"Keep tracker data and history conflict-free while many agents work on separate branches.",intent:"Use this when more than one agent or worktree mutates the same tracker and the results must merge without hand resolution.",commands:["pm merge install","pm merge report","pm merge reconcile --dry-run","pm claim <ID>","pm release <ID>","pm validate --check-history-drift","pm health --check-only"],workflows:[{name:"Prepare A Clone For Field-Aware Merges",goal:"The committed merge fence needs clone-local driver configuration once.",prompt:"Run the merge installer in every fresh clone or worktree before the first branch merge of tracker data.",commands:["pm merge install","pm health --check-only"]},{name:"Settle A Merge Before Trusting Health",goal:"A lossless merge still leaves pending receipts that strict health reports until they are reconciled.",prompt:"After any branch merge that touched tracker data, read the merge report, preview the reconciliation, then apply it; only then treat a health verdict as a statement about the data.",commands:["pm merge report","pm merge reconcile --dry-run",'pm merge reconcile --message "Post-merge history reconciliation"',"pm health --check-only"]},{name:"Hand Work Between Agents Safely",goal:"Ownership and evidence survive the handoff.",prompt:"Claim before substantial edits, record evidence as comments, and release the claim when pausing, handing off, closing, or canceling.",commands:["pm claim <ID>",'pm comments <ID> "Handoff: <state and next step>"',"pm release <ID>"]}],docs:[{path:"docs/MERGE_SAFETY.md",purpose:"Merge driver, field-aware resolution, and clone setup."},{path:"docs/SDK_CONTEXT_COORDINATION.md",purpose:"Coordination primitives for concurrent agents."}],related:["workflows","assurance","commands"]},{id:"evidence",aliases:["record","annotations","learnings","history-maintenance"],title:"Evidence, Durable Knowledge, and Record Maintenance",summary:"Append comments, notes, learnings, files, docs, and tests to items, and maintain the immutable history those records live in.",intent:"Use this when work must be explained to the next agent, when a durable lesson should outlive the item, or when a history stream needs verification, repair, redaction, compaction, or author attribution.",commands:['pm comments <ID> "<progress or verification evidence>"','pm notes <ID> --add "<rationale that belongs on the item>"','pm learnings <ID> --add "<lesson that should outlive the item>"',"pm append <ID> --body -","pm files <ID> --add path=<path>,scope=project,note=<why>","pm history <ID> --verify --strict-exit","pm history-repair --all --dry-run","pm history-redact <ID> --literal <secret> --dry-run","pm history-compact <ID> --dry-run","pm history-author-acknowledge --all-actionable --dry-run","pm close-many --ids <ID>,<ID> --reason <text> --dry-run","pm test-all --status open --limit 10 --progress"],workflows:[{name:"Record While Working, Not After",goal:"Another agent can rebuild the full situation from the item alone.",prompt:"Add a comment for each verified step, a note for each rationale the item body does not carry, and a learning for each lesson that applies beyond this item. Prefer appending over rewriting.",commands:['pm comments <ID> "Evidence: <what changed and what passed>"','pm notes <ID> --add "Decision log: <why this shape>"','pm learnings <ID> --add "<durable lesson>"',"pm learnings <ID> --limit 5"]},{name:"Verify And Repair A History Stream",goal:"Every mutation stays provable and the chain re-anchors after drift.",prompt:"Verify the chain with a strict exit before trusting a stream, preview any repair, and record why the repair was needed in the audit message.",commands:["pm history <ID> --verify --strict-exit","pm history-repair --all --dry-run",'pm history-repair --all --message "<why the chain drifted>"',"pm validate --check-history-drift"]},{name:"Redact, Compact, Or Attribute Without Losing Proof",goal:"Sensitive text, stream length, and unknown authors are handled through audited rewrites.",prompt:"Preview every history rewrite with --dry-run, read the receipt, then apply. Compaction renumbers ordinal versions, so record the checkpoint it created.",commands:["pm history-redact <ID> --literal <secret> --dry-run","pm history-compact <ID> --dry-run","pm history-author-acknowledge --all-actionable --dry-run"]}],docs:[{path:"docs/COMMANDS.md",purpose:"Annotation, bulk, and history-and-recovery command families."},{path:"docs/MUTATION_INTEGRITY.md",purpose:"Provenance and content-safety policy every mutation shares."},{path:"docs/AGENT_GUIDE.md",purpose:"Evidence expectations in the agent loop and self-repair remediation."}],related:["workflows","assurance","merge","graph"]},{id:"automation",aliases:["calendar","reminders","meetings","events"],title:"Reminders, Events, and Meetings",summary:"Attach time to items so context and agenda views can surface deadlines, meetings, and reminders when they matter.",intent:"Use this when an item needs a due signal, a scheduled event, or a meeting record that later context reads should surface.",commands:["pm package install calendar --project","pm calendar remind <title> --at <when> --parent <ID>","pm calendar event <title> --start <when> --parent <ID>","pm calendar meet <title> --start <when> --duration 30min --parent <ID>","pm context --limit 10"],workflows:[{name:"Put A Deadline Where Context Will Find It",goal:"Time-bound work surfaces in the agenda section of context reads.",prompt:"Install calendar, then record the reminder or event under its owning item and confirm it in context. Use explicit min or mo for durations; bare m is ambiguous.",commands:["pm package install calendar --project","pm calendar remind <title> --at <when> --parent <ID>","pm context --limit 10"]}],docs:[{path:"docs/COMMANDS.md",purpose:"Calendar and context command family."},{path:"packages/pm-calendar/README.md",purpose:"Package commands, duration units, and compatibility aliases."}],related:["workflows","quickstart","extensions"]}],TOPIC_BY_TOKEN=new Map;for(const topic of GUIDE_TOPICS){TOPIC_BY_TOKEN.set(topic.id,topic);for(const alias of topic.aliases)TOPIC_BY_TOKEN.set(alias,topic)}function listGuideTopics(){return GUIDE_TOPICS.map(topic=>({...topic,aliases:[...topic.aliases],commands:[...topic.commands],workflows:topic.workflows.map(workflow=>({...workflow,commands:[...workflow.commands]})),docs:topic.docs.map(doc=>({...doc})),related:[...topic.related]}))}function listGuideTopicIds(){return GUIDE_TOPICS.map(topic=>topic.id)}function resolveGuideTopic(rawTopic){if(!rawTopic)return null;const normalized=normalizeTopicToken(rawTopic);return normalized?TOPIC_BY_TOKEN.get(normalized)??null:null}export{listGuideTopicIds,listGuideTopics,resolveGuideTopic};
+(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]="5917df84-25e1-5ce2-9203-746f92bb4037")}catch{}})();import{listPmCommandCapabilityGroups}from"./agent-capability-contracts.js";function normalizeTopicToken(value){return value.trim().toLowerCase().replaceAll("_","-")}const GUIDE_TOPICS=[{id:"capabilities",aliases:["capability-map","families","routing"],title:"Generated Capability Routing",summary:"Route work through command families generated from the canonical agent capability contract.",intent:"Use this as the drift-free entrypoint when selecting a CLI, MCP, completion, documentation, or extension command surface.",commands:listPmCommandCapabilityGroups().flatMap(({commands})=>commands.map(command=>`pm ${command}`)),workflows:[],docs:[{path:"docs/generated/AGENT_CAPABILITY_ROUTING.md",purpose:"Generated command-to-family routing table."},{path:"docs/generated/AGENT_COMMAND_SURFACE.md",purpose:"Generated visibility-tier and family table."}],related:["commands","workflows","extensions"]},{id:"quickstart",aliases:["start","getting-started","bootstrap"],title:"Quickstart",summary:"Initialize a tracker and run the shortest safe plan -> execute -> close loop.",intent:"Use this when a human or agent needs to start productive work quickly with minimal context load.",commands:["pm workspace init","pm workspace config --help","pm workspace schema --help","pm workspace profile --help","pm context --limit 10","pm list --status open --limit 20",'pm create --create-mode progressive --title "..." --description "..." --type Task',"pm claim <ID>","pm update <ID> --status in_progress",'pm close <ID> "<reason>" --resolution "<change>" --expected "<expected outcome>" --actual "<observed outcome>" --validate-close warn'],workflows:[{name:"Start Session Safely",goal:"Bootstrap without mutating unrelated state.",prompt:"You are bootstrapping pm work. Use a token-efficient context snapshot first, then select one open item, claim it, and only then mutate.",commands:["pm context --limit 10","pm list --status open --limit 20","pm claim <ID>"]}],docs:[{path:"README.md",purpose:"High-level project and install entrypoint."},{path:"docs/QUICKSTART.md",purpose:"Short setup and first-command walkthrough."},{path:"docs/COMMANDS.md",purpose:"Task-oriented command recipes."}],related:["commands","workflows","release"]},{id:"commands",aliases:["cli","operations","reference"],title:"CLI Command Routing",summary:"Find the right command family quickly and use command-scoped help/contracts output.",intent:"Use this when selecting command paths, flags, and output formats for implementation or automation.",commands:["pm --help","pm <command> --help","pm <command> --help --explain","pm contracts --command <command> --flags-only","pm contracts --command <command> --availability-only --runtime-only","pm completion <bash|zsh|fish>"],workflows:[{name:"Flag Discovery",goal:"Resolve command flags deterministically before mutations.",prompt:"You are preparing to run a command. Use help and contracts surfaces to verify required/optional flags before execution.",commands:["pm <command> --help --explain","pm contracts --command <command> --flags-only"]}],docs:[{path:"docs/COMMANDS.md",purpose:"Command grouping and examples."},{path:"docs/CONFIGURATION.md",purpose:"Project/global settings and policy controls."},{path:"docs/TESTING.md",purpose:"Linked-test orchestration and safety guidance."}],related:["quickstart","workflows","sdk","extensions"]},{id:"workflows",aliases:["developer","maintainer","agent"],title:"Developer and Agent Workflows",summary:"Apply canonical claim -> execute -> verify -> close workflows with append-only evidence.",intent:"Use this for day-to-day coding-agent execution loops and handoff-safe updates.",commands:["pm claim <ID>","pm update <ID> --status in_progress","pm files <ID> --add ...","pm test <ID> --add ...",'pm comments <ID> "..."',"pm validate --check-resolution --check-history-drift","pm release <ID>"],workflows:[{name:"Execution Loop",goal:"Keep code, tests, and tracker evidence synchronized.",prompt:"You are implementing a scoped change. Claim first, link files/tests/docs as you go, append evidence comments, and close only after validation.",commands:["pm claim <ID>","pm update <ID> --status in_progress","pm files <ID> --add path=<file>,scope=project","pm test <ID> --run --progress",'pm close <ID> "<reason>" --resolution "<change>" --expected "<expected outcome>" --actual "<observed outcome>" --validate-close warn']}],docs:[{path:"AGENTS.md",purpose:"Repository operating rules and required workflow."},{path:"docs/AGENT_GUIDE.md",purpose:"Agent-oriented usage and context strategy."},{path:"docs/TESTING.md",purpose:"Sandbox-safe test execution rules."}],related:["quickstart","commands","skills"]},{id:"sdk",aliases:["api","typescript-sdk"],title:"SDK and Integrations",summary:"Use the published SDK surface for extension authoring and contract-safe integrations.",intent:"Use this when building or reviewing programmatic integrations against @unbrained/pm-cli/sdk.",commands:["pm contracts --schema-only","pm contracts --command extension --flags-only","pm contracts --runtime-only --availability-only"],workflows:[{name:"Integration Contract Check",goal:"Confirm action schemas and runtime availability before coding.",prompt:"You are wiring an integration. Capture schema + runtime availability first, then map your adapter payload fields to contract keys.",commands:["pm contracts --schema-only","pm contracts --availability-only --runtime-only","pm contracts --command <command> --flags-only"]}],docs:[{path:"docs/SDK.md",purpose:"Public SDK exports and extension authoring references."},{path:"docs/ARCHITECTURE.md",purpose:"Core runtime composition and extension load flow."}],related:["extensions","commands"]},{id:"extensions",aliases:["plugins","extension-authoring","packages","package-authoring"],title:"Packages and Extensions",summary:"Install, author, and diagnose packages/extensions with deterministic lifecycle controls.",intent:"Use this for package management, extension capability registration, and runtime diagnostics.",commands:["pm package install <target> --project","pm package upgrade --dry-run","pm package explore --project","pm package manage --detail summary","pm package doctor --detail deep","pm package activate <target> --project","pm package deactivate <target> --project"],workflows:[{name:"Lifecycle Triage",goal:"Diagnose extension state before forceful lifecycle actions.",prompt:"You are debugging package behavior. Inspect managed state first, then run doctor diagnostics, then apply install/adopt/activate actions.",commands:["pm package explore --project","pm package manage --detail summary","pm package doctor --detail deep","pm package upgrade --packages-only --dry-run"]}],docs:[{path:"docs/EXTENSIONS.md",purpose:"Capability model and lifecycle command usage."},{path:"docs/examples/starter-extension/README.md",purpose:"Starter extension scaffold and local development path."},{path:"docs/SDK.md",purpose:"SDK contracts used by extension implementations."}],related:["sdk","commands","skills"]},{id:"skills",aliases:["agent-skills","agentskills"],title:"Agent Skills",summary:"Skill bundles for developer, user, extensions, and sdk workflows aligned to the current CLI.",intent:"Use this when an agent needs reproducible prompts/workflows with strict compatibility metadata.",commands:["pm guide skills --depth deep","pm contracts --command guide --flags-only","pm validate --check-command-references"],workflows:[{name:"Skill Selection",goal:"Pick the narrowest compatible skill first to minimize context usage.",prompt:"Select a pm skill based on the task intent, then execute only the workflow section needed for the current change.",commands:["pm guide skills","pm guide skills --depth deep"]}],docs:[{path:"docs/AGENT_GUIDE.md",purpose:"Agent-first usage and context model."},{path:"docs/README.md",purpose:"Documentation routing with progressive disclosure."},{path:".agents/skills/README.md",purpose:"Agent skills index and routing overview."},{path:".agents/skills/pm-developer/SKILL.md",purpose:"Developer-oriented pm skill workflow."},{path:".agents/skills/pm-user/SKILL.md",purpose:"User/operator pm skill workflow."},{path:".agents/skills/pm-extensions/SKILL.md",purpose:"Extension-focused pm skill workflow."},{path:".agents/skills/pm-sdk/SKILL.md",purpose:"SDK integration pm skill workflow."}],related:["workflows","harnesses","commands"]},{id:"harnesses",aliases:["compatibility","agent-compatibility"],title:"Agent Harness Compatibility",summary:"Cross-harness compatibility guidance for docs routing.",intent:"Use this when adapting pm docs and SDK contracts for an external automation harness.",commands:["pm guide skills","pm guide commands","pm contracts --runtime-only --availability-only"],workflows:[{name:"Harness Mapping",goal:"Route each harness to the same canonical skill/docs sources.",prompt:"Map harness-specific entrypoints to the same pm guide topics and .agents/skills workflows without adding runtime harness-specific code.",commands:["pm guide harnesses --depth standard","pm guide skills --depth deep"]}],docs:[{path:"docs/AGENT_GUIDE.md",purpose:"Agent context and output-mode conventions."},{path:"docs/README.md",purpose:"Single-source documentation routing entrypoint."},{path:".agents/skills/HARNESS_COMPATIBILITY.md",purpose:"Harness compatibility matrix and usage notes."}],related:["skills","workflows"]},{id:"release",aliases:["gates","ship","release-readiness"],title:"Release and Staleness Gates",summary:"Run release gates and docs/skills freshness checks before publishing.",intent:"Use this when validating release readiness and preventing docs/skills drift.",commands:["pnpm build","pnpm test:coverage","pnpm quality:static","node scripts/release/run-gates.mjs --telemetry-mode best-effort","pnpm security:scan"],workflows:[{name:"Pre-Release Gate Sweep",goal:"Ensure code, docs, and skills are all green before publish.",prompt:"Run release gates in deterministic order and treat docs/skills freshness failures as release blockers.",commands:["pnpm build","pnpm test:coverage","node scripts/release/run-gates.mjs --telemetry-mode best-effort"]}],docs:[{path:"docs/RELEASING.md",purpose:"Release flow and safety checks."},{path:"CHANGELOG.md",purpose:"Versioned release history and unreleased notes."},{path:"scripts/release/run-gates.mjs",purpose:"Source of truth for release gate ordering."}],related:["commands","skills","workflows"]},{id:"tokens",aliases:["output","budget","context-cost","projections"],title:"Read Output and Token Budgets",summary:"Bound what a read costs before it is emitted, and resume the part a budget withheld.",intent:"Use this when an agent must keep context small: every read declares a token ceiling, degrades deterministically, and reports what it omitted.",commands:["pm contracts --summary --json","pm list --status open --output-limit 20","pm get <ID> --output-include id,title,status,dependencies","pm context --limit 10 --token-accounting","pm notes <ID> --output-cursor <cursor>","pm list --status closed --output-budget unbounded"],workflows:[{name:"Bound A Read Before Emitting It",goal:"Never pay for rows the task does not need.",prompt:"Choose the narrowest projection first, then a row limit, then a token budget. Read the omission receipt before concluding the result is complete.",commands:["pm contracts --command list --flags-only --json","pm list --status open --output-limit 20 --output-format toon","pm list --status open --token-accounting"]},{name:"Recover A Truncated Read",goal:"Continue a bounded read instead of re-running it unbounded.",prompt:"When output_budget_truncation appears, prefer the declared continuation cursor. Only widen the budget when the response declares no cursor.",commands:["pm notes <ID> --output-cursor <cursor>","pm get <ID> --output-budget 20000"]}],docs:[{path:"docs/READ_OUTPUT_CONTRACTS.md",purpose:"Budget, truncation, continuation, and omission receipts."},{path:"docs/OUTPUT_PROJECTION_CONTRACTS.md",purpose:"Field and section projection grammar for every read."},{path:"docs/OUTPUT_TOKEN_ACCOUNTING.md",purpose:"Per-section token cost receipts."},{path:"docs/ITEM_READ_PROJECTIONS.md",purpose:"Item-level projection defaults and restore hints."}],related:["commands","workflows","quickstart"]},{id:"graph",aliases:["relationships","deps","dependencies","analytics"],title:"Relationship Graph and Planning Analytics",summary:"Type the relationships between items, then read the project as a graph rather than as a list.",intent:"Use this when the question is about lineage, ordering, blast radius, bottlenecks, or which work reaches a declared outcome.",commands:["pm deps <ID>",'pm update <ID> --dep "id=<other>,kind=implements"',"pm graph analyze","pm graph impact <ID> --direction downstream","pm graph paths <ID> <ID>","pm graph audit"],workflows:[{name:"Place New Work In The Ladder",goal:"Every item resolves to an outcome through a typed, explainable path.",prompt:"Set parent lineage first, then add typed edges that cite durable evidence. Never add an edge to satisfy a count.",commands:['pm search "<topic>" --limit 10','pm update <ID> --dep "id=<parent-goal>,kind=implements"',"pm graph ancestors <ID>"]},{name:"Assess Blast Radius Before Changing Something",goal:"Know what derives from an item before touching it.",prompt:"Walk the directed graph downstream from the item, then check whether any bottleneck node sits on the path.",commands:["pm graph impact <ID> --direction downstream","pm graph dominators <ID>","pm graph articulation"]}],docs:[{path:"docs/RELATIONSHIP_GRAPH.md",purpose:"Graph model, traversal verbs, and analytics surface."},{path:"docs/DEPENDENCY_KIND_CONTRACT.md",purpose:"Every typed edge kind, its direction, and its semantics."}],related:["commands","workflows","assurance"]},{id:"assurance",aliases:["gates","invariants","measurements","quality"],title:"Declared Invariants and Gates",summary:"Express a project's own quality rules as tracked data the SDK evaluates, instead of as scripts.",intent:"Use this when a rule must hold over the record itself \u2014 a floor, a ceiling, or a monotone property \u2014 and must fail closed in CI.",commands:["pm assurance list","pm assurance run <gate-id> --trigger ci --dry-run","pm validate --check-resolution --check-history-drift","pm health --summary"],workflows:[{name:"Add An Invariant Rather Than A Script",goal:"A new enforcement gap becomes declared data, not a new bespoke gate script.",prompt:"Define the measurement, bind an assertion with an explicit bound and polarity, prove a negative control, then attach it to a trigger.",commands:["pm assurance list --json","pm assurance run <gate-id> --trigger ci --dry-run --json"]},{name:"Read A Verdict Before Believing It",goal:"Know which population a passing assertion speaks for.",prompt:"Read population_size and scope on every assertion. A gate that cannot fail for the reason it exists is not evidence.",commands:["pm assurance run <gate-id> --trigger ci --dry-run --json --output-budget unbounded"]}],docs:[{path:"docs/ASSURANCE.md",purpose:"Measurement, assertion, gate, and trigger vocabulary."},{path:"docs/MUTATION_INTEGRITY.md",purpose:"What every mutation must record to remain provable."}],related:["release","graph","workflows"]},{id:"merge",aliases:["branches","concurrency","multi-agent","fleet"],title:"Branching, Merging, and Concurrent Agents",summary:"Keep tracker data and history conflict-free while many agents work on separate branches.",intent:"Use this when more than one agent or worktree mutates the same tracker and the results must merge without hand resolution.",commands:["pm merge install","pm merge report","pm merge reconcile --dry-run","pm claim <ID>","pm release <ID>","pm validate --check-history-drift","pm health --check-only"],workflows:[{name:"Prepare A Clone For Field-Aware Merges",goal:"The committed merge fence needs clone-local driver configuration once.",prompt:"Run the merge installer in every fresh clone or worktree before the first branch merge of tracker data.",commands:["pm merge install","pm health --check-only"]},{name:"Settle A Merge Before Trusting Health",goal:"A lossless merge still leaves pending receipts that strict health reports until they are reconciled.",prompt:"After any branch merge that touched tracker data, read the merge report, preview the reconciliation, then apply it; only then treat a health verdict as a statement about the data.",commands:["pm merge report","pm merge reconcile --dry-run",'pm merge reconcile --message "Post-merge history reconciliation"',"pm health --check-only"]},{name:"Hand Work Between Agents Safely",goal:"Ownership and evidence survive the handoff.",prompt:"Claim before substantial edits, record evidence as comments, and release the claim when pausing, handing off, closing, or canceling.",commands:["pm claim <ID>",'pm comments <ID> "Handoff: <state and next step>"',"pm release <ID>"]}],docs:[{path:"docs/MERGE_SAFETY.md",purpose:"Merge driver, field-aware resolution, and clone setup."},{path:"docs/SDK_CONTEXT_COORDINATION.md",purpose:"Coordination primitives for concurrent agents."}],related:["workflows","assurance","commands"]},{id:"evidence",aliases:["record","annotations","learnings","history-maintenance"],title:"Evidence, Durable Knowledge, and Record Maintenance",summary:"Append comments, notes, learnings, files, docs, and tests to items, and maintain the immutable history those records live in.",intent:"Use this when work must be explained to the next agent, when a durable lesson should outlive the item, or when a history stream needs verification, repair, redaction, compaction, or author attribution.",commands:['pm comments <ID> "<progress or verification evidence>"','pm notes <ID> --add "<rationale that belongs on the item>"','pm learnings <ID> --add "<lesson that should outlive the item>"',"pm append <ID> --body -","pm files <ID> --add path=<path>,scope=project,note=<why>","pm history <ID> --verify --strict-exit","pm history-repair --all --dry-run","pm history-redact <ID> --literal <secret> --dry-run","pm history-compact <ID> --dry-run","pm history-author-acknowledge --all-actionable --dry-run","pm close-many --ids <ID>,<ID> --reason <text> --dry-run","pm test-all --status open --limit 10 --progress"],workflows:[{name:"Record While Working, Not After",goal:"Another agent can rebuild the full situation from the item alone.",prompt:"Add a comment for each verified step, a note for each rationale the item body does not carry, and a learning for each lesson that applies beyond this item. Prefer appending over rewriting.",commands:['pm comments <ID> "Evidence: <what changed and what passed>"','pm notes <ID> --add "Decision log: <why this shape>"','pm learnings <ID> --add "<durable lesson>"',"pm learnings <ID> --limit 5"]},{name:"Verify And Repair A History Stream",goal:"Every mutation stays provable and the chain re-anchors after drift.",prompt:"Verify the chain with a strict exit before trusting a stream, preview any repair, and record why the repair was needed in the audit message.",commands:["pm history <ID> --verify --strict-exit","pm history-repair --all --dry-run",'pm history-repair --all --message "<why the chain drifted>"',"pm validate --check-history-drift"]},{name:"Redact, Compact, Or Attribute Without Losing Proof",goal:"Sensitive text, stream length, and unknown authors are handled through audited rewrites.",prompt:"Preview every history rewrite with --dry-run, read the receipt, then apply. Compaction renumbers ordinal versions, so record the checkpoint it created.",commands:["pm history-redact <ID> --literal <secret> --dry-run","pm history-compact <ID> --dry-run","pm history-author-acknowledge --all-actionable --dry-run"]}],docs:[{path:"docs/COMMANDS.md",purpose:"Annotation, bulk, and history-and-recovery command families."},{path:"docs/MUTATION_INTEGRITY.md",purpose:"Provenance and content-safety policy every mutation shares."},{path:"docs/AGENT_GUIDE.md",purpose:"Evidence expectations in the agent loop and self-repair remediation."}],related:["workflows","assurance","merge","graph"]},{id:"automation",aliases:["calendar","reminders","meetings","events"],title:"Reminders, Events, and Meetings",summary:"Attach time to items so context and agenda views can surface deadlines, meetings, and reminders when they matter.",intent:"Use this when an item needs a due signal, a scheduled event, or a meeting record that later context reads should surface.",commands:["pm package install calendar --project","pm calendar remind <title> --at <when> --parent <ID>","pm calendar event <title> --start <when> --parent <ID>","pm calendar meet <title> --start <when> --duration 30min --parent <ID>","pm context --limit 10"],workflows:[{name:"Put A Deadline Where Context Will Find It",goal:"Time-bound work surfaces in the agenda section of context reads.",prompt:"Install calendar, then record the reminder or event under its owning item and confirm it in context. Use explicit min or mo for durations; bare m is ambiguous.",commands:["pm package install calendar --project","pm calendar remind <title> --at <when> --parent <ID>","pm context --limit 10"]}],docs:[{path:"docs/COMMANDS.md",purpose:"Calendar and context command family."},{path:"packages/pm-calendar/README.md",purpose:"Package commands, duration units, and compatibility aliases."}],related:["workflows","quickstart","extensions"]}],TOPIC_BY_TOKEN=new Map;for(const topic of GUIDE_TOPICS){TOPIC_BY_TOKEN.set(topic.id,topic);for(const alias of topic.aliases)TOPIC_BY_TOKEN.set(alias,topic)}function listGuideTopics(){return GUIDE_TOPICS.map(topic=>({...topic,aliases:[...topic.aliases],commands:[...topic.commands],workflows:topic.workflows.map(workflow=>({...workflow,commands:[...workflow.commands]})),docs:topic.docs.map(doc=>({...doc})),related:[...topic.related]}))}function listGuideTopicIds(){return GUIDE_TOPICS.map(topic=>topic.id)}function resolveGuideTopic(rawTopic){if(!rawTopic)return null;const normalized=normalizeTopicToken(rawTopic);return normalized?TOPIC_BY_TOKEN.get(normalized)??null:null}export{listGuideTopicIds,listGuideTopics,resolveGuideTopic};
 //# sourceMappingURL=guide-topics.js.map

package/dist/sdk/guide.d.ts

@@ -1,97 +1,97 @@
 import { type GlobalOptions } from "./runtime-primitives.js";
 import { type GuideTopicDefinition } from "./guide-topics.js";
 /** Supported values accepted by the guide output contract. */
-export declare const GUIDE_OUTPUT_VALUES: readonly ["markdown", "toon", "json"];
+export declare const GUIDE_OUTPUT_VALUES:readonly ["markdown","toon","json"];
 /** Restricts guide output format values accepted by command, SDK, and storage contracts. */
 export type GuideOutputFormat = (typeof GUIDE_OUTPUT_VALUES)[number];
 /** Supported values accepted by the guide depth contract. */
-export declare const GUIDE_DEPTH_VALUES: readonly ["brief", "standard", "deep"];
+export declare const GUIDE_DEPTH_VALUES:readonly ["brief","standard","deep"];
 /** Restricts guide depth values accepted by command, SDK, and storage contracts. */
 export type GuideDepth = (typeof GUIDE_DEPTH_VALUES)[number];
 /** Documents the guide options payload exchanged by command, SDK, and package integrations. */
 export interface GuideOptions {
 /** Value that configures or reports topic for this contract. */
-topic?: string;
+topic?:string;
 /** Value that configures or reports list for this contract. */
-list?: boolean;
+list?:boolean;
 /** Value that configures or reports format for this contract. */
-format?: string;
+format?:string;
 /** Value that configures or reports depth for this contract. */
-depth?: string;
-[key: string]: unknown;
+depth?:string;
+[key:string]:unknown;
 }
 /** Documents the guide doc render payload exchanged by command, SDK, and package integrations. */
 export interface GuideDocRender {
 /** Filesystem path used for path resolution. */
-path: string;
+path:string;
 /** Value that configures or reports purpose for this contract. */
-purpose: string;
+purpose:string;
 /** Value that configures or reports optional for this contract. */
-optional: boolean;
+optional:boolean;
 /** Value that configures or reports exists for this contract. */
-exists: boolean;
+exists:boolean;
 /** Number of line entries represented by this result. */
-line_count: number | null;
+line_count:number | null;
 /** Strategy used to control content behavior. */
-content_mode: "none" | "excerpt" | "full";
+content_mode:"none" | "excerpt" | "full";
 /** Value that configures or reports content for this contract. */
-content: string | null;
+content:string | null;
 /** Value that configures or reports truncated for this contract. */
-truncated: boolean;
+truncated:boolean;
 }
 /** Documents the guide index result payload exchanged by command, SDK, and package integrations. */
 export interface GuideIndexResult {
 /** Value that configures or reports output default for this contract. */
-output_default: "toon";
+output_default:"toon";
 /** Value that configures or reports mode for this contract. */
-mode: "index";
+mode:"index";
 /** Value that configures or reports depth for this contract. */
-depth: GuideDepth;
+depth:GuideDepth;
 /** Value that configures or reports topics for this contract. */
-topics: Array<{
-id: string;
-aliases: string[];
-title: string;
-summary: string;
-intent: string;
-quick_commands: string[];
-docs: Array<{
-path: string;
-purpose: string;
+topics:Array<{
+id:string;
+aliases:string[];
+title:string;
+summary:string;
+intent:string;
+quick_commands:string[];
+docs:Array<{
+path:string;
+purpose:string;
 }>;
-related: string[];
+related:string[];
 }>;
 /** Value that configures or reports suggested next steps for this contract. */
-suggested_next_steps: string[];
+suggested_next_steps:string[];
 }
 /** Documents the guide topic result payload exchanged by command, SDK, and package integrations. */
 export interface GuideTopicResult {
 /** Value that configures or reports output default for this contract. */
-output_default: "toon";
+output_default:"toon";
 /** Value that configures or reports mode for this contract. */
-mode: "topic";
+mode:"topic";
 /** Value that configures or reports depth for this contract. */
-depth: GuideDepth;
+depth:GuideDepth;
 /** Value that configures or reports requested topic for this contract. */
-requested_topic: string;
+requested_topic:string;
 /** Value that configures or reports topic for this contract. */
-topic: GuideTopicDefinition;
+topic:GuideTopicDefinition;
 /** Value that configures or reports docs for this contract. */
-docs: GuideDocRender[];
+docs:GuideDocRender[];
 /** Value that configures or reports warnings for this contract. */
-warnings: string[];
+warnings:string[];
 }
 /** Restricts guide result values accepted by command, SDK, and storage contracts. */
 export type GuideResult = GuideIndexResult | GuideTopicResult;
 /** Implements resolve guide output format for the public runtime surface of this module. */
-export declare function resolveGuideOutputFormat(options: GuideOptions, global: GlobalOptions): GuideOutputFormat;
-declare function ensureGuideTopic(topic: string): GuideTopicDefinition;
+export declare function resolveGuideOutputFormat(options:GuideOptions,global:GlobalOptions):GuideOutputFormat;
+declare function ensureGuideTopic(topic:string):GuideTopicDefinition;
 /** Implements run guide for the public runtime surface of this module. */
-export declare function runGuide(options: GuideOptions, global: GlobalOptions): Promise<GuideResult>;
+export declare function runGuide(options:GuideOptions,global:GlobalOptions):Promise<GuideResult>;
 /** Public contract for test only guide, shared by SDK and presentation-layer consumers. */
-export declare const _testOnlyGuide: {
-ensureGuideTopic: typeof ensureGuideTopic;
+export declare const _testOnlyGuide:{
+ensureGuideTopic:typeof ensureGuideTopic;
 };
 /** Implements render guide markdown for the public runtime surface of this module. */
-export declare function renderGuideMarkdown(result: GuideResult): string;
+export declare function renderGuideMarkdown(result:GuideResult):string;
 export {};

package/dist/sdk/history/attestation-command.d.ts

@@ -1,22 +1,22 @@
 import type { GlobalOptions } from "../../core/shared/command-types.js";
-import type { HistoryAttestation, HistoryAttestationVerification } from "./attestation-contract.js";
+import type { HistoryAttestation,HistoryAttestationVerification } from "./attestation-contract.js";
 /** Proof transport options; local CLI/SDK callers may also use filesystem paths. */
 export interface HistoryAttestCommandOptions {
 /** Compare current streams with a retained bundle, or a local CLI/SDK proof path. */
-verify?: string | HistoryAttestation;
+verify?:string | HistoryAttestation;
 /** Create a new proof file exclusively; existing files are never overwritten. */
-output?: string;
+output?:string;
 /** Digest used for new bundles, independently from record algorithms. */
-hashAlgorithm?: string;
+hashAlgorithm?:string;
 }
 /** Bounded receipt after a complete bundle has been saved separately. */
 export interface HistoryAttestationExportReceipt {
 /** File created by this export. */
-output: string;
+output:string;
 /** Digest committing to the entire bundle. */
-workspace_digest: string;
+workspace_digest:string;
 /** Number of streams represented by the saved proof. */
-streams: number;
+streams:number;
 }
 /** Export a complete proof or verify one; no tracker mutations or extension hooks occur. */
-export declare function runHistoryAttest(options: HistoryAttestCommandOptions, global: GlobalOptions): Promise<HistoryAttestation | HistoryAttestationVerification | HistoryAttestationExportReceipt>;
+export declare function runHistoryAttest(options:HistoryAttestCommandOptions,global:GlobalOptions):Promise<HistoryAttestation | HistoryAttestationVerification | HistoryAttestationExportReceipt>;