frontend-harness 0.7.9 → 0.8.0

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { buildContext } from "../runtime/context.js";
 import { checkComponentGraph } from "../runtime/graph.js";
-import { addKnowledge, checkKnowledge, checkKnowledgeCoverage, createModuleKnowledge, indexKnowledge, listKnowledge, promoteKnowledge, searchKnowledge, showKnowledge, updateKnowledge } from "../runtime/knowledge.js";
+import { addKnowledge, checkKnowledge, checkKnowledgeCoverage, createModuleKnowledge, draftKnowledgeFromIngest, indexKnowledge, listKnowledge, promoteKnowledge, searchKnowledge, showKnowledge, updateKnowledge } from "../runtime/knowledge.js";
 import { checkAgentPlanningProposal, createPlan } from "../runtime/plan.js";
 import { publicHelpLines } from "../runtime/command-taxonomy.js";
 import { cleanRuntimeArtifacts } from "../runtime/clean.js";
@@ -10,12 +10,15 @@ import { createRepairPacket } from "../runtime/repair-packet.js";
 import { isScaffoldPresetName, scaffoldProject } from "../runtime/scaffold.js";
 import { explainState } from "../runtime/state-explain.js";
 import { checkProtocol, initializeProtocol } from "../runtime/protocol-init.js";
-import { checkSkills, discoverSkills } from "../runtime/skills.js";
+import { checkSkills, listSkills } from "../runtime/skills.js";
 import { changedFilesFromGit, checkStateContract, getNextAction, loadState, recordChangedFiles } from "../runtime/state.js";
 import { checkExecutionUnits } from "../runtime/units.js";
+import { listIngestRecords, recordIngestSource, showIngestRecord } from "../runtime/ingest.js";
+import { buildCompactTaskContext } from "../runtime/task-context.js";
 import { assertDesignSourceReadyForProjectChanges, createEvidenceTemplate, recordEvidence } from "../runtime/evidence.js";
 import { runVerification } from "../runtime/verify.js";
 import { compareVisualArtifacts } from "../runtime/visual-compare.js";
