perttool 0.10.5 → 0.11.0

package/dist/cli.js

@@ -7,11 +7,11 @@ import { createNodeHost } from "./node/host.js";
 import { createHistoricalGraphGitEvidenceHost } from "./node/historical-host.js";
 import { exportMermaid, } from "./conversion/mermaid.js";
 import { importMermaid } from "./conversion/mermaid-import.js";
-import { getContract9Guide as getAssuranceGuide, renderContract9GuideResult as renderAssuranceGuideResult, serializeContract9GuideResult as serializeAssuranceGuideResult, } from "./help/contract9-guide.js";
+import { getContract10Guide as getAssuranceGuide, renderContract10GuideResult as renderAssuranceGuideResult, serializeContract10GuideResult as serializeAssuranceGuideResult, } from "./help/contract10-guide.js";
 import { commandOptionSets, } from "./command/registry.js";
-import { CONTRACT9_COMMAND_REGISTRY as ASSURANCE_COMMAND_REGISTRY, getContract9CommandDiscovery as getAssuranceCommandDiscovery, renderContract9CommandHelpResult as renderAssuranceCommandHelpResult, serializeContract9CommandHelpResult as serializeAssuranceCommandHelpResult, } from "./command/contract9-discovery.js";
+import { CONTRACT10_COMMAND_REGISTRY as ASSURANCE_COMMAND_REGISTRY, getContract10CommandDiscovery as getAssuranceCommandDiscovery, renderContract10CommandHelpResult as renderAssuranceCommandHelpResult, serializeContract10CommandHelpResult as serializeAssuranceCommandHelpResult, } from "./command/contract10-discovery.js";
 import { handlerCommandUsageError, } from "./command/usage.js";
-import { renderContract9CommandUsageError as renderAssuranceCommandUsageError, serializeContract9CommandUsageError as serializeAssuranceCommandUsageError, validateContract9CommandInvocation as validateAssuranceCommandInvocation, } from "./command/contract9-usage.js";
+import { renderContract10CommandUsageError as renderAssuranceCommandUsageError, serializeContract10CommandUsageError as serializeAssuranceCommandUsageError, validateContract10CommandInvocation as validateAssuranceCommandInvocation, } from "./command/contract10-usage.js";
 import { agentGuidanceResultToJson } from "./guidance/projection.js";
 import { agentGuidanceExitCode, renderAgentGuidanceText, } from "./guidance/text.js";
 import { SafeWriteConflictError, SafeWriteVerificationError, } from "./io/safe-write.js";
@@ -20,14 +20,14 @@ import { formatDecimal } from "./model/rational.js";
 import { convertWithVelocity, durationSuffix } from "./model/units.js";
 import { recommendationInvariantExitCode } from "./recommendation/failure.js";
 import { recommendationAnalysisToJson } from "./recommendation/json.js";
-import { applyTextEdits, normalizeTextEdits } from "./mutation/text-edits.js";
+import { applyTextEdits, normalizeTextEdits, } from "./mutation/text-edits.js";
 import { createUnifiedDiff } from "./editing/unified-diff.js";
 import { sha256DigestUtf8 } from "./model/sha256.js";
 import { TARGET_GRAMMAR_6_CAPABILITY, } from "./parser/document-parser.js";
 import { exportPlanAssuranceMermaid, importPlanAssuranceMermaid, } from "./assurance/mermaid.js";
 import { getJsonSchemaResult, renderJsonSchemaResult, serializeJsonSchemaResult, } from "./schema/registry.js";
 import { TOOL_VERSION } from "./version.js";
-import { analyzeDocument as analyzeContract8Document, checkDocument as checkContract8Document, selectNextTasks as selectContract8NextTasks, } from "./application/contract9-temporal.js";
+import { analyzeDocument as analyzeContract8Document, checkDocument as checkContract8Document, planGrammarMigration as planContract10GrammarMigration, selectNextTasks as selectContract8NextTasks, } from "./application/contract10-runtime.js";
 import { contract9CheckResultToJson, contract9ProjectResultToJson, liftContract9AnalysisResultJson, liftContract9NextResultJson, renderContract9ScheduleAlerts, contract9WireJson, } from "./application/contract9-projection.js";
 import { planContract9GrammarMigration } from "./application/contract9-format-migration.js";
 import { planContract9TemporalMutation } from "./application/contract9-temporal-mutation.js";
@@ -36,8 +36,18 @@ import { planAcceptanceReceiptMutation, planCriterionSetReplacement, showMilesto
 import { scanTemporalDeclarationBlocks, temporalScheduleBaseText, } from "./temporal-schedule/source-lexical.js";
 import { planMilestoneAcceptanceMigration, recheckCommittedMigrationProof, } from "./milestone-acceptance/migration.js";
 import { MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY, milestoneAcceptanceBaseText, parseMilestoneAcceptanceSource } from "./milestone-acceptance/source.js";
-import { coalesceMilestoneAcceptanceDeletionOverlaps, planMilestoneAcceptanceAdvance, preserveMilestoneAcceptanceRecords, } from "./milestone-acceptance/advance.js";
-const { analyzeDocument: _analyzeContract7Document, checkDocument: _checkContract7Document, selectNextTasks: _selectContract7NextTasks, planFormat, planProjectInit, projectInitResultToJson, renderProjectInitResult, withProjectInitOutput, planUnitMigration, withUnitMigrationWrite, getProjectMetadata, contract7ProjectResultToJson, renderContract7ProjectText, planAdvance, planBatchMutation, planFinishActuals, planLifecycle, planMutation, planAssuranceMutation, renderTargetGovernanceDecision, contract7InspectionResultToJson, contract7MutationResultToJson, contract7SnakeJson, contract6WorkEventToJson, renderAdvanceHistoryGuard, prepareTargetPlanAssuranceAdvanceHistory, prepareAdvanceHistory, withAdvanceHistoryRace, withTargetPlanAssuranceAdvanceHistoryRace, persistTargetPlanAssuranceResult, inspectTargetPlanAssurance, inspectTargetCurrentProjectActuals, inspectTargetProjectHistoryFile, renderTargetProjectHistoryText, targetProjectHistoryResultToJson, observeTargetProjectVelocity, renderTargetVelocityObservationText, targetVelocityObservationResultToJson, getAgentHelp, documentContentFromBytes, readDocumentContent, readBytes, recheckAdvanceHistoryBaseline, captureAdvanceHistoryBaseline, createArtifactFile, createValidatedDocumentFile, createTargetGrammar6DocumentFile, replaceTargetGrammar6DocumentFile, replaceValidatedDocumentFile, inspectTargetHistoricalGraphFile, renderTargetHistoricalGraphText, targetHistoricalGraphResultToJson, } = createCliApplicationFacade(createNodeHost(), createHistoricalGraphGitEvidenceHost());
+import { planMilestoneAcceptanceAdvance, prepareMilestoneAcceptanceAdvanceEdits, preserveMilestoneAcceptanceRecords, } from "./milestone-acceptance/advance.js";
+import { beginPlanningPoolReshapeCommit, inspectPlanningPool, observeCurrentPlanningPool, planPlanningWindowMutation, preflightPlanningPoolReshape, preparePlanningPoolReshapeApply, recoverPlanningPoolReshapeCommit, settlePlanningPoolReshapeCommit, } from "./application/contract10-planning.js";
+import { observeHistoricalPlanningPool } from "./application/contract10-planning-history.js";
+import { parsePlanningPoolSource, PLANNING_POOL_SOURCE_CAPABILITY, } from "./planning-pool/source.js";
+import { planPlanningAdvanceCleanup } from "./planning-pool/advance.js";
+import { planningPoolBaseText, scanPlanningDeclarationBlocks, } from "./planning-pool/source-lexical.js";
+import { assessPlanningHistoryBaseline, planningHistoryNotApplicable, } from "./planning-pool/history-guard.js";
+import { withPlanningReshapeTokenRegistry } from "./node/planning-token-store.js";
+import { compilePlanningIntentRequest, isPlanningIntentRequest, } from "./planning-pool/intent.js";
+import { renderPlanningHistoricalObservationText, renderPlanningObservationText, renderPlanningPoolReadText, renderPlanningReshapePreflightText, } from "./planning-pool/human.js";
+const historicalGitEvidenceHost = createHistoricalGraphGitEvidenceHost();
+const { analyzeDocument: _analyzeContract7Document, checkDocument: _checkContract7Document, selectNextTasks: _selectContract7NextTasks, planFormat, planProjectInit, projectInitResultToJson, renderProjectInitResult, withProjectInitOutput, planUnitMigration, withUnitMigrationWrite, getProjectMetadata, contract7ProjectResultToJson, renderContract7ProjectText, planAdvance, planBatchMutation, planFinishActuals, planLifecycle, planMutation, planAssuranceMutation, renderTargetGovernanceDecision, contract7InspectionResultToJson, contract7MutationResultToJson, contract7SnakeJson, contract6WorkEventToJson, renderAdvanceHistoryGuard, prepareTargetPlanAssuranceAdvanceHistory, prepareAdvanceHistory, withAdvanceHistoryRace, withTargetPlanAssuranceAdvanceHistoryRace, persistTargetPlanAssuranceResult, inspectTargetPlanAssurance, inspectTargetCurrentProjectActuals, inspectTargetProjectHistoryFile, renderTargetProjectHistoryText, targetProjectHistoryResultToJson, observeTargetProjectVelocity, renderTargetVelocityObservationText, targetVelocityObservationResultToJson, getAgentHelp, documentContentFromBytes, readDocumentContent, readBytes, recheckAdvanceHistoryBaseline, captureAdvanceHistoryBaseline, createArtifactFile, createValidatedDocumentFile, createTargetGrammar6DocumentFile, replaceTargetGrammar6DocumentFile, replaceValidatedDocumentFile, inspectTargetHistoricalGraphFile, renderTargetHistoricalGraphText, targetHistoricalGraphResultToJson, } = createCliApplicationFacade(createNodeHost(), historicalGitEvidenceHost);
 const analyzeDocument = analyzeContract8Document;
 const checkDocument = checkContract8Document;
 const selectNextTasks = selectContract8NextTasks;
@@ -221,7 +231,7 @@ async function readStdin() {
 function writeJson(value) {
     const contract8Value = typeof value === "object" && value !== null && !Array.isArray(value) &&
         "cli_contract_version" in value
-        ? { ...value, cli_contract_version: 9 }
+        ? { ...value, cli_contract_version: 10 }
         : value;
     process.stdout.write(`${JSON.stringify(contract8Value)}\n`);
 }
@@ -532,15 +542,20 @@ async function persistContract8CandidateResult(result, request) {
     if (!result.ok || !result.governance?.writeAuthorized || result.updatedText === null) {
         throw new TypeError("authorized Contract 8 result does not contain a digest-bound candidate");
     }
-    const validator = /^  version 8$/mu.test(result.updatedText)
+    const validator = /^  version 9$/mu.test(result.updatedText)
         ? (candidate) => {
-            const checked = checkDocument(candidate);
-            return { ok: checked.ok, diagnostics: checked.diagnostics };
+            const parsed = parsePlanningPoolSource(candidate, PLANNING_POOL_SOURCE_CAPABILITY);
+            return { ok: parsed.ok, diagnostics: parsed.diagnostics };
         }
-        : (candidate) => {
-            const parsed = parseMilestoneAcceptanceSource(candidate, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
-            return { ok: parsed.ok, diagnostics: [] };
-        };
+        : /^  version 8$/mu.test(result.updatedText)
+            ? (candidate) => {
+                const checked = checkDocument(candidate);
+                return { ok: checked.ok, diagnostics: checked.diagnostics };
+            }
+            : (candidate) => {
+                const parsed = parseMilestoneAcceptanceSource(candidate, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
+                return { ok: parsed.ok, diagnostics: [] };
+            };
     if (request.mode === "in_place") {
         await replaceValidatedDocumentFile(request.target, result.updatedText, {
             initialDigest: result.originalDigest,
@@ -563,19 +578,19 @@ async function commitCandidate(request, candidateText, initialDigest) {
     if (candidateText === null) {
         throw new SafeWriteVerificationError("invalid_candidate", "successful editing result has no candidate text");
     }
+    if (/^  version 9$/mu.test(candidateText)) {
+        const validator = (candidate) => {
+            const parsed = parsePlanningPoolSource(candidate, PLANNING_POOL_SOURCE_CAPABILITY);
+            return { ok: parsed.ok, diagnostics: parsed.diagnostics };
+        };
+        return commitValidatedCandidate(request, candidateText, initialDigest, validator);
+    }
     if (/^  version 8$/mu.test(candidateText)) {
         const validator = (candidate) => {
             const checked = checkDocument(candidate);
             return { ok: checked.ok, diagnostics: checked.diagnostics };
         };
-        return request.mode === "in_place"
-            ? replaceValidatedDocumentFile(request.target, candidateText, {
-                initialDigest,
-                ...(request.expectedDigest === undefined
-                    ? {}
-                    : { expectedDigest: request.expectedDigest }),
-            }, validator)
-            : createValidatedDocumentFile(request.target, candidateText, validator);
+        return commitValidatedCandidate(request, candidateText, initialDigest, validator);
     }
     const acceptanceSource = parseMilestoneAcceptanceSource(candidateText, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
     if (acceptanceSource.grammarVersion === 7) {
@@ -583,14 +598,7 @@ async function commitCandidate(request, candidateText, initialDigest) {
             const parsed = parseMilestoneAcceptanceSource(candidate, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
             return { ok: parsed.ok, diagnostics: [] };
         };
-        return request.mode === "in_place"
-            ? replaceValidatedDocumentFile(request.target, candidateText, {
-                initialDigest,
-                ...(request.expectedDigest === undefined
-                    ? {}
-                    : { expectedDigest: request.expectedDigest }),
-            }, validator)
-            : createValidatedDocumentFile(request.target, candidateText, validator);
+        return commitValidatedCandidate(request, candidateText, initialDigest, validator);
     }
     return request.mode === "in_place"
         ? replaceTargetGrammar6DocumentFile(request.target, candidateText, TARGET_GRAMMAR_6_CAPABILITY, {
@@ -601,6 +609,17 @@ async function commitCandidate(request, candidateText, initialDigest) {
         })
         : createTargetGrammar6DocumentFile(request.target, candidateText, TARGET_GRAMMAR_6_CAPABILITY);
 }
+function commitValidatedCandidate(request, candidateText, initialDigest, validator) {
+    if (request.mode === "out") {
+        return createValidatedDocumentFile(request.target, candidateText, validator);
+    }
+    return replaceValidatedDocumentFile(request.target, candidateText, {
+        initialDigest,
+        ...(request.expectedDigest === undefined
+            ? {}
+            : { expectedDigest: request.expectedDigest }),
+    }, validator);
+}
 function writeFailureExit(error, operation, json) {
     const normalized = error instanceof Error ? error : new Error(String(error));
     const exitCode = normalized instanceof SafeWriteConflictError
@@ -616,6 +635,39 @@ function renderWriteSummary(operation, result) {
 function renderGovernanceWriteSummary(operation, result, digest) {
     return `WRITE ${operation} mode=${result.mode} target=${result.target ?? "-"} digest=${digest ?? "-"} written=${result.written}\n`;
 }
+function grammarMigrationResultJson(result, source, sourceDigest, write) {
+    return Object.freeze({
+        schema_version: "Perttool.UnitMigrationResult.v5",
+        cli_contract_version: 10,
+        tool_version: TOOL_VERSION,
+        operation: "document.migrate",
+        ok: result.ok,
+        document_id: result.documentId,
+        source,
+        source_digest: sourceDigest,
+        diagnostics: planningDiagnosticsJson(result.diagnostics),
+        diagnostics_truncated: result.diagnosticsTruncated,
+        source_grammar_version: result.sourceGrammarVersion,
+        target_grammar_version: result.targetGrammarVersion,
+        changed: result.changed,
+        migrated_task_ids: [...result.migratedTaskIds],
+        required_action: result.requiredAction,
+        original_digest: result.originalDigest,
+        updated_digest: result.updatedDigest,
+        updated_text: result.updatedText,
+        diff: result.diff,
+        edits: snakeJson(result.edits),
+        write,
+    });
+}
+function emitGrammarMigrationResult(format, result, sourceOperand, sourceDigest, write, diffOnly) {
+    if (format === "json") {
+        writeJson(grammarMigrationResultJson(result, sourceOperand === "-" ? "<stdin>" : sourceOperand, sourceDigest, write));
+    }
+    else if (result.updatedText !== null) {
+        process.stdout.write(diffOnly ? result.diff ?? "" : result.updatedText);
+    }
+}
 async function runContract9DocumentMigration(args) {
     const parsed = parseCommandOptions("document.migrate", args);
     if (parsed.positionals.length !== 1 || parsed.values.get("target-grammar") !== "8")
@@ -624,16 +676,49 @@ async function runContract9DocumentMigration(args) {
     const format = outputFormat(parsed.values.get("format"));
     const input = await readDocument(sourceOperand);
     const result = planContract9GrammarMigration(input.text);
+    let written = false;
     if (result.ok && result.updatedText !== null && parsed.flags.has("write")) {
         if (sourceOperand === "-")
             throw new UsageError("document migrate --write requires a file");
         await replaceValidatedDocumentFile(sourceOperand, result.updatedText, { initialDigest: input.digest, ...(parsed.values.get("expect-digest") === undefined ? {} : { expectedDigest: parsed.values.get("expect-digest") }) }, (candidate) => ({ ok: checkDocument(candidate).ok, diagnostics: [] }));
+        written = result.changed;
     }
-    if (format === "json")
-        writeJson({ schema_version: "Perttool.UnitMigrationResult.v4", cli_contract_version: 9,
-            tool_version: TOOL_VERSION, operation: "document.migrate", ...snakeJson(result) });
-    else if (result.updatedText !== null)
-        process.stdout.write(parsed.flags.has("diff") ? result.diff ?? "" : result.updatedText);
+    emitGrammarMigrationResult(format, result, sourceOperand, input.digest, Object.freeze({
+        mode: parsed.flags.has("write") ? "in_place" : "preview",
+        target: parsed.flags.has("write") ? sourceOperand : null,
+        written,
+    }), parsed.flags.has("diff"));
+    return result.ok ? 0 : 1;
+}
+async function runContract10DocumentMigration(args) {
+    const parsed = parseCommandOptions("document.migrate", args);
+    if (parsed.positionals.length !== 1 || parsed.values.get("target-grammar") !== "9") {
+        throw new UsageError("document migrate requires <file> --target-grammar 9");
+    }
+    const sourceOperand = parsed.positionals[0];
+    const format = outputFormat(parsed.values.get("format"));
+    const input = await readDocument(sourceOperand);
+    const result = planContract10GrammarMigration(input.text);
+    let written = false;
+    if (result.ok && result.updatedText !== null && parsed.flags.has("write")) {
+        if (sourceOperand === "-")
+            throw new UsageError("document migrate --write requires a file");
+        await replaceValidatedDocumentFile(sourceOperand, result.updatedText, {
+            initialDigest: input.digest,
+            ...(parsed.values.get("expect-digest") === undefined
+                ? {}
+                : { expectedDigest: parsed.values.get("expect-digest") }),
+        }, (candidate) => {
+            const checked = parsePlanningPoolSource(candidate, PLANNING_POOL_SOURCE_CAPABILITY);
+            return { ok: checked.ok, diagnostics: checked.diagnostics };
+        });
+        written = result.changed;
+    }
+    emitGrammarMigrationResult(format, result, sourceOperand, input.digest, Object.freeze({
+        mode: parsed.flags.has("write") ? "in_place" : "preview",
+        target: parsed.flags.has("write") ? sourceOperand : null,
+        written,
+    }), parsed.flags.has("diff"));
     return result.ok ? 0 : 1;
 }
 async function runFormat(args) {
@@ -1420,7 +1505,7 @@ function unitMigrationJson(result, source, sourceDigest, ok) {
     });
     return {
         schema_version: result.schemaVersion,
-        cli_contract_version: 9,
+        cli_contract_version: 10,
         tool_version: TOOL_VERSION,
         operation: "project.migrate-unit",
         ok,
@@ -1714,6 +1799,7 @@ function renderAdvanceSummary(details) {
     const list = (ids) => ids.join(",") || "-";
     return [
         `ADVANCE removed_tasks=${list(details.removedTaskIds)} removed_gates=${list(details.removedGateIds)} removed_milestones=${list(details.removedMilestoneIds)} removed_work_events=${list("removedWorkEventIds" in details ? details.removedWorkEventIds : [])}`,
+        `ADVANCE removed_planning_links=${list("removedPlanningLinks" in details ? details.removedPlanningLinks : [])} archived_works=${list("archivedWorkIds" in details ? details.archivedWorkIds : [])}`,
         `ADVANCE frontier_before=${list(details.frontierBefore)} frontier_after=${list(details.frontierAfter)} ready_before=${list(details.readyBefore)} ready_after=${list(details.readyAfter)}`,
         "",
     ].join("\n");
@@ -1765,7 +1851,14 @@ async function runAdvance(args) {
     catch (error) {
         return cliError(error instanceof Error ? error : new Error(String(error)), 3, "dag.advance", format === "json");
     }
-    const acceptancePlan = planMilestoneAcceptanceAdvance(input.text, {
+    const grammar9 = /^  version 9$/mu.test(input.text);
+    const strictInputText = grammar9
+        ? planningPoolBaseText(input.text, scanPlanningDeclarationBlocks(input.text))
+        : input.text;
+    const acceptanceInputText = /^  version 8$/mu.test(strictInputText)
+        ? temporalScheduleBaseText(strictInputText, scanTemporalDeclarationBlocks(strictInputText))
+        : strictInputText;
+    const acceptancePlan = planMilestoneAcceptanceAdvance(acceptanceInputText, {
         maxDiagnostics,
         originalLabel: source,
         updatedLabel: "candidate",
@@ -1778,8 +1871,8 @@ async function runAdvance(args) {
     if (!acceptancePlan.ok) {
         if (format === "json")
             writeJson({
-                schema_version: "Perttool.AdvanceResult.v3",
-                cli_contract_version: 8,
+                schema_version: "Perttool.AdvanceResult.v4",
+                cli_contract_version: 10,
                 tool_version: TOOL_VERSION,
                 operation: "dag.advance",
                 ok: false,
@@ -1802,6 +1895,8 @@ async function runAdvance(args) {
                     removedWorkEventIds: [],
                     removedAssuranceRecordIds: [],
                     updatedAssuranceReceiptIds: [],
+                    removedPlanningLinks: [],
+                    archivedWorkIds: [],
                 }),
                 history_guard: null,
                 assurance_guard: null,
@@ -1815,25 +1910,38 @@ async function runAdvance(args) {
         }
         return 1;
     }
-    const contract7BaseText = milestoneAcceptanceBaseText(input.text);
+    const contract7BaseText = milestoneAcceptanceBaseText(acceptanceInputText);
     const contract7Planned = planAdvance(contract7BaseText, {
         maxDiagnostics,
         originalLabel: source,
         updatedLabel: "candidate",
         governance: governanceRequest(parsed, writeRequest),
     });
-    const combinedEdits = contract7Planned.updatedText === null
+    const strictCombinedEdits = contract7Planned.updatedText === null
         ? contract7Planned.edits
-        : normalizeTextEdits(input.text, coalesceMilestoneAcceptanceDeletionOverlaps([
-            ...preserveMilestoneAcceptanceRecords(input.text, contract7Planned.edits, acceptancePlan.provisional.advance.keptMilestoneIds),
+        : normalizeTextEdits(acceptanceInputText, prepareMilestoneAcceptanceAdvanceEdits(acceptanceInputText, [
+            ...preserveMilestoneAcceptanceRecords(acceptanceInputText, contract7Planned.edits, acceptancePlan.provisional.advance.keptMilestoneIds),
             ...acceptancePlan.provisional.edits,
         ]), "Contract 8 acceptance-aware advance");
+    const planningCleanup = grammar9 && contract7Planned.updatedText !== null
+        ? planPlanningAdvanceCleanup(input.text, contract7Planned.advance?.removedMilestoneIds ?? [], contract7Planned.advance?.removedTaskIds ?? [], parsed.flags.has("archive-empty-work"))
+        : Object.freeze({
+            edits: Object.freeze([]),
+            removedPlanningLinks: Object.freeze([]),
+            archivedWorkIds: Object.freeze([]),
+            destructiveRecords: Object.freeze([]),
+        });
+    const combinedEdits = contract7Planned.updatedText === null
+        ? strictCombinedEdits
+        : normalizeTextEdits(input.text, [...strictCombinedEdits, ...planningCleanup.edits], "Contract 10 planning-aware advance");
     const combinedText = contract7Planned.updatedText === null
         ? null
         : applyTextEdits(input.text, combinedEdits);
     const combinedCheck = combinedText === null
         ? null
-        : checkContract8Document(combinedText, { maxDiagnostics });
+        : grammar9
+            ? checkDocument(combinedText, { maxDiagnostics })
+            : checkContract8Document(combinedText, { maxDiagnostics });
     if (combinedCheck !== null && !combinedCheck.ok) {
         throw new Error("acceptance-aware assurance advance lost Contract 8 validation");
     }
@@ -1842,7 +1950,7 @@ async function runAdvance(args) {
         : mergeAdvanceCandidateDiagnostics(combinedCheck.diagnostics, contract7Planned.diagnostics, maxDiagnostics);
     const planned = Object.freeze({
         ...contract7Planned,
-        schemaVersion: "Perttool.AdvanceResult.v3",
+        schemaVersion: "Perttool.AdvanceResult.v4",
         originalDigest: input.digest,
         updatedText: combinedText,
         updatedDigest: combinedText === null ? null : sha256DigestUtf8(combinedText),
@@ -1856,6 +1964,13 @@ async function runAdvance(args) {
             (combinedCheck?.diagnosticsTruncated ?? false) ||
             (combinedDiagnostics?.truncated ?? false),
         acceptanceGuard: acceptancePlan.acceptanceGuard,
+        advance: contract7Planned.advance === null
+            ? null
+            : Object.freeze({
+                ...contract7Planned.advance,
+                removedPlanningLinks: planningCleanup.removedPlanningLinks,
+                archivedWorkIds: planningCleanup.archivedWorkIds,
+            }),
     });
     const initialWarningFailure = parsed.flags.has("warnings-as-errors") &&
         (contract7Planned.diagnosticsTruncated ||
@@ -1873,8 +1988,16 @@ async function runAdvance(args) {
         warningDenied: initialWarningFailure,
         maxDiagnostics,
         documentValidator: (candidateText, candidateMaxDiagnostics) => {
-            const acceptanceSource = parseMilestoneAcceptanceSource(candidateText, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
-            const checked = checkContract8Document(candidateText, { maxDiagnostics: candidateMaxDiagnostics });
+            const planningBase = grammar9
+                ? planningPoolBaseText(candidateText, scanPlanningDeclarationBlocks(candidateText))
+                : candidateText;
+            const acceptanceBase = /^  version 8$/mu.test(planningBase)
+                ? temporalScheduleBaseText(planningBase, scanTemporalDeclarationBlocks(planningBase))
+                : planningBase;
+            const acceptanceSource = parseMilestoneAcceptanceSource(acceptanceBase, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
+            const checked = grammar9
+                ? checkDocument(candidateText, { maxDiagnostics: candidateMaxDiagnostics })
+                : checkContract8Document(candidateText, { maxDiagnostics: candidateMaxDiagnostics });
             return {
                 ok: checked.ok && acceptanceSource.ok,
                 document: checked.document,
@@ -1884,11 +2007,66 @@ async function runAdvance(args) {
             };
         },
     });
+    const planningAdvanceGuard = planningCleanup.destructiveRecords.length === 0
+        ? planningHistoryNotApplicable([], "no_canonical_records")
+        : writeRequest.mode === "preview"
+            ? planningHistoryNotApplicable(planningCleanup.destructiveRecords, "preview")
+            : writeRequest.mode === "out"
+                ? planningHistoryNotApplicable(planningCleanup.destructiveRecords, "separate_output")
+                : preparedBase.baseline === null
+                    ? planningHistoryNotApplicable(planningCleanup.destructiveRecords, "authority_denied")
+                    : assessPlanningHistoryBaseline(input.text, planningCleanup.destructiveRecords, preparedBase.baseline, forceRequested);
+    const planningAdvanceBlocked = planningAdvanceGuard.status === "blocked";
+    const baseHistoryGuard = preparedBase.result.historyGuard;
+    const combinedHistoryGuard = baseHistoryGuard === null
+        ? null
+        : planningCleanup.destructiveRecords.length === 0
+            ? baseHistoryGuard
+            : Object.freeze({
+                ...baseHistoryGuard,
+                status: planningAdvanceGuard.status === "blocked"
+                    ? "blocked"
+                    : planningAdvanceGuard.status === "forced"
+                        ? "forced"
+                        : baseHistoryGuard.status,
+                cause: planningAdvanceGuard.status === "passed" ||
+                    planningAdvanceGuard.status === "not_applicable"
+                    ? baseHistoryGuard.cause
+                    : planningAdvanceGuard.cause,
+                destructiveEntityIds: Object.freeze([...new Set([
+                        ...baseHistoryGuard.destructiveEntityIds,
+                        ...planningAdvanceGuard.destructiveEntityIds,
+                    ])].sort()),
+                overlappingEntityIds: Object.freeze([...new Set([
+                        ...baseHistoryGuard.overlappingEntityIds,
+                        ...planningAdvanceGuard.overlappingEntityIds,
+                    ])].sort()),
+            });
+    const preparedDiagnostics = planningAdvanceBlocked
+        ? limitDiagnostics(sortDiagnostics([
+            ...preparedBase.result.diagnostics,
+            Object.freeze({
+                code: "PTADV-101",
+                severity: "error",
+                message: "advance history proof is blocked for canonical planning facts",
+                helpTopic: "editing",
+                data: Object.freeze({
+                    cause: planningAdvanceGuard.cause,
+                    entity_ids: planningAdvanceGuard.overlappingEntityIds,
+                }),
+            }),
+        ]), maxDiagnostics)
+        : null;
     const prepared = Object.freeze({
         ...preparedBase,
         result: Object.freeze({
             ...preparedBase.result,
-            schemaVersion: "Perttool.AdvanceResult.v3",
+            schemaVersion: "Perttool.AdvanceResult.v4",
+            ok: preparedBase.result.ok && !planningAdvanceBlocked,
+            diagnostics: preparedDiagnostics?.diagnostics ?? preparedBase.result.diagnostics,
+            diagnosticsTruncated: preparedBase.result.diagnosticsTruncated ||
+                (preparedDiagnostics?.truncated ?? false),
+            historyGuard: combinedHistoryGuard,
             governance: planned.governance,
             assuranceGuard: planned.assuranceGuard,
             acceptanceGuard: acceptancePlan.acceptanceGuard,
@@ -1918,7 +2096,7 @@ async function runAdvance(args) {
                 if (!recheck.ok) {
                     result = Object.freeze({
                         ...withAdvanceHistoryRace(result, recheck, maxDiagnostics),
-                        schemaVersion: "Perttool.AdvanceResult.v3",
+                        schemaVersion: "Perttool.AdvanceResult.v4",
                         governance: result.governance,
                         assuranceGuard: result.assuranceGuard,
                         acceptanceGuard: result.acceptanceGuard,
@@ -1939,9 +2117,10 @@ async function runAdvance(args) {
     if (format === "json") {
         writeJson({
             ...contract7MutationResultToJson((ok ? result : Object.freeze({ ...result, ok: false })), "dag.advance", source, writeResult),
-            schema_version: "Perttool.AdvanceResult.v3",
-            cli_contract_version: 8,
+            schema_version: "Perttool.AdvanceResult.v4",
+            cli_contract_version: 10,
             acceptance_guard: snakeJson(result.acceptanceGuard),
+            advance: snakeJson(result.advance),
         });
     }
     else {
@@ -2783,10 +2962,13 @@ function renderNextText(result) {
     const unit = result.durationUnit;
     const taskById = new Map(result.tasks.map((task) => [task.id, task]));
     const authority = result.temporal.authority;
+    const runnableNow = new Set(result.groups.runnableNow);
+    const nonRunnableRecommended = authority.rawRecommendedTaskIds.filter((taskId) => !runnableNow.has(taskId));
     const lines = [
         "START AUTHORITY",
         `POLICY ${authority.policy}`,
         `STARTABLE RECOMMENDED ${authority.startableRecommendedTaskIds.join(",") || "-"}`,
+        `NON-RUNNABLE RAW RECOMMENDED ${nonRunnableRecommended.join(",") || "-"}`,
         `DELAYED RECOMMENDED ${authority.delayedRecommendedTaskIds.join(",") || "-"}`,
         `UNAVAILABLE RECOMMENDED ${authority.unavailableRecommendedTaskIds.join(",") || "-"}`,
         "DEADLINE FACTS INFORMATIONAL FOR RANKING v1",
@@ -2936,35 +3118,82 @@ function parseMilestoneAcceptanceCriteria(values) {
         };
     });
 }
+function liftAcceptanceMutationCandidate(text, base, planned) {
+    const originalDigest = sha256DigestUtf8(text);
+    const rebound = planned.governance === null
+        ? planned
+        : Object.freeze({
+            ...planned,
+            governance: Object.freeze({
+                ...planned.governance,
+                sourceDigest: originalDigest,
+            }),
+        });
+    if (planned.updatedText === null) {
+        return Object.freeze({ ...rebound, originalDigest });
+    }
+    const protectedRanges = maskedSourceLineRanges(text, base);
+    let edits;
+    let candidate;
+    try {
+        edits = normalizeTextEdits(base, planned.edits, "milestone acceptance lift");
+        if (protectedRanges === null ||
+            edits.some((edit) => protectedRanges.some((range) => textEditTouchesRange(edit, range))) ||
+            applyTextEdits(base, edits) !== planned.updatedText)
+            throw new Error("acceptance edits do not preserve the lowered source");
+        candidate = applyTextEdits(text, edits);
+    }
+    catch {
+        return Object.freeze({ ...rebound, ok: false, changed: false,
+            originalDigest, updatedDigest: null, updatedText: null,
+            edits: Object.freeze([]), diagnostics: Object.freeze([
+                ...rebound.diagnostics, "invalid_lifted_candidate",
+            ]) });
+    }
+    const checked = checkDocument(candidate);
+    if (!checked.ok)
+        return Object.freeze({ ...rebound, ok: false, changed: false,
+            originalDigest, updatedDigest: null, updatedText: null,
+            edits: Object.freeze([]), diagnostics: Object.freeze([
+                ...rebound.diagnostics, "invalid_lifted_candidate",
+            ]) });
+    return Object.freeze({ ...rebound, originalDigest, changed: candidate !== text,
+        updatedDigest: sha256DigestUtf8(candidate), updatedText: candidate,
+        edits: Object.freeze(edits) });
+}
+function maskedSourceLineRanges(text, base) {
+    if (text.length !== base.length)
+        return null;
+    const ranges = [];
+    let startOffset = 0;
+    while (startOffset < text.length) {
+        const newline = text.indexOf("\n", startOffset);
+        const endOffset = newline < 0 ? text.length : newline + 1;
+        if (text.slice(startOffset, endOffset) !== base.slice(startOffset, endOffset)) {
+            ranges.push(Object.freeze({ startOffset, endOffset }));
+        }
+        startOffset = endOffset;
+    }
+    return Object.freeze(ranges);
+}
+function textEditTouchesRange(edit, range) {
+    return edit.startOffset === edit.endOffset
+        ? edit.startOffset > range.startOffset && edit.startOffset < range.endOffset
+        : edit.startOffset < range.endOffset && edit.endOffset > range.startOffset;
+}
 function planContract9AcceptanceMutation(text, planner) {
     if (!/^  version 8$/mu.test(text))
         return planner(text);
     const base = temporalScheduleBaseText(text, scanTemporalDeclarationBlocks(text));
-    const planned = planner(base);
-    const originalDigest = sha256DigestUtf8(text);
-    if (!planned.ok || planned.updatedText === null) {
-        return Object.freeze({ ...planned, originalDigest });
-    }
-    let prefix = 0;
-    while (prefix < base.length &&
-        prefix < planned.updatedText.length &&
-        base[prefix] === planned.updatedText[prefix])
-        prefix += 1;
-    let suffix = 0;
-    while (suffix < base.length - prefix &&
-        suffix < planned.updatedText.length - prefix &&
-        base[base.length - 1 - suffix] ===
-            planned.updatedText[planned.updatedText.length - 1 - suffix])
-        suffix += 1;
-    const candidate = text.slice(0, prefix) +
-        planned.updatedText.slice(prefix, planned.updatedText.length - suffix) +
-        text.slice(text.length - suffix);
-    const checked = checkDocument(candidate);
-    if (!checked.ok)
-        return Object.freeze({ ...planned, ok: false, changed: false,
-            originalDigest, updatedDigest: null, updatedText: null });
-    return Object.freeze({ ...planned, originalDigest, changed: candidate !== text,
-        updatedDigest: sha256DigestUtf8(candidate), updatedText: candidate });
+    return liftAcceptanceMutationCandidate(text, base, planner(base));
+}
+function planContract10AcceptanceMutation(text, planner) {
+    if (!/^  version 9$/mu.test(text)) {
+        return planContract9AcceptanceMutation(text, planner);
+    }
+    const base = planningPoolBaseText(text, scanPlanningDeclarationBlocks(text));
+    const planned = planContract9AcceptanceMutation(base, planner);
+    return liftAcceptanceMutationCandidate(text, base, planned);
 }
 async function runMilestoneAcceptance(action, args) {
     const operation = `milestone-acceptance.${action}`;
@@ -2979,7 +3208,7 @@ async function runMilestoneAcceptance(action, args) {
             throw new UsageError("milestone acceptance show requires exactly one <file>");
         const result = checkDocument(input.text).acceptance ?? showMilestoneAcceptance(input.text, []);
         if (format === "json")
-            writeJson({ schema_version: "Perttool.MilestoneAcceptanceResult.v1", cli_contract_version: 8, tool_version: TOOL_VERSION, operation, ok: result.ok, milestones: snakeJson(result.milestones), diagnostics: snakeJson(result.diagnostics) });
+            writeJson({ schema_version: "Perttool.MilestoneAcceptanceResult.v1", cli_contract_version: 10, tool_version: TOOL_VERSION, operation, ok: result.ok, milestones: snakeJson(result.milestones), diagnostics: snakeJson(result.diagnostics) });
         else
             process.stdout.write(`${result.milestones.map(({ milestoneId, closure, acceptance }) => `${milestoneId} closure=${closure} acceptance=${acceptance}`).join("\n")}\n`);
         return result.ok ? 0 : 1;
@@ -2988,15 +3217,15 @@ async function runMilestoneAcceptance(action, args) {
         throw new UsageError(`${operation} requires four operands`);
     const request = editingWriteRequest(parsed, sourceOperand);
     if (request.mode === "out")
-        throw new UsageError(`${operation} does not support --out in Contract 8`);
+        throw new UsageError(`${operation} does not support --out in Contract 10`);
     const governance = governanceRequest(parsed, request);
     let result;
     if (action === "replace") {
         const criteria = parseMilestoneAcceptanceCriteria(parsed.repeatedValues.get("criterion") ?? []);
-        result = planContract9AcceptanceMutation(input.text, (text) => planCriterionSetReplacement(text, { milestoneId: parsed.positionals[1], setId: parsed.positionals[2], revisionId: parsed.positionals[3], criteria }, { governance }));
+        result = planContract10AcceptanceMutation(input.text, (text) => planCriterionSetReplacement(text, { milestoneId: parsed.positionals[1], setId: parsed.positionals[2], revisionId: parsed.positionals[3], criteria }, { governance }));
     }
     else {
-        result = planContract9AcceptanceMutation(input.text, (text) => planAcceptanceReceiptMutation(text, {
+        result = planContract10AcceptanceMutation(input.text, (text) => planAcceptanceReceiptMutation(text, {
             setId: parsed.positionals[1], criterionId: parsed.positionals[2], receiptId: parsed.positionals[3], action: action,
             ...(parsed.values.get("evidence-kind") === undefined ? {} : { evidenceKind: parsed.values.get("evidence-kind") }),
             ...(parsed.values.get("evidence-reference") === undefined ? {} : { evidenceReference: parsed.values.get("evidence-reference") }),
@@ -3009,13 +3238,18 @@ async function runMilestoneAcceptance(action, args) {
     }
     let written = false;
     if (result.ok && request.mode === "in_place" && result.changed) {
-        await commitCandidate(request, result.updatedText, input.digest);
-        written = true;
+        try {
+            await commitCandidate(request, result.updatedText, input.digest);
+            written = true;
+        }
+        catch (error) {
+            return writeFailureExit(error, operation, format === "json");
+        }
     }
     if (format === "json")
         writeJson({
             schema_version: "Perttool.MutationResult.v6",
-            cli_contract_version: 8,
+            cli_contract_version: 10,
             tool_version: TOOL_VERSION,
             operation,
             ok: result.ok,
@@ -3034,7 +3268,7 @@ async function runMilestoneAcceptance(action, args) {
             updated_digest: result.updatedDigest,
             updated_text: result.updatedText,
             diff: result.updatedText === null ? null : createUnifiedDiff(input.text, result.updatedText, { originalLabel: sourceOperand, updatedLabel: "candidate" }),
-            edits: result.changed && result.updatedText !== null ? [{ start_offset: 0, end_offset: input.text.length, replacement: result.updatedText }] : [],
+            edits: snakeJson(result.edits),
             write: { mode: request.mode, target: request.target, written },
             governance: result.governance === null ? null : {
                 ...snakeJson(result.governance),
@@ -3055,9 +3289,11 @@ async function runDocumentMigration(args) {
         : args.find((value) => value.startsWith("--target-grammar="))?.slice("--target-grammar=".length);
     if (target === "8")
         return runContract9DocumentMigration(args);
+    if (target === "9")
+        return runContract10DocumentMigration(args);
     const parsed = parseCommandOptions("document.migrate", args);
     if (parsed.positionals.length !== 1 || parsed.values.get("target-grammar") !== "7")
-        throw new UsageError("document migrate requires <file> --target-grammar 7 or 8");
+        throw new UsageError("document migrate requires <file> --target-grammar 7, 8, or 9");
     const sourceOperand = parsed.positionals[0];
     if (sourceOperand === "-")
         throw new UsageError("document migrate requires a repository file");
@@ -3467,6 +3703,420 @@ async function runCalendarMutation(action, args) {
     }
     return result.ok ? 0 : 1;
 }
+function unknownRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+async function residualDescriptionOption(value) {
+    const separator = value.indexOf("=");
+    if (separator <= 0) {
+        throw new UsageError("--add-residual-description requires WORK_ID=<JSON string> or WORK_ID=@<UTF-8 path>");
+    }
+    const workId = value.slice(0, separator);
+    const source = value.slice(separator + 1);
+    let text;
+    if (source.startsWith("@")) {
+        const bytes = await readBytes(source.slice(1));
+        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    else {
+        try {
+            text = JSON.parse(source);
+        }
+        catch {
+            throw new UsageError("--add-residual-description inline value must be one JSON string");
+        }
+    }
+    if (typeof text !== "string" || text.length === 0) {
+        throw new UsageError("--add-residual-description value must be a non-empty string");
+    }
+    return Object.freeze({ work_id: workId, text });
+}
+async function planningRequestInput(parsed, sourceOperand) {
+    const requestSource = parsed.values.get("request") ?? parsed.values.get("intent-request");
+    if (requestSource === undefined) {
+        throw new UsageError("exactly one of --request or --intent-request is required");
+    }
+    if (sourceOperand === "-" && requestSource === "-") {
+        throw new UsageError("document and planning request cannot both use stdin");
+    }
+    const input = await readMutationRequest(requestSource);
+    const additions = await Promise.all((parsed.repeatedValues.get("add-residual-description") ?? [])
+        .map(residualDescriptionOption));
+    if (additions.length === 0)
+        return input;
+    const request = unknownRecord(input);
+    if (request === null) {
+        throw new UsageError("planning request must be one JSON object");
+    }
+    const existing = request["add_residual_description"];
+    if (!Array.isArray(existing)) {
+        throw new UsageError("planning reshape request add_residual_description must be an array");
+    }
+    return Object.freeze({
+        ...request,
+        add_residual_description: Object.freeze([...existing, ...additions]),
+    });
+}
+function planningDiagnosticsJson(diagnostics) {
+    return diagnostics.map((diagnostic) => jsonDiagnostic(diagnostic));
+}
+function planningWireJson(value) {
+    const projected = snakeJson(value);
+    function convert(candidate) {
+        if (Array.isArray(candidate))
+            return candidate.map(convert);
+        const record = unknownRecord(candidate);
+        if (record === null)
+            return candidate;
+        const start = unknownRecord(record["start"]);
+        const end = unknownRecord(record["end"]);
+        const sourcePosition = (position) => position !== null &&
+            typeof position["offset"] === "number" &&
+            typeof position["line"] === "number" &&
+            typeof position["column"] === "number";
+        if (sourcePosition(start) && sourcePosition(end)) {
+            const oneBased = (position) => ({
+                offset: position["offset"],
+                line: position["line"] + 1,
+                column: position["column"] + 1,
+            });
+            return { start: oneBased(start), end: oneBased(end) };
+        }
+        return Object.fromEntries(Object.entries(record).map(([key, child]) => [key, convert(child)]));
+    }
+    return convert(projected);
+}
+function planningResultJson(operation, source, result, write = null) {
+    const projected = planningWireJson(result);
+    const diagnostics = result["diagnostics"];
+    return {
+        ...projected,
+        ...(Array.isArray(diagnostics)
+            ? { diagnostics: planningDiagnosticsJson(diagnostics) }
+            : {}),
+        cli_contract_version: 10,
+        tool_version: TOOL_VERSION,
+        operation,
+        source,
+        ...(write === null ? {} : { write: snakeJson(write) }),
+    };
+}
+function emitPlanningResult(format, operation, sourceOperand, result) {
+    if (format === "json") {
+        writeJson(planningResultJson(operation, sourceOperand === "-" ? "<stdin>" : sourceOperand, result));
+    }
+    else if (operation === "work.observe" || operation === "window.observe") {
+        const historical = "historyCapability" in result;
+        process.stdout.write(historical
+            ? renderPlanningHistoricalObservationText(operation, result)
+            : renderPlanningObservationText(operation, result));
+    }
+    else if (operation === "work.reshape.preflight") {
+        process.stdout.write(renderPlanningReshapePreflightText(result));
+    }
+}
+async function runPlanningRead(resource, action, args) {
+    const operation = `${resource}.${action}`;
+    const parsed = parseCommandOptions(operation, args);
+    const format = outputFormat(parsed.values.get("format"));
+    const sourceOperand = parsed.positionals[0];
+    const input = await readDocument(sourceOperand);
+    const result = inspectPlanningPool(input.text, {
+        operation,
+        ...(action === "show" ? { id: parsed.positionals[1] } : {}),
+    });
+    if (format === "json") {
+        writeJson(planningResultJson(operation, sourceOperand === "-" ? "<stdin>" : sourceOperand, result));
+    }
+    else if (result.ok) {
+        process.stdout.write(renderPlanningPoolReadText(result));
+    }
+    if (format !== "json") {
+        for (const diagnostic of result.diagnostics) {
+            process.stderr.write(`${diagnostic.code} ${diagnostic.severity}: ${diagnostic.message}\n`);
+        }
+    }
+    return result.ok ? 0 : 1;
+}
+function historicalSelectionAbsent(text, requestInput) {
+    const parsed = parsePlanningPoolSource(text, PLANNING_POOL_SOURCE_CAPABILITY);
+    const request = unknownRecord(requestInput);
+    const selection = unknownRecord(request?.["selection"]);
+    if (!parsed.ok || parsed.model === null || selection === null)
+        return false;
+    if (selection["kind"] === "work" && Array.isArray(selection["work_ids"])) {
+        const available = new Set(parsed.model.works.map(({ qualifiedId }) => qualifiedId));
+        return selection["work_ids"].some((id) => typeof id === "string" && !available.has(id));
+    }
+    if (selection["kind"] === "persisted" && typeof selection["window_id"] === "string") {
+        return !parsed.model.windows.some(({ qualifiedId }) => qualifiedId === selection["window_id"]);
+    }
+    return false;
+}
+async function runPlanningObservation(resource, args) {
+    const operation = `${resource}.observe`;
+    const parsed = parseCommandOptions(operation, args);
+    const format = outputFormat(parsed.values.get("format"));
+    const sourceOperand = parsed.positionals[0];
+    const input = await readDocument(sourceOperand);
+    const request = await planningRequestInput(parsed, sourceOperand);
+    let result = observeCurrentPlanningPool(input.text, request);
+    if (!result.ok && sourceOperand !== "-" && historicalSelectionAbsent(input.text, request)) {
+        const evidence = await historicalGitEvidenceHost.probe({
+            targetPath: sourceOperand,
+            expectedSourceDigest: input.digest,
+        });
+        result = observeHistoricalPlanningPool(input.text, request, evidence);
+    }
+    emitPlanningResult(format, operation, sourceOperand, result);
+    return result.ok ? 0 : 1;
+}
+async function runPlanningReshapePreflight(args) {
+    const operation = "work.reshape.preflight";
+    const parsed = parseCommandOptions(operation, args);
+    const format = outputFormat(parsed.values.get("format"));
+    const sourceOperand = parsed.positionals[0];
+    const input = await readDocument(sourceOperand);
+    const request = await planningRequestInput(parsed, sourceOperand);
+    const result = await withPlanningReshapeTokenRegistry((registry) => preflightPlanningPoolReshape(input.text, request, registry));
+    emitPlanningResult(format, operation, sourceOperand, result);
+    return result.ok ? 0 : 1;
+}
+function planningValidator(candidate) {
+    const checked = parsePlanningPoolSource(candidate, PLANNING_POOL_SOURCE_CAPABILITY);
+    return { ok: checked.ok && checked.grammarVersion === 9, diagnostics: [] };
+}
+async function persistPlanningCandidate(request, candidateText, originalDigest) {
+    if (request.mode === "preview") {
+        return Object.freeze({ mode: "preview", target: null, written: false });
+    }
+    if (request.mode === "in_place") {
+        const output = await replaceValidatedDocumentFile(request.target, candidateText, {
+            initialDigest: originalDigest,
+            ...(request.expectedDigest === undefined ? {} : { expectedDigest: request.expectedDigest }),
+        }, planningValidator);
+        return Object.freeze({ mode: "in_place", target: request.target, written: output.written });
+    }
+    const output = await createValidatedDocumentFile(request.target, candidateText, planningValidator);
+    return Object.freeze({ mode: "out", target: request.target, written: output.written });
+}
+async function preparePlanningHistory(sourceOperand, sourceDigest, sourceText, writeRequest, records, changed, writeAuthorized) {
+    const canonical = records.filter(({ ownerClass }) => ownerClass === "canonical");
+    const notApplicable = (cause) => Object.freeze({
+        guard: planningHistoryNotApplicable(canonical, cause),
+        baseline: null,
+    });
+    if (writeRequest.mode === "preview")
+        return notApplicable("preview");
+    if (writeRequest.mode === "out")
+        return notApplicable("separate_output");
+    if (!changed)
+        return notApplicable("no_change");
+    if (canonical.length === 0)
+        return notApplicable("no_canonical_records");
+    if (!writeAuthorized)
+        return notApplicable("authority_denied");
+    const baseline = await captureAdvanceHistoryBaseline({
+        targetPath: sourceOperand,
+        expectedSourceDigest: sourceDigest,
+    });
+    const prepared = Object.freeze({
+        guard: assessPlanningHistoryBaseline(sourceText, canonical, baseline),
+        baseline,
+    });
+    if (prepared.guard.status !== "passed" || writeRequest.mode !== "in_place") {
+        return prepared;
+    }
+    const recheck = await recheckAdvanceHistoryBaseline(baseline, sourceOperand);
+    if (recheck.ok)
+        return prepared;
+    return Object.freeze({
+        ...prepared,
+        guard: Object.freeze({
+            ...prepared.guard,
+            status: "blocked",
+            cause: recheck.cause ?? "baseline_race",
+        }),
+    });
+}
+function planningHistoryDiagnostic(guard) {
+    return Object.freeze({
+        code: "PTPOOL-113",
+        severity: "error",
+        message: "Canonical planning history proof is blocked",
+        helpTopic: "editing",
+        data: Object.freeze({
+            cause: guard.cause,
+            entity_ids: guard.overlappingEntityIds.length > 0
+                ? guard.overlappingEntityIds
+                : guard.destructiveEntityIds,
+        }),
+    });
+}
+async function runPlanningReshapeApply(args) {
+    const operation = "work.reshape.apply";
+    const parsed = parseCommandOptions(operation, args);
+    const format = outputFormat(parsed.values.get("format"));
+    const sourceOperand = parsed.positionals[0];
+    const input = await readDocument(sourceOperand);
+    const requestInput = await planningRequestInput(parsed, sourceOperand);
+    const preflightHash = requiredOption(parsed, "preflight-hash");
+    const preflightToken = requiredOption(parsed, "preflight-token");
+    const writeRequest = editingWriteRequest(parsed, sourceOperand);
+    const output = await withPlanningReshapeTokenRegistry(async (registry) => {
+        const recovered = recoverPlanningPoolReshapeCommit(preflightToken, input.digest, registry);
+        if (recovered.ok && recovered.completed) {
+            const snapshot = registry.snapshots().find(({ tokenDigest }) => tokenDigest === sha256DigestUtf8(preflightToken));
+            if (snapshot === undefined) {
+                throw new Error("completed planning reshape recovery lost its token binding");
+            }
+            return Object.freeze({
+                result: Object.freeze({
+                    schemaVersion: "Perttool.PlanningMutationResult.v1",
+                    reshapeCapability: "perttool.planning-reshape-core@1",
+                    ok: true,
+                    documentId: parsePlanningPoolSource(input.text, PLANNING_POOL_SOURCE_CAPABILITY).documentId,
+                    sourceDigest: snapshot.binding.sourceDigest,
+                    normalizedRequest: null,
+                    preflightHash: snapshot.binding.preflightHash,
+                    candidateDigest: snapshot.binding.candidateDigest,
+                    candidateText: input.text,
+                    changed: false,
+                    edits: Object.freeze([]),
+                    diagnostics: Object.freeze([]),
+                    diagnosticsTruncated: false,
+                    transfers: Object.freeze([]),
+                    destructiveRecords: Object.freeze([]),
+                    governance: null,
+                    assuranceImpact: null,
+                    historyGuard: planningHistoryNotApplicable([], "no_change"),
+                    tokenRecovery: recovered,
+                }),
+                write: Object.freeze({
+                    mode: writeRequest.mode,
+                    target: writeRequest.target,
+                    written: false,
+                }),
+            });
+        }
+        const prepared = preparePlanningPoolReshapeApply(input.text, requestInput, preflightHash, preflightToken, registry, { governance: governanceRequest(parsed, writeRequest) });
+        const warningFailure = parsed.flags.has("warnings-as-errors") &&
+            prepared.diagnostics.some(({ severity }) => severity === "warning");
+        const history = await preparePlanningHistory(sourceOperand, input.digest, input.text, writeRequest, prepared.destructiveRecords, prepared.changed, prepared.ok && !warningFailure && (prepared.governance?.writeAuthorized ?? false));
+        const historyBlocked = history.guard.status === "blocked";
+        const effectiveDiagnostics = historyBlocked
+            ? Object.freeze([...prepared.diagnostics, planningHistoryDiagnostic(history.guard)])
+            : prepared.diagnostics;
+        let write = Object.freeze({
+            mode: writeRequest.mode,
+            target: writeRequest.target,
+            written: false,
+        });
+        if (prepared.ok && !warningFailure && !historyBlocked && writeRequest.mode !== "preview") {
+            if (prepared.candidateText === null || prepared.candidateDigest === null) {
+                throw new Error("successful planning reshape has no candidate");
+            }
+            assertExpectedDigest(writeRequest, input.digest);
+            const begun = beginPlanningPoolReshapeCommit(prepared, preflightToken, registry);
+            if (!begun.ok)
+                throw new Error(`planning reshape token cannot enter commit: ${begun.state}`);
+            if (prepared.changed) {
+                write = await persistPlanningCandidate(writeRequest, prepared.candidateText, input.digest);
+            }
+            const settled = settlePlanningPoolReshapeCommit(preflightToken, prepared.candidateDigest, registry);
+            if (!settled.ok || !settled.completed) {
+                throw new Error(`planning reshape token cannot complete: ${settled.state}`);
+            }
+        }
+        return Object.freeze({
+            result: Object.freeze({
+                ...prepared,
+                ok: prepared.ok && !warningFailure && !historyBlocked,
+                diagnostics: effectiveDiagnostics,
+                historyGuard: history.guard,
+                tokenRecovery: recovered,
+            }),
+            write,
+        });
+    });
+    if (format === "json") {
+        writeJson(planningResultJson(operation, sourceOperand === "-" ? "<stdin>" : sourceOperand, output.result, output.write));
+    }
+    else if (output.result.ok && output.result.candidateText !== null) {
+        process.stdout.write(parsed.flags.has("diff")
+            ? createUnifiedDiff(input.text, output.result.candidateText, { originalLabel: sourceOperand, updatedLabel: "candidate" })
+            : output.result.candidateText);
+    }
+    return output.result.ok ? 0 : 1;
+}
+async function runPlanningWindowMutation(action, args) {
+    const operation = `window.${action}`;
+    const parsed = parseCommandOptions(operation, args);
+    const format = outputFormat(parsed.values.get("format"));
+    const sourceOperand = parsed.positionals[0];
+    const input = await readDocument(sourceOperand);
+    const requestInput = await planningRequestInput(parsed, sourceOperand);
+    let effectiveRequest = requestInput;
+    if (isPlanningIntentRequest(requestInput)) {
+        const parsedSource = parsePlanningPoolSource(input.text, PLANNING_POOL_SOURCE_CAPABILITY);
+        if (!parsedSource.ok || parsedSource.model === null) {
+            throw new UsageError("Planning intent request requires a valid Grammar 9 document");
+        }
+        const compiled = compilePlanningIntentRequest(requestInput, parsedSource.model);
+        if (!compiled.ok || compiled.windowRequest === null) {
+            throw new UsageError(compiled.reshapeRequest === null
+                ? compiled.diagnostics.map(({ message }) => message).join("; ") || "Planning intent request is invalid"
+                : "Work intent request must use work reshape preflight/apply");
+        }
+        effectiveRequest = compiled.windowRequest;
+    }
+    const request = unknownRecord(effectiveRequest);
+    if (request === null || request["window_id"] !== parsed.positionals[1] &&
+        request["window_id"] !== `${/^project ([A-Za-z][A-Za-z0-9_-]*):$/mu.exec(input.text)?.[1] ?? ""}::${parsed.positionals[1]}`) {
+        throw new UsageError("Window operand and request window_id must identify the same Window");
+    }
+    const writeRequest = editingWriteRequest(parsed, sourceOperand);
+    const result = planPlanningWindowMutation(input.text, effectiveRequest, {
+        governance: governanceRequest(parsed, writeRequest),
+    });
+    const history = await preparePlanningHistory(sourceOperand, input.digest, input.text, writeRequest, result.destructiveRecords, result.changed, result.ok && (result.governance?.writeAuthorized ?? false));
+    const historyBlocked = history.guard.status === "blocked";
+    let write = Object.freeze({
+        mode: writeRequest.mode,
+        target: writeRequest.target,
+        written: false,
+    });
+    if (result.ok && !historyBlocked && result.candidateText !== null && writeRequest.mode !== "preview") {
+        assertExpectedDigest(writeRequest, input.digest);
+        if (result.changed) {
+            write = await persistPlanningCandidate(writeRequest, result.candidateText, input.digest);
+        }
+    }
+    const projected = Object.freeze({
+        ...result,
+        ok: result.ok && !historyBlocked,
+        originalDigest: input.digest,
+        updatedDigest: result.candidateDigest,
+        updatedText: result.candidateText,
+        diff: result.candidateText === null ? null : createUnifiedDiff(input.text, result.candidateText, {
+            originalLabel: sourceOperand,
+            updatedLabel: "candidate",
+        }),
+        diagnostics: historyBlocked
+            ? Object.freeze([...result.diagnostics, planningHistoryDiagnostic(history.guard)])
+            : result.diagnostics,
+        historyGuard: history.guard,
+    });
+    if (format === "json") {
+        writeJson(planningResultJson(operation, sourceOperand === "-" ? "<stdin>" : sourceOperand, projected, write));
+    }
+    else if (result.ok && result.candidateText !== null) {
+        process.stdout.write(parsed.flags.has("diff") ? projected.diff ?? "" : result.candidateText);
+    }
+    return projected.ok ? 0 : 1;
+}
 async function dispatchCommand(descriptor, args) {
     switch (descriptor.operation) {
         case "help":
@@ -3509,6 +4159,30 @@ async function dispatchCommand(descriptor, args) {
         case "calendar.set":
         case "calendar.remove":
             return runCalendarMutation(descriptor.path[1], args);
+        case "work.list":
+        case "work.show":
+            return runPlanningRead("work", descriptor.path[1], args);
+        case "work.observe":
+            return runPlanningObservation("work", args);
+        case "work.reshape.preflight":
+            return runPlanningReshapePreflight(args);
+        case "work.reshape.apply":
+            return runPlanningReshapeApply(args);
+        case "event.list":
+        case "event.show":
+            return runPlanningRead("event", descriptor.path[1], args);
+        case "activity.list":
+        case "activity.show":
+            return runPlanningRead("activity", descriptor.path[1], args);
+        case "window.list":
+        case "window.show":
+            return runPlanningRead("window", descriptor.path[1], args);
+        case "window.observe":
+            return runPlanningObservation("window", args);
+        case "window.add":
+        case "window.set":
+        case "window.close":
+            return runPlanningWindowMutation(descriptor.path[1], args);
         case "task.start":
             return runLifecycleMutation("start", args);
         case "task.suspend":
@@ -3541,7 +4215,7 @@ async function dispatchCommand(descriptor, args) {
         const [resource, action] = descriptor.path;
         return runMutation(resource, action, args);
     }
-    throw new Error(`no Contract 8 handler for ${descriptor.operation}`);
+    throw new Error(`no Contract 10 handler for ${descriptor.operation}`);
 }
 function emitCommandUsage(error, json) {
     if (json) {