planfs-cli 1.3.0 → 1.4.0

package/README.md

@@ -14,6 +14,8 @@ Command-line interface for PlanFS.
 - **Show** - Display entity details
 - **Create** - Create new entities
 - **PR** - Generate pull request planning context
+- **Format** - Check, preview, and explicitly apply conservative semantic Markdown repairs
+- **Semantic context** - Share compact, traceable planning intent and relationship context between agents and people
 
 ## Installation
 
@@ -46,8 +48,14 @@ Validate the repository for errors:
 ```bash
 planfs validate
 planfs validate --verbose
+planfs validate --semantic baseline
+planfs validate --semantic automation-ready --lifecycle
+planfs validate --semantic automation-ready --criterion-check-state error --format json
+planfs validate --semantic automation-ready --nlp --language en
 ```
 
+Semantic validation is opt-in and remains separate from existing YAML and repository-integrity checks. `baseline` checks loss-preserving Markdown interpretation; `automation-ready` applies entity content profiles; `--lifecycle` adds read-only status-sensitive policy. Ordinary criteria can be ignored or reported at `info`, `warning`, or `error` severity. `--strict` fails on repository or semantic warnings. Enabled semantic JSON appears under a separate `semantic` key, leaving default JSON unchanged.
+
 ### List
 
 List entities:
@@ -103,6 +111,19 @@ planfs backlog list --format json
 
 Backlog refinement states are `captured`, `needs-refinement`, `ready`, `deferred`, and `discarded`. Explicit non-ready backlog items are separate from next-work recommendations.
 
+### AI Planning Context
+
+Start with the repository summary, then retrieve bounded semantic context for relevant work:
+
+```bash
+planfs ai summary --only ready --compact
+planfs ai context --id TASK-001
+planfs ai context --id TASK-001 --format text
+planfs ai context --id TASK-001 --nlp --language en
+```
+
+`ai context` uses the shared core semantic parser and returns intent, recognized sections, acceptance criteria, findings, decisions, questions, references, diagnostics, readiness, and resolved authoritative relationships. JSON retains source ranges and provenance for traceability; text presents the same contract for human review. Advisory prose analysis is local, optional, and never mutates metadata.
+
 ### Show
 
 Display entity details:
@@ -110,8 +131,45 @@ Display entity details:
 ```bash
 planfs show TASK-001
 planfs show TASK-001 --format json
+planfs show TASK-001 --nlp
+planfs show TASK-001 --nlp --language en --format json
+```
+
+`--nlp` explicitly enables local, advisory English prose analysis. It reports promoted modality, negation, condition, date/duration, and possible relationship-mention signals with source locations. Analysis never edits the file or treats prose as authoritative metadata. It makes no network calls and downloads no model. Other languages return an advisory unsupported-language diagnostic without hiding the entity or failing the command.
+
+Without `--nlp`, JSON output retains the existing entity shape. With `--nlp`, JSON is `{ "entity": ..., "analysis": ... }`; every signal is marked `nlp-inferred` and `authoritative: false`.
+
+### Semantic Inspection
+
+Inspect normalized Markdown content, authoritative relationships, diagnostics, and advisory suggestions through one stable surface:
+
+```bash
+planfs inspect TASK-001
+planfs inspect TASK-001 --format json
+planfs inspect TASK-001 --view acceptance-criteria --format json
+planfs inspect TASK-001 --view relationships
+planfs inspect TASK-001 --view raw --no-nlp
 ```
 