+const MAX_HUMAN_VERIFICATION_RESULTS = 10;
 const COMMAND_HELP = {
     init: [
         "Usage:",
@@ -30,7 +33,18 @@ const COMMAND_HELP = {
     ],
     context: [
         "Usage:",
-        "  frontend-harness context --json"
+        "  frontend-harness context --json",
+        "  frontend-harness context task --json \"<task>\" [--prd <prd-file>] [--api-source <openapi-file-or-url>] [--ui-source <ui-artifact-or-design-url>] [--limit <count>]",
+        "",
+        "`context task` builds a compact task packet from workflow policy, knowledge cards, and ingest provenance."
+    ],
+    ingest: [
+        "Usage:",
+        "  frontend-harness ingest record --json --kind prd|openapi|ui-package --id <source-id> --source <file-or-url> --summary \"<summary>\" [--cards <ids>]",
+        "  frontend-harness ingest list --json [--kind prd|openapi|ui-package]",
+        "  frontend-harness ingest show --json --ref ingest://<kind>/<source-id>",
+        "",
+        "Records lightweight provenance for temporary PRD, OpenAPI, or UI package inputs."
     ],
     clean: [
         "Usage:",
@@ -43,10 +57,11 @@ const COMMAND_HELP = {
     ],
     plan: [
         "Usage:",
-        "  frontend-harness plan --json \"<task>\" [--prd <prd-file>] [--ui-source <ui-artifact-or-design-url>] [--agent-proposal <agent-proposal.json>]",
+        "  frontend-harness plan --json \"<task>\" [--prd <prd-file>] [--api-source <openapi-file-or-url>] [--ui-source <ui-artifact-or-design-url>] [--agent-proposal <agent-proposal.json>]",
         "",
         "Flags:",
         "  --prd <file>                    Project-relative PRD or requirement source.",
+        "  --api-source <path-or-url>       OpenAPI/Swagger source file or URL.",
         "  --ui-source <path-or-url>        UI source artifact or supported design URL.",
         "  --agent-proposal <json-file>     Bounded planning proposal envelope.",
         "  --json                          Print machine-readable output."
@@ -112,6 +127,7 @@ const COMMAND_HELP = {
     knowledge: [
         "Usage:",
         "  frontend-harness knowledge add --json --kind <kind> --subject \"<subject>\" <content-flag>",
+        "  frontend-harness knowledge draft --json --ref ingest://<kind>/<source-id>",
         "  frontend-harness knowledge module --json --id <id> --title \"<title>\" --summary \"<summary>\" --body \"<body>\"",
         "  frontend-harness knowledge update --json --id <knowledge-id> [metadata flags]",
         "  frontend-harness knowledge index --json",
@@ -147,6 +163,13 @@ const COMMAND_HELP = {
         "  --status active|deprecated",
         "  --stability stable|evolving"
     ],
+    "knowledge draft": [
+        "Usage:",
+        "  frontend-harness knowledge draft --json --ref ingest://<kind>/<source-id>",
+        "",
+        "Builds a knowledge add scaffold from recorded ingest provenance.",
+        "Review the summary and replace placeholder content, coverage, verification, scope, and tags before adding durable knowledge."
+    ],
     "knowledge module": [
         "Usage:",
         "  frontend-harness knowledge module --json --id <kebab-id> --title \"<title>\" --summary \"<summary>\" --body \"<body>\" [traceability flags]",
@@ -254,7 +277,10 @@ async function main() {
                 }
                 return;
             case "context":
-                output(buildContext(projectRoot), parsed.json);
+                handleContext(projectRoot, parsed);
+                return;
+            case "ingest":
+                handleIngest(projectRoot, parsed);
                 return;
             case "clean":
                 output(cleanRuntimeArtifacts(projectRoot, {
@@ -266,6 +292,7 @@ async function main() {
                 output(createPlan(projectRoot, {
                     taskText: parsed.taskText,
                     ...optionalString("prd", parsed.flags["prd"]),
+                    ...optionalString("apiSource", parsed.flags["api-source"]),
                     ...optionalString("uiSource", parsed.flags["ui-source"]),
                     ...optionalString("agentProposal", parsed.flags["agent-proposal"])
                 }), parsed.json);
@@ -348,11 +375,27 @@ async function main() {
             console.log(JSON.stringify({ error: message }, null, 2));
         }
         else {
-            console.error(message);
+            console.error(humanField(message));
         }
         process.exitCode = 1;
     }
 }
+function handleContext(projectRoot, parsed) {
+    if (parsed.subcommand === "task") {
+        output(buildCompactTaskContext(projectRoot, {
+            taskText: parsed.positionals.slice(2).join(" "),
+            ...optionalString("prd", parsed.flags["prd"]),
+            ...optionalString("apiSource", parsed.flags["api-source"]),
+            ...optionalString("uiSource", parsed.flags["ui-source"]),
+            ...optionalNumber("limit", parsed.flags["limit"])
+        }), parsed.json);
+        return;
+    }
+    if (parsed.subcommand) {
+        throw new Error("context requires subcommand: task");
+    }
+    output(buildContext(projectRoot), parsed.json);
+}
 function handleEvidence(projectRoot, parsed) {
     if (parsed.subcommand === "template") {
         output(createEvidenceTemplate(projectRoot), parsed.json);
@@ -364,6 +407,27 @@ function handleEvidence(projectRoot, parsed) {
     }
     throw new Error("evidence requires subcommand: template or record");
 }
+function handleIngest(projectRoot, parsed) {
+    if (parsed.subcommand === "record") {
+        output(recordIngestSource(projectRoot, {
+            ...optionalString("kind", parsed.flags["kind"]),
+            ...optionalString("id", parsed.flags["id"]),
+            ...optionalString("source", parsed.flags["source"]),
+            ...optionalString("summary", parsed.flags["summary"]),
+            ...optionalString("cards", parsed.flags["cards"])
+        }), parsed.json);
+        return;
+    }
+    if (parsed.subcommand === "list") {
+        output(listIngestRecords(projectRoot, stringFlag(parsed.flags["kind"])), parsed.json);
+        return;
+    }
+    if (parsed.subcommand === "show") {
+        output(showIngestRecord(projectRoot, stringFlag(parsed.flags["ref"])), parsed.json);
+        return;
+    }
+    throw new Error("ingest requires subcommand: record, list, or show");
+}
 function handleVisual(projectRoot, parsed) {
     if (parsed.subcommand === "compare") {
         const result = compareVisualArtifacts(projectRoot, {
@@ -371,7 +435,7 @@ function handleVisual(projectRoot, parsed) {
             ...optionalString("actual", parsed.flags["actual"]),
             ...optionalString("diff", parsed.flags["diff"]),
             ...optionalString("report", parsed.flags["report"]),
-            ...optionalNumber("threshold", parsed.flags["threshold"])
+            ...optionalFiniteNumber("threshold", parsed.flags["threshold"])
         });
         output(result, parsed.json);
         process.exitCode = result.status === "failed" ? 1 : 0;
@@ -424,7 +488,7 @@ function handleRepair(projectRoot, parsed) {
 }
 function handleSkills(projectRoot, parsed) {
     if (parsed.subcommand === "list") {
-        output({ skills: discoverSkills(projectRoot) }, parsed.json);
+        output(listSkills(projectRoot), parsed.json);
         return;
     }
     if (parsed.subcommand === "check") {
@@ -458,6 +522,12 @@ function handleKnowledge(projectRoot, parsed) {
         }), parsed.json);
         return;
     }
+    if (parsed.subcommand === "draft") {
+        output(draftKnowledgeFromIngest(projectRoot, {
+            ...optionalString("ref", parsed.flags["ref"])
+        }), parsed.json);
+        return;
+    }
     if (parsed.subcommand === "promote") {
         output(promoteKnowledge(projectRoot, {
             ...optionalString("title", parsed.flags["title"]),
@@ -546,7 +616,7 @@ function handleKnowledge(projectRoot, parsed) {
         process.exitCode = result.status === "failed" ? 1 : 0;
         return;
     }
-    throw new Error("knowledge requires subcommand: add, promote, module, update, index, coverage, list, search, show, or check");
+    throw new Error("knowledge requires subcommand: add, draft, promote, module, update, index, coverage, list, search, show, or check");
 }
 function requireSubcommand(parsed, subcommand, message) {
     if (parsed.subcommand !== subcommand) {
@@ -563,6 +633,12 @@ function parseArgs(args) {
         }
         if (arg.startsWith("--")) {
             const key = arg.slice(2);
+            if (key.includes("=")) {
+                throw new Error(`Unsupported flag assignment syntax: --${key}. Use --${key.split("=")[0]} <value>.`);
+            }
+            if (Object.prototype.hasOwnProperty.call(flags, key)) {
+                throw new Error(`Duplicate flag: --${key}`);
+            }
             if (["json", "from-git", "dry-run", "check", "help", "force", "include-deprecated"].includes(key)) {
                 flags[key] = true;
             }
@@ -611,12 +687,13 @@ function allowedFlags(parsed) {
     const global = ["json", "help"];
     const commandFlags = {
         init: ["dry-run", "check"],
-        context: [],
+        context: parsed.subcommand === "task" ? ["limit", "prd", "api-source", "ui-source"] : [],
         clean: ["dry-run", "keep-logs"],
-        plan: ["prd", "ui-source", "agent-proposal"],
+        plan: ["prd", "api-source", "ui-source", "agent-proposal"],
         verify: ["typecheck", "test", "build"],
         visual: parsed.subcommand === "compare" ? ["design", "actual", "diff", "report", "threshold"] : [],
         evidence: parsed.subcommand === "record" ? ["file"] : [],
+        ingest: ingestFlags(parsed.subcommand),
         state: parsed.subcommand === "record-change" ? ["from-git"] : [],
         knowledge: knowledgeFlags(parsed.subcommand),
         protocol: [],
@@ -642,6 +719,8 @@ function knowledgeFlags(subcommand) {
     switch (subcommand) {
         case "add":
             return ["id", "kind", "subject", "summary", ...atomicContent, ...traceability, ...lifecycle];
+        case "draft":
+            return ["ref"];
         case "promote":
             return ["title", "body", "type", ...lifecycle];
         case "module":
@@ -663,6 +742,20 @@ function knowledgeFlags(subcommand) {
             return [];
     }
 }
+function ingestFlags(subcommand) {
+    switch (subcommand) {
+        case "record":
+            return ["kind", "id", "source", "summary", "cards"];
+        case "list":
+            return ["kind"];
+        case "show":
+            return ["ref"];
+        case undefined:
+            return [];
+        default:
+            return [];
+    }
+}
 function output(value, json) {
     if (json) {
         console.log(JSON.stringify(value, null, 2));
@@ -670,63 +763,199 @@ function output(value, json) {
     }
     console.log(renderHuman(value));
 }
+const MAX_HUMAN_FIELD_CHARS = 240;
+const MAX_HUMAN_PROMPT_CHARS = 4_000;
+function humanField(value) {
+    const normalized = normalizeHumanField(value);
+    return normalized.length > MAX_HUMAN_FIELD_CHARS
+        ? `${normalized.slice(0, MAX_HUMAN_FIELD_CHARS - 3)}...`
+        : normalized;
+}
+function humanFieldTruncated(value) {
+    return normalizeHumanField(value).length > MAX_HUMAN_FIELD_CHARS;
+}
+function normalizeHumanField(value) {
+    return String(value ?? "unknown").replace(/\s+/g, " ").trim();
+}
+function humanBlock(value, maxChars) {
+    const text = String(value ?? "").trimEnd();
+    return text.length > maxChars ? `${text.slice(0, maxChars - 3)}...` : text;
+}
+function humanBlockTruncated(value, maxChars) {
+    return String(value ?? "").trimEnd().length > maxChars;
+}
 function renderHuman(value) {
     if (!isRecord(value)) {
         return String(value);
     }
     if ("projectRoot" in value && "detectedStack" in value) {
         const context = value;
+        const knowledgeLimit = context.projectStatus?.knowledgeLimits;
+        const skillLimit = context.projectStatus?.skillLimits;
+        const planningDecision = context.projectStatus?.planningDecision;
+        const proposalLimits = planningDecision?.limits;
+        const evidence = planningDecision?.planningEvidence;
         return [
-            `projectRoot: ${String(context.projectRoot ?? "unknown")}`,
-            `packageManager: ${String(context.detectedStack?.packageManager ?? "unknown")}`,
-            `framework: ${String(context.detectedStack?.framework ?? "unknown")}`,
-            `language: ${String(context.detectedStack?.language ?? "unknown")}`
+            `projectRoot: ${humanField(context.projectRoot ?? "unknown")}`,
+            `packageManager: ${humanField(context.detectedStack?.packageManager ?? "unknown")}`,
+            `framework: ${humanField(context.detectedStack?.framework ?? "unknown")}`,
+            `language: ${humanField(context.detectedStack?.language ?? "unknown")}`,
+            `knowledge: ${Array.isArray(context.projectStatus?.knowledge) ? context.projectStatus.knowledge.length : 0}/${String(knowledgeLimit?.total ?? "unknown")}`,
+            `omittedKnowledge: ${String(knowledgeLimit?.omitted ?? 0)}`,
+            `skills: ${Array.isArray(context.projectStatus?.skills) ? context.projectStatus.skills.length : 0}/${String(skillLimit?.total ?? "unknown")}`,
+            `omittedSkills: ${String(skillLimit?.omitted ?? 0)}`,
+            ...(planningDecision ? [
+                `planningDecision: ${humanField(planningDecision.artifactPath ?? "unknown")}`,
+                `planningConstraintHints: ${String(proposalLimits?.constraintHints?.selected ?? (Array.isArray(planningDecision.constraintHints) ? planningDecision.constraintHints.length : 0))}/${String(proposalLimits?.constraintHints?.max ?? "unknown")}`,
+                `planningComponentHints: ${String(proposalLimits?.componentHints?.selected ?? (Array.isArray(planningDecision.componentHints) ? planningDecision.componentHints.length : 0))}/${String(proposalLimits?.componentHints?.max ?? "unknown")}`,
+                `planningWorkflowCandidates: ${String(proposalLimits?.workflowCandidates?.selected ?? (Array.isArray(evidence?.workflowCandidates) ? evidence.workflowCandidates.length : 0))}/${String(proposalLimits?.workflowCandidates?.max ?? "unknown")}`,
+                `planningTargetCandidates: ${String(proposalLimits?.targetCandidates?.selected ?? (Array.isArray(evidence?.targetCandidates) ? evidence.targetCandidates.length : 0))}/${String(proposalLimits?.targetCandidates?.max ?? "unknown")}`,
+                `planningVerificationCandidates: ${String(proposalLimits?.verificationCandidates?.selected ?? (Array.isArray(evidence?.verificationCandidates) ? evidence.verificationCandidates.length : 0))}/${String(proposalLimits?.verificationCandidates?.max ?? "unknown")}`,
+                `planningAmbiguities: ${String(proposalLimits?.ambiguities?.selected ?? (Array.isArray(evidence?.ambiguities) ? evidence.ambiguities.length : 0))}/${String(proposalLimits?.ambiguities?.max ?? "unknown")}`
+            ] : [])
         ].join("\n");
     }
     if ("task" in value && "units" in value && Array.isArray(value["units"])) {
         const plan = value;
+        const guidanceLimits = plan.limits?.guidance;
+        return [
+            `intent: ${humanField(plan.task?.intent)}`,
+            `scope: ${humanField(plan.task?.scope)}`,
+            `components: ${Array.isArray(plan.components) ? plan.components.length : 0}`,
+            `units: ${plan.units.length}`,
+            `guidanceComponents: ${String(guidanceLimits?.components?.selected ?? "unknown")}/${String(guidanceLimits?.components?.total ?? "unknown")}`,
+            `omittedGuidanceComponents: ${String(guidanceLimits?.components?.omitted ?? 0)}`,
+            `guidanceUnits: ${String(guidanceLimits?.units?.selected ?? "unknown")}/${String(guidanceLimits?.units?.total ?? "unknown")}`,
+            `omittedGuidanceUnits: ${String(guidanceLimits?.units?.omitted ?? 0)}`,
+            `guidancePath: ${humanField(plan.guidancePath ?? "unknown")}`,
+            `componentGraphPath: ${humanField(plan.componentGraphPath ?? "unknown")}`,
+            `statePath: ${humanField(plan.statePath ?? "unknown")}`
+        ].join("\n");
+    }
+    if ("task" in value && "workflow" in value && "prompt" in value) {
+        const taskContext = value;
+        const sourceHintCount = [
+            taskContext.sourceHints?.endpoints,
+            taskContext.sourceHints?.prdCoverage,
+            taskContext.sourceHints?.uiArtifacts,
+            taskContext.sourceHints?.apiImplementations
+        ].reduce((total, group) => total + (Array.isArray(group) ? group.length : 0), 0);
+        const prompt = String(taskContext.prompt ?? "");
         return [
-            `intent: ${String(plan.task?.intent ?? "unknown")}`,
-            `scope: ${String(plan.task?.scope ?? "unknown")}`,
-            `units: ${plan.units.length}`
+            `task: ${humanField(taskContext.task)}`,
+            `workflow: ${humanField(taskContext.workflow?.kind)}`,
+            `knowledge: ${Array.isArray(taskContext.selectedKnowledge) ? taskContext.selectedKnowledge.length : 0}`,
+            `ingestSources: ${Array.isArray(taskContext.selectedIngestSources) ? taskContext.selectedIngestSources.length : 0}`,
+            `projectFiles: ${Array.isArray(taskContext.selectedProjectFiles) ? taskContext.selectedProjectFiles.length : 0}`,
+            `sourceHints: ${sourceHintCount}`,
+            `omittedKnowledge: ${String(taskContext.limits?.omittedSelectedKnowledge ?? 0)}`,
+            `omittedKnowledgeSourcePaths: ${String(taskContext.limits?.omittedSelectedKnowledgeSourcePaths ?? 0)}`,
+            `omittedKnowledgeCoverage: ${String(taskContext.limits?.omittedSelectedKnowledgeCoverage ?? 0)}`,
+            `omittedKnowledgeVerification: ${String(taskContext.limits?.omittedSelectedKnowledgeVerification ?? 0)}`,
+            `omittedIngestSources: ${String(taskContext.limits?.omittedSelectedIngestSources ?? 0)}`,
+            `omittedIngestProducedKnowledgeCardIds: ${String(taskContext.limits?.omittedSelectedIngestProducedKnowledgeCardIds ?? 0)}`,
+            `omittedProjectFiles: ${String(taskContext.limits?.omittedSelectedProjectFiles ?? 0)}`,
+            `omittedSourceHints: ${String(taskContext.limits?.omittedSourceHints ?? 0)}`,
+            `omittedPrdCoverageHintCoverage: ${String(taskContext.limits?.omittedPrdCoverageHintCoverage ?? 0)}`,
+            `omittedPrdCoverageHintAnchors: ${String(taskContext.limits?.omittedPrdCoverageHintAnchors ?? 0)}`,
+            `omittedPrdCoverageHintSourcePaths: ${String(taskContext.limits?.omittedPrdCoverageHintSourcePaths ?? 0)}`,
+            `projectFilesScanned: ${String(taskContext.limits?.totalScannedProjectFiles ?? 0)}/${String(taskContext.limits?.scannedProjectFiles ?? "unknown")}`,
+            `projectFileScanLimitReached: ${String(taskContext.limits?.projectFileScanLimitReached ?? false)}`,
+            `skippedPrdSourceHintSources: ${String(taskContext.limits?.skippedPrdSourceHintSources ?? 0)}`,
+            `skippedApiSourceHintSources: ${String(taskContext.limits?.skippedApiSourceHintSources ?? 0)}`,
+            `artifactPath: ${humanField(taskContext.artifactPath ?? "unknown")}`,
+            `promptChars: ${String(prompt.length)}`,
+            `promptTruncated: ${String(humanBlockTruncated(prompt, MAX_HUMAN_PROMPT_CHARS))}`,
+            "",
+            humanBlock(prompt, MAX_HUMAN_PROMPT_CHARS)
         ].join("\n");
     }
     if ("results" in value && Array.isArray(value["results"])) {
         const verification = value;
+        const selectedResults = verification.results.slice(0, MAX_HUMAN_VERIFICATION_RESULTS);
+        const omittedResults = Math.max(0, verification.results.length - selectedResults.length);
         return [
-            `status: ${String(verification.status ?? "unknown")}`,
+            `status: ${humanField(verification.status ?? "unknown")}`,
             `results: ${verification.results.length}`,
-            ...verification.results.map((item) => `- ${String(item.name ?? "verification")}: ${String(item.status ?? "unknown")} (${String(item.exitCode ?? "n/a")})`)
+            `omittedResults: ${String(omittedResults)}`,
+            ...selectedResults.map((item) => `- ${humanField(item.name ?? "verification")}: ${humanField(item.status ?? "unknown")} (${String(item.exitCode ?? "n/a")})`)
+        ].join("\n");
+    }
+    if ("manifestPath" in value && "entries" in value && "instructions" in value) {
+        const template = value;
+        const entryLimits = template.limits?.entries;
+        return [
+            `status: ${humanField(template.status ?? "unknown")}`,
+            `manifestPath: ${humanField(template.manifestPath ?? "unknown")}`,
+            `entries: ${String(entryLimits?.selected ?? (Array.isArray(template.entries) ? template.entries.length : 0))}/${String(entryLimits?.total ?? (Array.isArray(template.entries) ? template.entries.length : 0))}`,
+            `omittedEntries: ${String(entryLimits?.omitted ?? 0)}`
+        ].join("\n");
+    }
+    if ("recordedEntries" in value && "entryCount" in value && "provenance" in value) {
+        const evidence = value;
+        const selectedSourceLimit = evidence.provenance?.limits?.selectedEvidenceSources ?? "unknown";
+        return [
+            `status: ${humanField(evidence.status ?? "unknown")}`,
+            `inputPath: ${humanField(evidence.inputPath ?? "unknown")}`,
+            `manifestPath: ${humanField(evidence.manifestPath ?? "unknown")}`,
+            `recordedEntries: ${Array.isArray(evidence.recordedEntries) ? evidence.recordedEntries.length : 0}`,
+            `entryCount: ${String(evidence.entryCount ?? 0)}`,
+            `planArtifactPath: ${humanField(evidence.provenance?.planArtifactPath ?? "none")}`,
+            `taskContextArtifactPath: ${humanField(evidence.provenance?.taskContextArtifactPath ?? "none")}`,
+            `selectedApiContractSources: ${Array.isArray(evidence.provenance?.selectedApiContractSources) ? evidence.provenance.selectedApiContractSources.length : 0}/${String(selectedSourceLimit)}`,
+            `omittedSelectedApiContractSources: ${String(evidence.provenance?.limits?.omittedSelectedApiContractSources ?? 0)}`,
+            `selectedUiSources: ${Array.isArray(evidence.provenance?.selectedUiSources) ? evidence.provenance.selectedUiSources.length : 0}/${String(selectedSourceLimit)}`,
+            `omittedSelectedUiSources: ${String(evidence.provenance?.limits?.omittedSelectedUiSources ?? 0)}`,
+            `selectedIngestSources: ${Array.isArray(evidence.provenance?.selectedIngestSources) ? evidence.provenance.selectedIngestSources.length : 0}/${String(selectedSourceLimit)}`,
+            `omittedSelectedIngestSources: ${String(evidence.provenance?.limits?.omittedSelectedIngestSources ?? 0)}`
         ].join("\n");
     }
     if ("comparisonTool" in value && "score" in value) {
         const comparison = value;
         return [
-            `status: ${String(comparison.status ?? "unknown")}`,
+            `status: ${humanField(comparison.status ?? "unknown")}`,
             `score: ${String(comparison.score ?? "unknown")}`,
             `threshold: ${String(comparison.threshold ?? "unknown")}`,
             `changedPixels: ${String(comparison.changedPixels ?? "unknown")}`,
             `changedRatio: ${String(comparison.changedRatio ?? "unknown")}`,
-            `diffPath: ${String(comparison.diffPath ?? "unknown")}`,
+            `diffPath: ${humanField(comparison.diffPath ?? "unknown")}`,
             ...(Array.isArray(comparison.limitations) && comparison.limitations.length
-                ? [`limitations: ${comparison.limitations.map((item) => String(item)).join(" ")}`]
+                ? [`limitations: ${comparison.limitations.map((item) => humanField(item)).join(" ")}`]
                 : [])
         ].join("\n");
     }
     if ("action" in value && "stateStatus" in value) {
         const next = value;
+        const changedFileLimit = next.limits?.changedFiles;
+        return [
+            `action: ${humanField(next.action ?? "unknown")}`,
+            `reason: ${humanField(next.reason ?? "unknown")}`,
+            `command: ${humanField(next.command ?? "none")}`,
+            `changedFiles: ${String(changedFileLimit?.selected ?? (Array.isArray(next.changedFiles) ? next.changedFiles.length : 0))}/${String(changedFileLimit?.total ?? (Array.isArray(next.changedFiles) ? next.changedFiles.length : 0))}`,
+            `omittedChangedFiles: ${String(changedFileLimit?.omitted ?? 0)}`
+        ].join("\n");
+    }
+    if ("nextAction" in value && "requiredArtifacts" in value && "recommendedCommands" in value) {
+        const explain = value;
+        const markdownLimits = explain.limits?.markdown;
         return [
-            `action: ${String(next.action ?? "unknown")}`,
-            `reason: ${String(next.reason ?? "unknown")}`,
-            `command: ${String(next.command ?? "none")}`
+            `action: ${humanField(explain.nextAction?.action ?? "unknown")}`,
+            `summary: ${humanField(explain.summary ?? "unknown")}`,
+            `rationale: ${String(markdownLimits?.rationale?.selected ?? "unknown")}/${String(markdownLimits?.rationale?.total ?? "unknown")}`,
+            `omittedRationale: ${String(markdownLimits?.rationale?.omitted ?? 0)}`,
+            `requiredArtifacts: ${String(markdownLimits?.requiredArtifacts?.selected ?? (Array.isArray(explain.requiredArtifacts) ? explain.requiredArtifacts.length : 0))}/${String(markdownLimits?.requiredArtifacts?.total ?? (Array.isArray(explain.requiredArtifacts) ? explain.requiredArtifacts.length : 0))}`,
+            `omittedRequiredArtifacts: ${String(markdownLimits?.requiredArtifacts?.omitted ?? 0)}`,
+            `recommendedCommands: ${String(markdownLimits?.recommendedCommands?.selected ?? (Array.isArray(explain.recommendedCommands) ? explain.recommendedCommands.length : 0))}/${String(markdownLimits?.recommendedCommands?.total ?? (Array.isArray(explain.recommendedCommands) ? explain.recommendedCommands.length : 0))}`,
+            `omittedRecommendedCommands: ${String(markdownLimits?.recommendedCommands?.omitted ?? 0)}`,
+            `stopCondition: ${humanField(explain.stopCondition ?? "unknown")}`
         ].join("\n");
     }
     if ("changedFiles" in value && "verification" in value) {
         const state = value;
         return [
-            `status: ${String(state.status ?? "unknown")}`,
+            `status: ${humanField(state.status ?? "unknown")}`,
             `changedFiles: ${Array.isArray(state.changedFiles) ? state.changedFiles.length : 0}`,
-            `verification: ${String(state.verification?.status ?? "unknown")}`,
+            `verification: ${humanField(state.verification?.status ?? "unknown")}`,
             `retryCount: ${String(state.retryCount ?? 0)}`
         ].join("\n");
     }
@@ -740,41 +969,80 @@ function renderHuman(value) {
     }
     if ("skills" in value && Array.isArray(value["skills"])) {
         const skills = value["skills"];
-        return [`skills: ${skills.length}`, ...skills.map((skill) => `- ${String(skill.name ?? "unknown")}: ${String(skill.title ?? "unknown")} (${String(skill.path ?? "unknown")})`)].join("\n");
+        const limits = value["limits"];
+        const selected = limits?.selected ?? skills.length;
+        const total = limits?.total ?? skills.length;
+        return [
+            `skills: ${String(selected)}/${String(total)}`,
+            `omittedSkills: ${String(limits?.omitted ?? 0)}`,
+            ...skills.map((skill) => `- ${humanField(skill.name)}: ${humanField(skill.title)} (${humanField(skill.path)})`)
+        ].join("\n");
     }
-    if ("cards" in value && Array.isArray(value["cards"])) {
-        const cards = value["cards"];
+    if ("records" in value && Array.isArray(value["records"])) {
+        const records = value["records"];
+        const limits = value["limits"];
+        const selected = limits?.selected ?? records.length;
+        const total = limits?.total ?? records.length;
         return [
-            `cards: ${cards.length}`,
-            ...cards.map((card) => {
-                const score = card.score === undefined ? "" : ` score=${String(card.score)}`;
-                return `- ${String(card.id ?? "unknown")}: ${String(card.title ?? "unknown")} (${String(card.path ?? "unknown")})${score}`;
-            })
+            `records: ${String(selected)}/${String(total)}`,
+            `omittedRecords: ${String(limits?.omitted ?? 0)}`,
+            ...records.map((record) => `- ${humanField(record.ingestRef)}: ${humanField(record.summary)} (${humanField(record.artifactPath)})`)
         ].join("\n");
     }
-    if ("card" in value && "body" in value) {
-        const shown = value;
+    if ("ingestRef" in value && "source" in value && "producedKnowledgeCardIds" in value) {
+        const record = value;
         return [
-            `id: ${String(shown.card?.id ?? "unknown")}`,
-            `title: ${String(shown.card?.title ?? "unknown")}`,
-            `path: ${String(shown.card?.path ?? "unknown")}`,
-            "",
-            String(shown.body ?? "")
+            `ingestRef: ${humanField(record.ingestRef)}`,
+            `kind: ${humanField(record.kind)}`,
+            `source: ${humanField(record.source?.value)}`,
+            `sha256: ${humanField(record.source?.sha256 ?? "none")}`,
+            `cards: ${Array.isArray(record.producedKnowledgeCardIds) ? record.producedKnowledgeCardIds.length : 0}`,
+            `artifactPath: ${humanField(record.artifactPath)}`
         ].join("\n");
     }
     if ("artifactPath" in value && "prdSourceCount" in value) {
         const index = value;
+        const cardLimits = index.limits?.cards;
         return [
-            `artifactPath: ${String(index.artifactPath ?? "unknown")}`,
+            `artifactPath: ${humanField(index.artifactPath ?? "unknown")}`,
             `cardCount: ${String(index.cardCount ?? 0)}`,
+            `cards: ${String(cardLimits?.selected ?? index.cardCount ?? 0)}/${String(cardLimits?.total ?? index.cardCount ?? 0)}`,
+            `omittedCards: ${String(cardLimits?.omitted ?? 0)}`,
             `prdSourceCount: ${String(index.prdSourceCount ?? 0)}`,
             `uncoveredPrdSourceCount: ${String(index.uncoveredPrdSourceCount ?? 0)}`
         ].join("\n");
     }
+    if ("cards" in value && Array.isArray(value["cards"])) {
+        const cards = value["cards"];
+        const limits = value["limits"];
+        const selected = limits?.selected ?? cards.length;
+        const total = limits?.total ?? cards.length;
+        return [
+            `cards: ${String(selected)}${limits ? `/${String(total)}` : ""}`,
+            ...(limits ? [`omittedCards: ${String(limits.omitted ?? 0)}`] : []),
+            ...cards.map((card) => {
+                const score = card.score === undefined ? "" : ` score=${String(card.score)}`;
+                return `- ${humanField(card.id)}: ${humanField(card.title)} (${humanField(card.path)})${score}`;
+            })
+        ].join("\n");
+    }
+    if ("card" in value && "body" in value) {
+        const shown = value;
+        const body = String(shown.body ?? "");
+        return [
+            `id: ${humanField(shown.card?.id)}`,
+            `title: ${humanField(shown.card?.title)}`,
+            `path: ${humanField(shown.card?.path)}`,
+            `bodyChars: ${String(body.length)}`,
+            `bodyTruncated: ${String(humanFieldTruncated(body))}`,
+            "",
+            humanField(body)
+        ].join("\n");
+    }
     if ("coveredPrdSourceCount" in value && "uncoveredPrdSources" in value) {
         const coverage = value;
         return [
-            `status: ${String(coverage.status ?? "unknown")}`,
+            `status: ${humanField(coverage.status ?? "unknown")}`,
             `prdSourceCount: ${String(coverage.prdSourceCount ?? 0)}`,
             `coveredPrdSourceCount: ${String(coverage.coveredPrdSourceCount ?? 0)}`,
             `uncoveredPrdSources: ${Array.isArray(coverage.uncoveredPrdSources) ? coverage.uncoveredPrdSources.length : 0}`,
@@ -783,7 +1051,19 @@ function renderHuman(value) {
     }
     if ("path" in value && "title" in value) {
         const knowledge = value;
-        return [`path: ${String(knowledge.path ?? "unknown")}`, `title: ${String(knowledge.title ?? "unknown")}`, `createdAt: ${String(knowledge.createdAt ?? "unknown")}`].join("\n");
+        return [`path: ${humanField(knowledge.path)}`, `title: ${humanField(knowledge.title)}`, `createdAt: ${humanField(knowledge.createdAt)}`].join("\n");
+    }
+    if ("ingestRef" in value && "recommendedAction" in value && "updateCandidates" in value) {
+        const draft = value;
+        const candidateLimits = draft.limits?.updateCandidates;
+        return [
+            `ingestRef: ${humanField(draft.ingestRef ?? "unknown")}`,
+            `recommendedAction: ${humanField(draft.recommendedAction ?? "unknown")}`,
+            `recommendedKind: ${humanField(draft.recommendedKind ?? "unknown")}`,
+            `recommendedType: ${humanField(draft.recommendedType ?? "unknown")}`,
+            `updateCandidates: ${String(candidateLimits?.selected ?? (Array.isArray(draft.updateCandidates) ? draft.updateCandidates.length : 0))}/${String(candidateLimits?.total ?? (Array.isArray(draft.updateCandidates) ? draft.updateCandidates.length : 0))}`,
+            `omittedUpdateCandidates: ${String(candidateLimits?.omitted ?? 0)}`
+        ].join("\n");
     }
     if ("artifactPath" in value && "unitCount" in value) {
         return renderCheck(value, "unitCount");
@@ -791,30 +1071,53 @@ function renderHuman(value) {
     if ("artifactPath" in value && "nodeCount" in value) {
         return renderCheck(value, "nodeCount");
     }
+    if ("artifactPath" in value && "proposal" in value) {
+        const checked = value;
+        const evidence = checked.proposal?.planningEvidence;
+        return [
+            `status: ${humanField(checked.status ?? "unknown")}`,
+            `artifactPath: ${humanField(checked.artifactPath)}`,
+            `constraintHints: ${String(checked.limits?.constraintHints?.selected ?? (Array.isArray(checked.proposal?.constraintHints) ? checked.proposal.constraintHints.length : 0))}/${String(checked.limits?.constraintHints?.max ?? "unknown")}`,
+            `componentHints: ${String(checked.limits?.componentHints?.selected ?? (Array.isArray(checked.proposal?.componentHints) ? checked.proposal.componentHints.length : 0))}/${String(checked.limits?.componentHints?.max ?? "unknown")}`,
+            `workflowCandidates: ${String(checked.limits?.workflowCandidates?.selected ?? (Array.isArray(evidence?.workflowCandidates) ? evidence.workflowCandidates.length : 0))}/${String(checked.limits?.workflowCandidates?.max ?? "unknown")}`,
+            `targetCandidates: ${String(checked.limits?.targetCandidates?.selected ?? (Array.isArray(evidence?.targetCandidates) ? evidence.targetCandidates.length : 0))}/${String(checked.limits?.targetCandidates?.max ?? "unknown")}`,
+            `verificationCandidates: ${String(checked.limits?.verificationCandidates?.selected ?? (Array.isArray(evidence?.verificationCandidates) ? evidence.verificationCandidates.length : 0))}/${String(checked.limits?.verificationCandidates?.max ?? "unknown")}`,
+            `ambiguities: ${String(checked.limits?.ambiguities?.selected ?? (Array.isArray(evidence?.ambiguities) ? evidence.ambiguities.length : 0))}/${String(checked.limits?.ambiguities?.max ?? "unknown")}`,
+            ...(Array.isArray(checked.errors) && checked.errors.length ? checked.errors.map((error) => `error: ${humanField(error)}`) : [])
+        ].join("\n");
+    }
     if ("skillsRoot" in value && "skillCount" in value) {
         return renderCheck(value, "skillCount");
     }
     if ("knowledgeRoot" in value && "cardCount" in value) {
         return renderCheck(value, "cardCount");
     }
-    if ("artifactPath" in value && ("proposal" in value || "decision" in value)) {
+    if ("artifactPath" in value && "decision" in value) {
         return renderCheck(value, null);
     }
     if ("contractVersion" in value && "failedCommands" in value) {
         const packet = value;
         return [
-            `status: ${String(packet.status ?? "unknown")}`,
-            `verificationStatus: ${String(packet.verificationStatus ?? "unknown")}`,
-            `failedCommands: ${Array.isArray(packet.failedCommands) ? packet.failedCommands.length : 0}`
+            `status: ${humanField(packet.status ?? "unknown")}`,
+            `verificationStatus: ${humanField(packet.verificationStatus ?? "unknown")}`,
+            `changedFiles: ${Array.isArray(packet.changedFiles) ? packet.changedFiles.length : 0}/${String(packet.limits?.totalChangedFiles ?? "unknown")}`,
+            `omittedChangedFiles: ${String(packet.limits?.omittedChangedFiles ?? 0)}`,
+            `failedCommands: ${Array.isArray(packet.failedCommands) ? packet.failedCommands.length : 0}/${String(packet.limits?.totalFailedCommands ?? "unknown")}`,
+            `omittedFailedCommands: ${String(packet.limits?.omittedFailedCommands ?? 0)}`,
+            `retryGuidanceFailedCommands: ${Array.isArray(packet.retryGuidance?.failedCommands) ? packet.retryGuidance.failedCommands.length : 0}/${String(packet.limits?.totalRetryGuidanceFailedCommands ?? "unknown")}`,
+            `omittedRetryGuidanceFailedCommands: ${String(packet.limits?.omittedRetryGuidanceFailedCommands ?? 0)}`,
+            `retryGuidanceLogs: ${Array.isArray(packet.retryGuidance?.logs) ? packet.retryGuidance.logs.length : 0}/${String(packet.limits?.totalRetryGuidanceLogs ?? "unknown")}`,
+            `omittedRetryGuidanceLogs: ${String(packet.limits?.omittedRetryGuidanceLogs ?? 0)}`,
+            `retryGuidanceInstructionTruncated: ${String(packet.limits?.retryGuidanceInstructionTruncated ?? false)}`
         ].join("\n");
     }
     if ("contractVersion" in value && "files" in value) {
         const init = value;
         return [
             `dryRun: ${String(init.dryRun ?? false)}`,
-            `needsUpdate: ${String(init.needsUpdate ?? "unknown")}`,
-            ...(Array.isArray(init.files) ? init.files.map((file) => `${String(file.path ?? "unknown")}: ${String(file.action ?? "unknown")}`) : []),
-            ...(Array.isArray(init.skills) ? init.skills.map((skill) => `${String(skill.path ?? "unknown")}: ${String(skill.action ?? "unknown")}`) : [])
+            `needsUpdate: ${humanField(init.needsUpdate ?? "unknown")}`,
+            ...(Array.isArray(init.files) ? init.files.map((file) => `${humanField(file.path ?? "unknown")}: ${humanField(file.action ?? "unknown")}`) : []),
+            ...(Array.isArray(init.skills) ? init.skills.map((skill) => `${humanField(skill.path ?? "unknown")}: ${humanField(skill.action ?? "unknown")}`) : [])
         ].join("\n");
     }
     if ("removed" in value && "kept" in value) {
@@ -828,30 +1131,36 @@ function renderHuman(value) {
     if ("preset" in value && "files" in value && Array.isArray(value["files"])) {
         const scaffold = value;
         return [
-            `status: ${String(scaffold.status ?? "unknown")}`,
-            `preset: ${String(scaffold.preset ?? "unknown")}`,
-            `target: ${String(scaffold.target ?? "unknown")}`,
-            `projectName: ${String(scaffold.projectName ?? "unknown")}`,
+            `status: ${humanField(scaffold.status ?? "unknown")}`,
+            `preset: ${humanField(scaffold.preset ?? "unknown")}`,
+            `target: ${humanField(scaffold.target ?? "unknown")}`,
+            `projectName: ${humanField(scaffold.projectName ?? "unknown")}`,
             `files: ${scaffold.files.length}`
         ].join("\n");
     }
     if ("status" in value) {
-        return `status: ${String(value["status"])}`;
+        return `status: ${humanField(value["status"])}`;
     }
     return JSON.stringify(value, null, 2);
 }
 function renderCheck(value, countKey) {
+    const errors = Array.isArray(value["errors"]) ? value["errors"] : [];
+    const warnings = Array.isArray(value["warnings"]) ? value["warnings"] : [];
+    const selectedErrors = errors.slice(0, 5);
+    const selectedWarnings = warnings.slice(0, 5);
     const lines = [
-        `status: ${String(value["status"] ?? "unknown")}`,
-        ...(value["artifactPath"] ? [`artifactPath: ${String(value["artifactPath"])}`] : []),
-        ...(value["skillsRoot"] ? [`skillsRoot: ${String(value["skillsRoot"])}`] : []),
-        ...(countKey ? [`${countKey}: ${String(value[countKey] ?? 0)}`] : [])
+        `status: ${humanField(value["status"] ?? "unknown")}`,
+        ...(value["artifactPath"] ? [`artifactPath: ${humanField(value["artifactPath"])}`] : []),
+        ...(value["skillsRoot"] ? [`skillsRoot: ${humanField(value["skillsRoot"])}`] : []),
+        ...(countKey ? [`${countKey}: ${String(value[countKey] ?? 0)}`] : []),
+        `omittedErrors: ${String(Math.max(0, errors.length - selectedErrors.length))}`,
+        `omittedWarnings: ${String(Math.max(0, warnings.length - selectedWarnings.length))}`
     ];
-    for (const error of (Array.isArray(value["errors"]) ? value["errors"] : []).slice(0, 5)) {
-        lines.push(`error: ${String(error)}`);
+    for (const error of selectedErrors) {
+        lines.push(`error: ${humanField(error)}`);
     }
-    for (const warning of (Array.isArray(value["warnings"]) ? value["warnings"] : []).slice(0, 5)) {
-        lines.push(`warning: ${String(warning)}`);
+    for (const warning of selectedWarnings) {
+        lines.push(`warning: ${humanField(warning)}`);
     }
     return lines.join("\n");
 }
@@ -892,6 +1201,19 @@ function optionalNumber(key, value) {
     }
     return { [key]: parsed };
 }
+function optionalFiniteNumber(key, value) {
+    if (value === undefined) {
+        return {};
+    }
+    if (typeof value !== "string") {
+        throw new Error("numeric flag requires a value");
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`Invalid numeric value: ${value}`);
+    }
+    return { [key]: parsed };
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }