@unbrained/pm-cli 2026.9.7 → 2026.9.8

package/dist/sdk/cli-contracts/flag-lexicon-contracts.js

@@ -1,348 +1,2 @@
-/**
- * @module sdk/flag-lexicon-contracts
- *
- * Compiles command flags into a canonical concept lexicon with enforceable
- * per-command growth budgets.
- */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3fdfd4c8-a7ef-5469-acf5-bc2577fd141a")}catch(e){}}();
-import { hasSubcommandFlagContractsForCommand, resolveSubcommandFlagContractsForCommand, } from "./flag-contracts.js";
-import { PM_COMMAND_CAPABILITY_CONTRACTS, } from "../agent-capability-contracts.js";
-import { enrichCliFlagInvocationContracts } from "../flag-invocation-contracts.js";
-/** Memoized immutable canonical lexicon for this module instance. */
-let cachedPmFlagLexicon;
-const FULL_PROJECTION_CONCEPT_BY_COMMAND = Object.freeze({
-    list: "list-item-projection",
-    "list-all": "list-item-projection",
-    "list-draft": "list-item-projection",
-    "list-open": "list-item-projection",
-    "list-in-progress": "list-item-projection",
-    "list-blocked": "list-item-projection",
-    "list-closed": "list-item-projection",
-    "list-canceled": "list-item-projection",
-    get: "get-item-projection",
-    graph: "graph-detail-projection",
-    search: "search-result-projection",
-    history: "history-entry-projection",
-    events: "mutation-event-projection",
-    activity: "activity-entry-projection",
-    deps: "dependency-graph-projection",
-    health: "health-diagnostic-projection",
-    validate: "validation-diagnostic-projection",
-    contracts: "contract-catalog-projection",
-});
-/** Resolve one executable command flag to its stable cross-command semantic concept. */
-export function resolvePmFlagSemanticConcept(command, flag) {
-    if (flag === "--limit")
-        return "result-row-limit";
-    if (flag === "--node-limit")
-        return "graph-node-limit";
-    if (flag === "--edge-limit")
-        return "graph-edge-limit";
-    if (flag === "--output-limit")
-        return "rendered-output-row-limit";
-    if (flag === "--output-budget")
-        return "rendered-output-byte-budget";
-    if (flag === "--token-budget")
-        return "context-intent-token-budget";
-    if (flag === "--full") {
-        const concept = FULL_PROJECTION_CONCEPT_BY_COMMAND[command];
-        if (concept === undefined) {
-            throw new Error(`Command ${command} exposes --full without a registered projection concept.`);
-        }
-        return concept;
-    }
-    if (flag !== "--file")
-        return flag.slice(2);
-    if (["create", "update", "update-many"].includes(command))
-        return "linked-file-path";
-    if (["comments", "notes", "learnings"].includes(command))
-        return "entry-file-input";
-    return "plan-definition-file";
-}
-/** Build the canonical lexicon lazily from the same contracts as CLI and MCP. */
-export function listPmFlagLexicon() {
-    if (cachedPmFlagLexicon !== undefined)
-        return cachedPmFlagLexicon;
-    const commandContracts = PM_COMMAND_CAPABILITY_CONTRACTS.filter(({ command }) => hasSubcommandFlagContractsForCommand(command));
-    const provisionalEntries = commandContracts.flatMap(({ command, family }) => enrichCliFlagInvocationContracts(command, resolveSubcommandFlagContractsForCommand(command)).map((contract) => ({
-        command,
-        family,
-        concept: resolvePmFlagSemanticConcept(command, contract.flag),
-        flag: contract.flag,
-        aliases: Object.freeze([...(contract.aliases ?? [])]),
-        value_kind: (contract.repeatable
-            ? "list"
-            : contract.flag === "--limit"
-                ? "number"
-                : contract.value_type),
-    })));
-    const compatibilityAliasFlags = new Set(provisionalEntries.flatMap((entry) => entry.aliases.map((alias) => `${entry.command}:${alias}`)));
-    const canonicalEntries = provisionalEntries.filter((entry) => !compatibilityAliasFlags.has(`${entry.command}:${entry.flag}`));
-    const kindsByConcept = new Map();
-    for (const entry of canonicalEntries) {
-        const kinds = kindsByConcept.get(entry.concept) ?? new Set();
-        kinds.add(entry.value_kind);
-        kindsByConcept.set(entry.concept, kinds);
-    }
-    cachedPmFlagLexicon = Object.freeze(canonicalEntries.map((entry) => Object.freeze({
-        ...entry,
-        concept: kindsByConcept.get(entry.concept)?.size === 1
-            ? entry.concept
-            : `${entry.concept}@${entry.command}`,
-    })));
-    return cachedPmFlagLexicon;
-}
-/** Return the complete canonical and compatibility spelling inventory. */
-export function listPmFlagSpellingInventory() {
-    return Object.freeze(listPmFlagLexicon().map((entry) => Object.freeze({
-        command: entry.command,
-        canonical_flag: entry.flag,
-        accepted_spellings: Object.freeze([...new Set([entry.flag, ...entry.aliases])].sort()),
-    })));
-}
-// pm-2bqgs7: reconcile already executable options omitted by the previous
-// declared-only census. pm-08mt4k adds two explicit scheduling opt-ins to next
-// and claim; aliases remain free and every future increase still fails closed.
-const PM_COMMAND_FLAG_BUDGET_MAXIMUMS = Object.freeze({
-    init: 30,
-    config: 36,
-    extension: 53,
-    package: 54,
-    packages: 54,
-    install: 26,
-    upgrade: 29,
-    create: 100,
-    copy: 24,
-    focus: 22,
-    list: 86,
-    "list-all": 86,
-    "list-draft": 84,
-    "list-open": 84,
-    "list-in-progress": 84,
-    "list-blocked": 84,
-    "list-closed": 84,
-    "list-canceled": 84,
-    aggregate: 37,
-    context: 45,
-    ctx: 45,
-    get: 30,
-    graph: 34,
-    search: 78,
-    // pm-pshhry: one explicit exhaustive-reference mode, with no spare flag allowance.
-    duplicates: 25,
-    eval: 25,
-    next: 38,
-    history: 35,
-    events: 33,
-    "history-redact": 27,
-    // One explicit destructive-recovery mode; never overload ordinary reanchoring.
-    "history-repair": 27,
-    "history-compact": 30,
-    "history-author-acknowledge": 28,
-    // 24 -> 27 on 2026-09-04: --message, --force, and --include-reconciled were
-    // already registered at runtime for reconcile and report; declaring them
-    // makes the contract truthful rather than growing the surface.
-    merge: 27,
-    schema: 40,
-    profile: 22,
-    activity: 35,
-    restore: 23,
-    update: 105,
-    "update-many": 146,
-    close: 31,
-    "close-many": 72,
-    delete: 24,
-    append: 25,
-    comments: 31,
-    notes: 35,
-    learnings: 31,
-    files: 39,
-    docs: 30,
-    deps: 32,
-    plan: 109,
-    test: 53,
-    "test-all": 40,
-    telemetry: 21,
-    stats: 29,
-    health: 36,
-    validate: 45,
-    assurance: 30,
-    gc: 22,
-    workspace: 23,
-    contracts: 29,
-    claim: 38,
-    release: 23,
-    "start-task": 23,
-    "pause-task": 23,
-    "close-task": 24,
-    meet: 33,
-    event: 33,
-    remind: 29,
-    "test-runs-worker": 25,
-});
-/** Return persisted no-growth ratchets with current counts derived from the canonical vocabulary. */
-export function listPmCommandFlagBudgets() {
-    const currentByCommand = new Map(Object.keys(PM_COMMAND_FLAG_BUDGET_MAXIMUMS).map((command) => [command, 0]));
-    for (const { command } of listPmFlagLexicon()) {
-        currentByCommand.set(command, Number(currentByCommand.get(command)) + 1);
-    }
-    return Object.freeze(Object.entries(PM_COMMAND_FLAG_BUDGET_MAXIMUMS).map(([command, maximum]) => Object.freeze({
-        command,
-        current: Number(currentByCommand.get(command)),
-        maximum,
-    })));
-}
-/** Append collisions between compatibility aliases and canonical spellings. */
-function appendAliasCollisionFindings(entries, canonicalOwners, findings) {
-    for (const entry of entries) {
-        for (const alias of entry.aliases) {
-            const owner = canonicalOwners.get(`${entry.command}:${alias}`);
-            if (owner === undefined || owner.flag === entry.flag)
-                continue;
-            findings.push({
-                code: "alias_collision",
-                command: entry.command,
-                detail: `${alias} aliases ${entry.flag} but is canonical for ${owner.flag}.`,
-            });
-        }
-    }
-}
-/** Append missing, stale, and exceeded command-budget findings. */
-function appendBudgetFindings(counts, budgets, findings) {
-    const budgetedCommands = new Set(budgets.map(({ command }) => command));
-    for (const command of counts.keys()) {
-        if (budgetedCommands.has(command))
-            continue;
-        findings.push({
-            code: "missing_budget",
-            command,
-            detail: `${command} has canonical flags but no persisted budget.`,
-        });
-    }
-    for (const budget of budgets) {
-        const actual = counts.get(budget.command) ?? 0;
-        if (actual === 0) {
-            findings.push({
-                code: "stale_budget",
-                command: budget.command,
-                detail: `${budget.command} has a persisted budget but no canonical flags.`,
-            });
-        }
-        if (actual <= budget.maximum)
-            continue;
-        findings.push({
-            code: "budget_exceeded",
-            command: budget.command,
-            detail: `${actual} canonical flags exceed the ratcheted maximum ${budget.maximum}.`,
-        });
-    }
-}
-/** Append regressions against the persisted pre-change spelling inventory. */
-function appendSpellingCompatibilityFindings(entries, baseline, findings) {
-    const current = new Map(entries.map((entry) => [`${entry.command}:${entry.flag}`, entry]));
-    for (const historical of baseline) {
-        const key = `${historical.command}:${historical.canonical_flag}`;
-        const entry = current.get(key);
-        if (!entry) {
-            findings.push({
-                code: "removed_canonical_spelling",
-                command: historical.command,
-                detail: `${historical.canonical_flag} disappeared from the executable spelling inventory.`,
-            });
-            continue;
-        }
-        const accepted = new Set([entry.flag, ...entry.aliases]);
-        for (const spelling of historical.accepted_spellings) {
-            if (accepted.has(spelling))
-                continue;
-            findings.push({
-                code: "removed_compatibility_spelling",
-                command: historical.command,
-                detail: `${spelling} no longer resolves to ${historical.canonical_flag}.`,
-            });
-        }
-    }
-}
-/** Verify uniqueness, concept kind stability, alias safety, and flag budgets. */
-export function verifyPmFlagLexicon(entries = listPmFlagLexicon(), budgets = listPmCommandFlagBudgets(), baseline = []) {
-    const findings = [];
-    const canonicalOwners = new Map();
-    const conceptKinds = new Map();
-    const conceptSpellings = new Map();
-    const counts = new Map();
-    for (const entry of entries) {
-        const commandFlag = `${entry.command}:${entry.flag}`;
-        if (canonicalOwners.has(commandFlag)) {
-            findings.push({
-                code: "duplicate_canonical_flag",
-                command: entry.command,
-                detail: `${entry.flag} has more than one canonical row.`,
-            });
-        }
-        else {
-            canonicalOwners.set(commandFlag, entry);
-        }
-        counts.set(entry.command, (counts.get(entry.command) ?? 0) + 1);
-        const priorKind = conceptKinds.get(entry.concept);
-        if (priorKind !== undefined && priorKind !== entry.value_kind) {
-            findings.push({
-                code: "inconsistent_concept_kind",
-                command: entry.command,
-                detail: `${entry.concept} uses both ${priorKind} and ${entry.value_kind}.`,
-            });
-        }
-        else {
-            conceptKinds.set(entry.concept, entry.value_kind);
-        }
-        const priorSpelling = conceptSpellings.get(entry.concept);
-        if (priorSpelling !== undefined && priorSpelling !== entry.flag) {
-            findings.push({
-                code: "semantic_spelling_collision",
-                command: entry.command,
-                detail: `${entry.concept} is canonicalized by both ${priorSpelling} and ${entry.flag}.`,
-            });
-        }
-        else {
-            conceptSpellings.set(entry.concept, entry.flag);
-        }
-    }
-    appendAliasCollisionFindings(entries, canonicalOwners, findings);
-    appendBudgetFindings(counts, budgets, findings);
-    appendSpellingCompatibilityFindings(entries, baseline, findings);
-    findings.sort((left, right) => left.command.localeCompare(right.command) ||
-        left.code.localeCompare(right.code) ||
-        left.detail.localeCompare(right.detail));
-    return {
-        ok: findings.length === 0,
-        entry_count: entries.length,
-        budget_count: budgets.length,
-        concept_count: new Set(entries.map(({ concept }) => concept)).size,
-        baseline_entry_count: baseline.length,
-        findings,
-    };
-}
-/** Render a compact, generated family and command budget reference. Persisted budget rows are initialized to an explicit fallback so stale rows remain renderable. */
-export function renderPmFlagLexiconMarkdown() {
-    const lexicon = listPmFlagLexicon();
-    const budgets = listPmCommandFlagBudgets();
-    const familyByCommand = new Map(budgets.map(({ command }) => [command, "unknown"]));
-    for (const { command, family } of lexicon)
-        familyByCommand.set(command, family);
-    const rows = budgets.map(({ command, current, maximum }) => {
-        const family = familyByCommand.get(command);
-        return `| \`${command}\` | ${family} | ${current} | ${maximum} |`;
-    });
-    return [
-        "# Generated flag lexicon budgets",
-        "",
-        "This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not consume canonical budget.",
-        "",
-        "| Command | Capability family | Canonical flags | Maximum |",
-        "| --- | --- | ---: | ---: |",
-        ...rows,
-        "",
-    ].join("\n");
-}
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1343764b-7e64-5ce5-a5ae-7ae44acf4361")}catch(e2){}})();import{hasSubcommandFlagContractsForCommand,resolveSubcommandFlagContractsForCommand}from"./flag-contracts.js";import{PM_COMMAND_CAPABILITY_CONTRACTS}from"../agent-capability-contracts.js";import{enrichCliFlagInvocationContracts}from"../flag-invocation-contracts.js";let cachedPmFlagLexicon;const FULL_PROJECTION_CONCEPT_BY_COMMAND=Object.freeze({list:"list-item-projection","list-all":"list-item-projection","list-draft":"list-item-projection","list-open":"list-item-projection","list-in-progress":"list-item-projection","list-blocked":"list-item-projection","list-closed":"list-item-projection","list-canceled":"list-item-projection",get:"get-item-projection",graph:"graph-detail-projection",search:"search-result-projection",history:"history-entry-projection",events:"mutation-event-projection",activity:"activity-entry-projection",deps:"dependency-graph-projection",health:"health-diagnostic-projection",validate:"validation-diagnostic-projection",contracts:"contract-catalog-projection"});function resolvePmFlagSemanticConcept(command,flag){if(flag==="--limit")return"result-row-limit";if(flag==="--node-limit")return"graph-node-limit";if(flag==="--edge-limit")return"graph-edge-limit";if(flag==="--output-limit")return"rendered-output-row-limit";if(flag==="--output-budget")return"rendered-output-byte-budget";if(flag==="--token-budget")return"context-intent-token-budget";if(flag==="--full"){const concept=FULL_PROJECTION_CONCEPT_BY_COMMAND[command];if(concept===void 0){throw new Error(`Command ${command} exposes --full without a registered projection concept.`)}return concept}if(flag!=="--file")return flag.slice(2);if(["create","update","update-many"].includes(command))return"linked-file-path";if(["comments","notes","learnings"].includes(command))return"entry-file-input";return"plan-definition-file"}function listPmFlagLexicon(){if(cachedPmFlagLexicon!==void 0)return cachedPmFlagLexicon;const commandContracts=PM_COMMAND_CAPABILITY_CONTRACTS.filter(({command})=>hasSubcommandFlagContractsForCommand(command));const provisionalEntries=commandContracts.flatMap(({command,family})=>enrichCliFlagInvocationContracts(command,resolveSubcommandFlagContractsForCommand(command)).map(contract=>({command,family,concept:resolvePmFlagSemanticConcept(command,contract.flag),flag:contract.flag,aliases:Object.freeze([...contract.aliases??[]]),value_kind:contract.repeatable?"list":contract.flag==="--limit"?"number":contract.value_type})));const compatibilityAliasFlags=new Set(provisionalEntries.flatMap(entry=>entry.aliases.map(alias=>`${entry.command}:${alias}`)));const canonicalEntries=provisionalEntries.filter(entry=>!compatibilityAliasFlags.has(`${entry.command}:${entry.flag}`));const kindsByConcept=new Map;for(const entry of canonicalEntries){const kinds=kindsByConcept.get(entry.concept)??new Set;kinds.add(entry.value_kind);kindsByConcept.set(entry.concept,kinds)}cachedPmFlagLexicon=Object.freeze(canonicalEntries.map(entry=>Object.freeze({...entry,concept:kindsByConcept.get(entry.concept)?.size===1?entry.concept:`${entry.concept}@${entry.command}`})));return cachedPmFlagLexicon}function listPmFlagSpellingInventory(){return Object.freeze(listPmFlagLexicon().map(entry=>Object.freeze({command:entry.command,canonical_flag:entry.flag,accepted_spellings:Object.freeze([...new Set([entry.flag,...entry.aliases])].sort())})))}const PM_COMMAND_FLAG_BUDGET_MAXIMUMS=Object.freeze({init:30,config:36,extension:54,package:55,packages:55,install:27,upgrade:29,create:100,copy:24,focus:22,list:86,"list-all":86,"list-draft":84,"list-open":84,"list-in-progress":84,"list-blocked":84,"list-closed":84,"list-canceled":84,aggregate:40,context:45,ctx:45,get:30,graph:34,search:78,duplicates:25,eval:25,next:38,history:35,events:33,"history-redact":27,"history-repair":27,"history-compact":30,"history-author-acknowledge":28,merge:27,schema:40,profile:22,activity:35,restore:23,update:105,"update-many":146,close:31,"close-many":72,delete:24,append:25,comments:31,notes:35,learnings:31,files:39,docs:30,deps:32,plan:109,test:53,"test-all":40,telemetry:21,stats:29,health:36,validate:45,assurance:30,gc:22,workspace:23,contracts:29,claim:38,release:23,"start-task":23,"pause-task":23,"close-task":24,meet:33,event:33,remind:29,"test-runs-worker":25});function listPmCommandFlagBudgets(){const currentByCommand=new Map(Object.keys(PM_COMMAND_FLAG_BUDGET_MAXIMUMS).map(command=>[command,0]));for(const{command}of listPmFlagLexicon()){currentByCommand.set(command,Number(currentByCommand.get(command))+1)}return Object.freeze(Object.entries(PM_COMMAND_FLAG_BUDGET_MAXIMUMS).map(([command,maximum])=>Object.freeze({command,current:Number(currentByCommand.get(command)),maximum})))}function appendAliasCollisionFindings(entries,canonicalOwners,findings){for(const entry of entries){for(const alias of entry.aliases){const owner=canonicalOwners.get(`${entry.command}:${alias}`);if(owner===void 0||owner.flag===entry.flag)continue;findings.push({code:"alias_collision",command:entry.command,detail:`${alias} aliases ${entry.flag} but is canonical for ${owner.flag}.`})}}}function appendBudgetFindings(counts,budgets,findings){const budgetedCommands=new Set(budgets.map(({command})=>command));for(const command of counts.keys()){if(budgetedCommands.has(command))continue;findings.push({code:"missing_budget",command,detail:`${command} has canonical flags but no persisted budget.`})}for(const budget of budgets){const actual=counts.get(budget.command)??0;if(actual===0){findings.push({code:"stale_budget",command:budget.command,detail:`${budget.command} has a persisted budget but no canonical flags.`})}if(actual<=budget.maximum)continue;findings.push({code:"budget_exceeded",command:budget.command,detail:`${actual} canonical flags exceed the ratcheted maximum ${budget.maximum}.`})}}function appendSpellingCompatibilityFindings(entries,baseline,findings){const current=new Map(entries.map(entry=>[`${entry.command}:${entry.flag}`,entry]));for(const historical of baseline){const key=`${historical.command}:${historical.canonical_flag}`;const entry=current.get(key);if(!entry){findings.push({code:"removed_canonical_spelling",command:historical.command,detail:`${historical.canonical_flag} disappeared from the executable spelling inventory.`});continue}const accepted=new Set([entry.flag,...entry.aliases]);for(const spelling of historical.accepted_spellings){if(accepted.has(spelling))continue;findings.push({code:"removed_compatibility_spelling",command:historical.command,detail:`${spelling} no longer resolves to ${historical.canonical_flag}.`})}}}function verifyPmFlagLexicon(entries=listPmFlagLexicon(),budgets=listPmCommandFlagBudgets(),baseline=[]){const findings=[];const canonicalOwners=new Map;const conceptKinds=new Map;const conceptSpellings=new Map;const counts=new Map;for(const entry of entries){const commandFlag=`${entry.command}:${entry.flag}`;if(canonicalOwners.has(commandFlag)){findings.push({code:"duplicate_canonical_flag",command:entry.command,detail:`${entry.flag} has more than one canonical row.`})}else{canonicalOwners.set(commandFlag,entry)}counts.set(entry.command,(counts.get(entry.command)??0)+1);const priorKind=conceptKinds.get(entry.concept);if(priorKind!==void 0&&priorKind!==entry.value_kind){findings.push({code:"inconsistent_concept_kind",command:entry.command,detail:`${entry.concept} uses both ${priorKind} and ${entry.value_kind}.`})}else{conceptKinds.set(entry.concept,entry.value_kind)}const priorSpelling=conceptSpellings.get(entry.concept);if(priorSpelling!==void 0&&priorSpelling!==entry.flag){findings.push({code:"semantic_spelling_collision",command:entry.command,detail:`${entry.concept} is canonicalized by both ${priorSpelling} and ${entry.flag}.`})}else{conceptSpellings.set(entry.concept,entry.flag)}}appendAliasCollisionFindings(entries,canonicalOwners,findings);appendBudgetFindings(counts,budgets,findings);appendSpellingCompatibilityFindings(entries,baseline,findings);findings.sort((left,right)=>left.command.localeCompare(right.command)||left.code.localeCompare(right.code)||left.detail.localeCompare(right.detail));return{ok:findings.length===0,entry_count:entries.length,budget_count:budgets.length,concept_count:new Set(entries.map(({concept})=>concept)).size,baseline_entry_count:baseline.length,findings}}function renderPmFlagLexiconMarkdown(){const lexicon=listPmFlagLexicon();const budgets=listPmCommandFlagBudgets();const familyByCommand=new Map(budgets.map(({command})=>[command,"unknown"]));for(const{command,family}of lexicon)familyByCommand.set(command,family);const rows=budgets.map(({command,current,maximum})=>{const family=familyByCommand.get(command);return`| \`${command}\` | ${family} | ${current} | ${maximum} |`});return["# Generated flag lexicon budgets","","This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not consume canonical budget.","","| Command | Capability family | Canonical flags | Maximum |","| --- | --- | ---: | ---: |",...rows,""].join("\n")}export{listPmCommandFlagBudgets,listPmFlagLexicon,listPmFlagSpellingInventory,renderPmFlagLexiconMarkdown,resolvePmFlagSemanticConcept,verifyPmFlagLexicon};
 //# sourceMappingURL=flag-lexicon-contracts.js.map
-//# debugId=3fdfd4c8-a7ef-5469-acf5-bc2577fd141a