+Semantic inspection runs the bundled local analyzer by default and can be made structural-only with `--no-nlp`. Normal text output shows deduplicated actionable suggestions; full JSON preserves analyzer identity, language, evidence, confidence, provenance, raw signals, exact source ranges, and raw Markdown. Analysis remains advisory and never modifies frontmatter. This does not change `validate`: analysis during validation is still explicitly enabled with `--nlp`.
+
+Focused views are `all`, `acceptance-criteria`, `findings`, `sections`, `mentions`, `relationships`, and `raw`. See [Semantic Entity Inspection](../../docs/SEMANTIC_INSPECTION.md) for the stable envelope and integration examples.
+
+### Semantic Formatting
+
+Keep validation, formatting checks, previews, and writes explicit:
+
+```bash
+planfs validate --semantic automation-ready
+planfs format TASK-001 --check
+planfs format TASK-001 --format json
+planfs format TASK-001 --apply --expected-fingerprint sha256:...
+planfs format TASK-001 TASK-002 --format json
+planfs format --all --check
+```
+
+`format` canonicalizes only uniquely recognized headings and acceptance/release checklist markers. Preview is the default and never writes. Apply requires the source fingerprint returned by preview; batch fingerprints use `ENTITY-ID=sha256:...`. Unknown sections, code, HTML, comments, links, images, line endings, and frontmatter remain unchanged. Duplicate recognized sections and unsafe regions are reported rather than merged or guessed. See [Semantic Markdown Formatting](../../docs/SEMANTIC_FORMATTING.md) for the complete safety contract.
+
 ### Create
 
 Create new entities:

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 /**
- * Main CLI entry point
+ * Main CLI entry point.
  */
 export declare function main(): Promise<void>;

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * Main CLI entry point
+ * Main CLI entry point.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -10,551 +10,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.main = main;
 const yargs_1 = __importDefault(require("yargs"));
 const helpers_1 = require("yargs/helpers");
-const validate_1 = require("./commands/validate");
-const ai_1 = require("./commands/ai");
-const init_1 = require("./commands/init");
-const list_1 = require("./commands/list");
-const next_1 = require("./commands/next");
-const show_1 = require("./commands/show");
-const create_1 = require("./commands/create");
-const backlog_1 = require("./commands/backlog");
-const archive_1 = require("./commands/archive");
-const branch_1 = require("./commands/branch");
-const git_1 = require("./commands/git");
-const pr_1 = require("./commands/pr");
-const doctor_1 = require("./commands/doctor");
-const migrate_1 = require("./commands/migrate");
-const update_1 = require("./commands/update");
-const filter_1 = require("./commands/filter");
-const history_1 = require("./commands/history");
+const entity_commands_1 = require("./entity-commands");
+const planning_commands_1 = require("./planning-commands");
+const workflow_commands_1 = require("./workflow-commands");
 const package_json_1 = __importDefault(require("../package.json"));
 async function main() {
-    await (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
-        .version(package_json_1.default.version)
-        .command('ai <action>', 'AI-oriented planning summary and update helpers', (y) => y
-        .positional('action', {
-        describe: 'AI helper to run',
-        choices: ['summary', 'update-task', 'bulk-update-tasks', 'initialize']
-    })
-        .option('id', {
-        type: 'string',
-        description: 'Task ID to update'
-    })
-        .option('ids', {
-        type: 'array',
-        string: true,
-        description: 'Task IDs to bulk update, comma-separated or repeated'
-    })
-        .option('assignee', {
-        type: 'string',
-        description: 'Scope summary or set task assignee'
-    })
-        .option('epic', {
-        type: 'string',
-        description: 'Scope summary or set task epic'
-    })
-        .option('milestone', {
-        type: 'string',
-        description: 'Scope summary or set task milestone'
-    })
-        .option('estimate', {
-        type: 'string',
-        description: 'Set task estimate'
-    })
-        .option('status', {
-        type: 'array',
-        string: true,
-        choices: ['todo', 'in-progress', 'review', 'done'],
-        description: 'Scope summary by status or set task status'
-    })
-        .option('priority', {
-        type: 'string',
-        choices: ['low', 'medium', 'high', 'critical'],
-        description: 'Set task priority'
-    })
-        .option('refinement-state', {
-        type: 'array',
-        string: true,
-        choices: ['captured', 'needs-refinement', 'ready', 'deferred', 'discarded'],
-        description: 'Scope summary by refinement state or set task refinement state'
-    })
-        .option('due-date', {
-        type: 'string',
-        description: 'Set task due date'
-    })
-        .option('tags', {
-        type: 'string',
-        description: 'Set task tags as a comma-separated list'
-    })
-        .option('limit', {
-        type: 'number',
-        description: 'Maximum number of summary items per list'
-    })
-        .option('only', {
-        type: 'string',
-        choices: ['open', 'ready', 'blocked', 'review', 'stale', 'recent'],
-        description: 'Return only one planning summary section'
-    })
-        .option('compact', {
-        type: 'boolean',
-        default: false,
-        description: 'Emit minified JSON for lower-overhead agent context'
-    })
-        .option('expected-updated-at', {
-        type: 'string',
-        description: 'Refuse a task update if updatedAt changed since preview (use none for an unset timestamp)'
-    })
-        .option('command', {
-        type: 'string',
-        description: 'CLI command written by ai initialize (default: planfs)'
-    })
-        .option('dry-run', {
-        type: 'boolean',
-        default: false,
-        description: 'Preview task updates or awareness initialization without writing files'
-    })
-        .option('file', {
-        type: 'string',
-        default: 'AGENTS.md',
-        description: 'Agent instruction file to create or update'
-    })
-        .option('format', {
-        type: 'string',
-        choices: ['json', 'text'],
-        default: 'json',
-        description: 'Output format'
-    }), async (args) => {
-        const exitCode = await (0, ai_1.aiCommand)(process.cwd(), args.action, {
-            id: args.id,
-            ids: args.ids,
-            assignee: args.assignee,
-            epic: args.epic,
-            milestone: args.milestone,
-            estimate: args.estimate,
-            status: args.status,
-            priority: args.priority,
-            refinementState: args.refinementState,
-            dueDate: args.dueDate,
-            tags: args.tags,
-            limit: args.limit,
-            dryRun: args.dryRun,
-            file: args.file,
-            format: args.format,
-            only: args.only,
-            compact: args.compact,
-            expectedUpdatedAt: args.expectedUpdatedAt,
-            command: args.command
-        });
-        process.exit(exitCode);
-    })
-        .command('init', 'Initialize PlanFS repository structure', (y) => y.option('format', {
-        type: 'string',
-        choices: ['text', 'json'],
-        default: 'text',
-        description: 'Output format'
-    }), async (args) => {
-        const exitCode = await (0, init_1.initCommand)(process.cwd(), {
-            format: args.format
-        });
-        process.exit(exitCode);
-    })
-        .command('validate', 'Validate the PlanFS repository', (y) => y
-        .option('verbose', {
-        alias: 'v',
-        type: 'boolean',
-        description: 'Show detailed output',
-        default: false
-    })
-        .option('strict', {
-        type: 'boolean',
-        default: false,
-        description: 'Fail when validation warnings are present'
-    })
-        .option('format', {
-        type: 'string',
-        choices: ['text', 'json'],
-        default: 'text',
-        description: 'Output format'
-    }), async (args) => {
-        const exitCode = await (0, validate_1.validateCommand)(process.cwd(), {
-            verbose: args.verbose,
-            strict: args.strict,
-            format: args.format
-        });
-        process.exit(exitCode);
-    })
-        .command('doctor', 'Report actionable plan-health issues separately from historical references', (y) => y.option('format', { type: 'string', choices: ['text', 'json'], default: 'text' }), async (args) => {
-        process.exit(await (0, doctor_1.doctorCommand)(process.cwd(), { format: args.format }));
-    })
-        .command('migrate', 'Preview or apply a PlanFS format migration', (y) => y.option('apply', { type: 'boolean', default: false }).option('format', { type: 'string', choices: ['text', 'json'], default: 'text' }), async (args) => {
-        process.exit(await (0, migrate_1.migrateCommand)(process.cwd(), { apply: args.apply, format: args.format }));
-    })
-        .command('update <id>', 'Preview or update common entity metadata', (y) => y.positional('id', { type: 'string' }).option('title', { type: 'string' }).option('status', { type: 'string' }).option('owner', { type: 'string' }).option('assignee', { type: 'string' }).option('priority', { type: 'string' }).option('target-date', { type: 'string' }).option('clear', { type: 'array', string: true, description: 'Explicitly clear optional fields' }).option('expected-updated-at', { type: 'string' }).option('dry-run', { type: 'boolean', default: false }).option('format', { type: 'string', choices: ['text', 'json'], default: 'text' }), async (args) => {
-        const patch = { title: args.title, status: args.status, owner: args.owner, assignee: args.assignee, priority: args.priority, targetDate: args.targetDate };
-        for (const field of args.clear ?? [])
-            patch[field] = '__clear__';
-        process.exit(await (0, update_1.updateCommand)(process.cwd(), args.id, { patch, expectedUpdatedAt: args.expectedUpdatedAt, dryRun: args.dryRun, format: args.format }));
-    })
-        .command('filter <action>', 'Manage repository-shared saved filters', (y) => y.positional('action', { choices: ['list', 'show', 'save', 'delete'] }).option('id', { type: 'string' }).option('name', { type: 'string' }).option('description', { type: 'string' }).option('criteria', { type: 'string', description: 'Filter criteria as JSON' }).option('dry-run', { type: 'boolean', default: false }).option('format', { type: 'string', choices: ['text', 'json'], default: 'text' }), async (args) => process.exit(await (0, filter_1.filterCommand)(process.cwd(), args.action, { id: args.id, name: args.name, description: args.description, criteria: args.criteria, dryRun: args.dryRun, format: args.format })))
-        .command('history <id>', 'Show Git history for a PlanFS entity', (y) => y.positional('id', { type: 'string' }).option('format', { type: 'string', choices: ['text', 'json'], default: 'text' }), async (args) => process.exit(await (0, history_1.historyCommand)(process.cwd(), args.id, args.format)))
-        .command('branch', 'Show PlanFS changes on the current Git branch', (y) => y
-        .option('base', {
-        type: 'string',
-        description: 'Base branch or ref to compare against'
-    })
-        .option('format', {
-        type: 'string',
-        choices: ['text', 'json'],
-        default: 'text',
-        description: 'Output format'
-    }), async (args) => {
-        const exitCode = await (0, branch_1.branchCommand)(process.cwd(), {
-            base: args.base,
-            format: args.format
-        });
-        process.exit(exitCode);
-    })
-        .command('git <action> [message..]', 'Use Git-aware PlanFS helpers', (y) => y
-        .positional('action', {
-        describe: 'Git helper to run',
-        choices: ['commit-message', 'validate-message']
-    })
-        .positional('message', {
-        describe: 'Commit message to validate',
-        type: 'string'
-    })
-        .option('base', {
-        type: 'string',
-        description: 'Base branch or ref for commit message suggestions'
-    })
-        .option('format', {
-        type: 'string',
-        choices: ['text', 'json'],
-        default: 'text',
-        description: 'Output format'
-    }), async (args) => {
-        const message = Array.isArray(args.message)
-            ? args.message.join(' ')
-            : args.message;
-        const exitCode = await (0, git_1.gitCommand)(process.cwd(), args.action, message, {
-            base: args.base,
-            format: args.format
-        });
-        process.exit(exitCode);
-    })
-        .command('pr <action>', 'Generate pull request planning context', (y) => y
-        .positional('action', {
-        describe: 'Pull request helper to run',
-        choices: ['summary', 'providers']
-    })
-        .option('base', {
-        type: 'string',
-        description: 'Base branch or ref to compare against'
-    })
-        .option('provider', {
-        type: 'string',
-        choices: ['github', 'gitlab', 'azure-devops'],
-        default: 'github',
-        description: 'Pull request provider'
-    })
-        .option('format', {
-        type: 'string',
-        choices: ['markdown', 'json'],
-        default: 'markdown',
-        description: 'Output format'
-    }), async (args) => {
-        const exitCode = await (0, pr_1.pullRequestCommand)(process.cwd(), args.action, {
-            base: args.base,
-            provider: args.provider,
-            format: args.format
-        });
-        process.exit(exitCode);
-    })
-        .command('archive <action>', 'Archive, restore, and browse hidden PlanFS tasks and epics', (y) => y
-        .positional('action', {
-        describe: 'Archive workflow to run',
-        choices: ['list', 'archive', 'restore', 'delete']
-    })
-        .option('id', {
-        type: 'string',
-        description: 'Task or epic ID'
-    })
-        .option('include-children', {
-        type: 'boolean',
-        default: false,
-        description: 'When archiving an epic, also archive child tasks'
-    })
-        .option('dry-run', {
-        type: 'boolean',
-        default: false,
-        description: 'Preview archive changes without writing files'
-    })
-        .option('expected-updated-at', {
-        type: 'string',
-        description: 'Refuse archive if the target updatedAt has changed'
-    })
-        .option('yes', {
-        type: 'boolean',
-        default: false,
-        description: 'Confirm permanent archive deletion'
-    })
-        .option('disposition', { type: 'string', choices: ['completed', 'cancelled', 'duplicate', 'deferred', 'superseded'], description: 'Reason for archiving unfinished work' })
-        .option('note', { type: 'string', description: 'Optional archive note' })
-        .option('format', {
-        type: 'string',
-        choices: ['text', 'json'],
-        default: 'text',
-        description: 'Output format'
-    }), async (args) => {
-        const exitCode = await (0, archive_1.archiveCommand)(process.cwd(), args.action, {
-            id: args.id,
-            includeChildren: args.includeChildren,
-            dryRun: args.dryRun,
-            expectedUpdatedAt: args.expectedUpdatedAt,
-            yes: args.yes,
-            disposition: args.disposition,
-            note: args.note,
-            format: args.format
-        });
-        process.exit(exitCode);
-    })
-        .command('backlog <action>', 'Manage backlog intake, refinement, and hygiene', (y) => y
-        .positional('action', {
-        describe: 'Backlog workflow to run',
-        choices: ['list', 'capture', 'set-state', 'review']
-    })
-        .option('title', {
-        alias: 't',
-        type: 'string',
-        description: 'Title for captured backlog items'
-    })
-        .option('id', {
-        type: 'string',
-        description: 'Task ID to update'
-    })
-        .option('state', {
-        type: 'string',
-        choices: ['captured', 'needs-refinement', 'ready', 'deferred', 'discarded'],
-        description: 'Backlog refinement state'
-    })
-        .option('assignee', {
-        type: 'string',
-        description: 'Filter or set assignee'
-    })
-        .option('epic', {
-        type: 'string',
-        description: 'Filter or set epic'
-    })
-        .option('milestone', {
-        type: 'string',
-        description: 'Filter or set milestone'
-    })
-        .option('priority', {
-        type: 'string',
-        choices: ['low', 'medium', 'high', 'critical'],
-        description: 'Filter or set priority'
-    })
-        .option('tag', {
-        type: 'array',
-        string: true,
-        description: 'Filter by tag'
-    })
-        .option('query', {
-        type: 'string',
-        description: 'Filter by text query'
-    })
-        .option('body', {
-        type: 'string',
-        description: 'Markdown body for captured backlog items'
-    })
-        .option('limit', {
-        type: 'number',
-        description: 'Maximum number of items to show'
-    })
-        .option('format', {
-        type: 'string',
-        choices: ['text', 'json'],
-        default: 'text',
-        description: 'Output format'
-    }), async (args) => {
-        const exitCode = await (0, backlog_1.backlogCommand)(process.cwd(), args.action, {
-            title: args.title,
-            id: args.id,
-            state: args.state,
-            assignee: args.assignee,
-            epic: args.epic,
-            milestone: args.milestone,
-            priority: args.priority,
-            tag: args.tag,
-            query: args.query,
-            body: args.body,
-            limit: args.limit,
-            format: args.format
-        });
-        process.exit(exitCode);
-    })
-        .command('next', 'List ranked next-work candidates', (y) => y
-        .option('assignee', {
-        type: 'string',
-        description: 'Filter by assignee'
-    })
-        .option('epic', {
-        type: 'string',
-        description: 'Filter by epic'
-    })
-        .option('milestone', {
-        type: 'string',
-        description: 'Filter by milestone'
-    })
-        .option('tag', {
-        type: 'array',
-        string: true,
-        description: 'Filter by tag'
-    })
-        .option('status', {
-        type: 'array',
-        string: true,
-        choices: ['todo', 'in-progress', 'review', 'done'],
-        description: 'Filter by status'
-    })
-        .option('include-blocked', {
-        type: 'boolean',
-        default: false,
-        description: 'Include blocked and missing-dependency tasks'
-    })
-        .option('explain', {
-        type: 'boolean',
-        default: false,
-        description: 'Show all ranking reasons'
-    })
-        .option('limit', {
-        type: 'number',
-        description: 'Maximum number of candidates to show'
-    })
-        .option('format', {
-        type: 'string',
-        choices: ['text', 'json'],
-        default: 'text',
-        description: 'Output format'
-    }), async (args) => {
-        const exitCode = await (0, next_1.nextCommand)(process.cwd(), {
-            assignee: args.assignee,
-            epic: args.epic,
-            milestone: args.milestone,
-            tag: args.tag,
-            status: args.status,
-            includeBlocked: args.includeBlocked,
-            explain: args.explain,
-            limit: args.limit,
-            format: args.format
-        });
-        process.exit(exitCode);
-    })
-        .command('list [type]', 'List entities', (y) => y
-        .positional('type', {
-        describe: 'Entity type to list',
-        choices: ['tasks', 'epics', 'milestones', 'decisions'],
-        default: 'tasks'
-    })
-        .option('status', {
-        type: 'string',
-        description: 'Filter by status'
-    })
-        .option('assignee', {
-        type: 'string',
-        description: 'Filter by assignee'
-    })
-        .option('epic', {
-        type: 'string',
-        description: 'Filter by epic'
-    })
-        .option('format', {
-        type: 'string',
-        choices: ['table', 'json'],
-        default: 'table',
-        description: 'Output format'
-    }), async (args) => {
-        const exitCode = await (0, list_1.listCommand)(process.cwd(), {
-            type: args.type,
-            status: args.status,
-            assignee: args.assignee,
-            epic: args.epic,
-            format: args.format
-        });
-        process.exit(exitCode);
-    })
-        .command('show <id>', 'Show entity details', (y) => y
-        .positional('id', {
-        describe: 'Entity ID to show'
-    })
-        .option('format', {
-        type: 'string',
-        choices: ['pretty', 'json'],
-        default: 'pretty'
-    }), async (args) => {
-        const exitCode = await (0, show_1.showCommand)(process.cwd(), args.id, {
-            format: args.format
-        });
-        process.exit(exitCode);
-    })
-        .command('create <type>', 'Create new entity', (y) => y
-        .positional('type', {
-        describe: 'Entity type to create',
-        choices: ['task', 'epic', 'milestone', 'decision']
-    })
-        .option('title', {
-        alias: 't',
-        type: 'string',
-        description: 'Entity title'
-    })
-        .option('status', {
-        type: 'string',
-        description: 'Initial status'
-    })
-        .option('priority', {
-        type: 'string',
-        description: 'Priority (for tasks)'
-    })
-        .option('assignee', {
-        type: 'string',
-        description: 'Assignee'
-    })
-        .option('owner', {
-        type: 'string',
-        description: 'Owner for epics and milestones'
-    })
-        .option('description', {
-        type: 'string',
-        description: 'Description/body for epics and milestones'
-    })
-        .option('target-date', {
-        type: 'string',
-        description: 'Target date for milestones'
-    })
-        .option('dry-run', {
-        type: 'boolean',
-        default: false,
-        description: 'Preview created Markdown without writing files'
-    })
-        .option('format', {
-        type: 'string',
-        choices: ['text', 'json'],
-        default: 'text',
-        description: 'Output format'
-    }), async (args) => {
-        const exitCode = await (0, create_1.createCommand)(process.cwd(), args.type, {
-            title: args.title,
-            status: args.status,
-            priority: args.priority,
-            assignee: args.assignee,
-            owner: args.owner,
-            description: args.description,
-            targetDate: args.targetDate,
-            dryRun: args.dryRun,
-            format: args.format
-        });
-        process.exit(exitCode);
-    })
+    const cli = (0, entity_commands_1.registerEntityCommands)((0, workflow_commands_1.registerWorkflowCommands)((0, planning_commands_1.registerPlanningCommands)((0, yargs_1.default)((0, helpers_1.hideBin)(process.argv)).version(package_json_1.default.version))));
+    await cli
         .demandCommand(1, 'You must provide a command')
         .help()
         .strict()