truecourse 0.7.0-next.0 → 0.7.0-next.1

package/cli.mjs

@@ -170270,7 +170270,7 @@ function readToolVersion() {
   if (cachedVersion)
     return cachedVersion;
   if (true) {
-    cachedVersion = "0.7.0-next.0";
+    cachedVersion = "0.7.0-next.1";
     return cachedVersion;
   }
   try {
@@ -196272,8 +196272,14 @@ var CorpusDocSchema = external_exports.object({
 var OverlapSectionSchema = external_exports.object({
   /** The doc this section lives in, by ref (one of the overlap's two docs). */
   doc: DocRefSchema,
-  /** The heading text of the conflicting section (verbatim from the doc). */
-  heading: external_exports.string()
+  /**
+   * The heading text of the conflicting section (verbatim from the doc), or
+   * `null` when the conflicting passage sits in the doc's PREAMBLE — the block
+   * before its first heading (README badges/tagline, intro line). A plain string
+   * from older corpora still parses; `null` is the preamble marker the viewer
+   * bands as the pre-first-heading block.
+   */
+  heading: external_exports.string().nullable()
 });
 var OverlapSchema = external_exports.object({
   /** The two docs that overlap, by ref. */
@@ -197210,7 +197216,9 @@ NOT a disagreement (do NOT flag):
 
 Bias: when there is a PLAUSIBLE contradiction a human should check, flag it. When the docs are clearly complementary or agree, do not.
 
-When you flag an overlap, also identify the SECTIONS that conflict: the nearest markdown heading (the \`#\`/\`##\`/\`###\` title, verbatim, WITHOUT the leading #s) above the conflicting text in EACH doc. List one entry per side; omit a side only if it genuinely has no heading.
+When you flag an overlap, also identify the SECTIONS that conflict: the nearest markdown heading (the \`#\`/\`##\`/\`###\` title, verbatim, WITHOUT the leading #s) above the conflicting text in EACH doc. List one entry per side; omit a side only when it genuinely has no conflicting passage.
+
+PREAMBLE: when a doc's conflicting passage sits ABOVE its first \`#\` heading \u2014 the preamble block (a README's badges, tagline, or the intro line before any heading) \u2014 there is no heading to name. Set that side's \`heading\` to the JSON literal \`null\` (not the string "null", not ""). Use \`null\` ONLY for that pre-first-heading block; whenever the passage is under a heading, name the heading verbatim.
 
 In the NOTE, refer to each doc by its FILENAME (the basename shown in the header, e.g. \`users.md\`) \u2014 NEVER "doc A" / "doc B", which mean nothing to the reader.
 
@@ -197220,6 +197228,12 @@ Output ONLY a JSON object, no prose, no code fences:
   "note": "users.md uses auth0_id; identity.md uses auth0_sub for the same user column",
   "sections": [ { "side": "A", "heading": "User model" }, { "side": "B", "heading": "Identity" } ] }
 
+Preamble example \u2014 doc A's claim is a README badge/tagline above any heading, so its side uses null:
+
+{ "overlap": true,
+  "note": "README.md lists C# as a supported language in the preamble; plan.md's Tech Stack omits it",
+  "sections": [ { "side": "A", "heading": null }, { "side": "B", "heading": "Tech Stack" } ] }
+
 Use { "overlap": false, "note": "", "sections": [] } when they are complementary or agree. The note is shown to the user \u2014 name the specific thing that differs.`;
 var OVERLAP_PREVIEW_LINES = 120;
 function docBody2(doc) {
@@ -197271,12 +197285,12 @@ function buildOverlapUserPrompt(areaId, a, b) {
 var LlmOverlapSchema = external_exports.object({
   overlap: external_exports.boolean(),
   note: external_exports.string().default(""),
-  sections: external_exports.array(external_exports.object({ side: external_exports.enum(["A", "B"]), heading: external_exports.string() })).default([])
+  sections: external_exports.array(external_exports.object({ side: external_exports.enum(["A", "B"]), heading: external_exports.string().nullable() })).default([])
 });
 var OverlapVerdictSchema = external_exports.object({
   overlap: external_exports.boolean(),
   note: external_exports.string().default(""),
-  sections: external_exports.array(external_exports.object({ doc: external_exports.string(), heading: external_exports.string() })).default([])
+  sections: external_exports.array(external_exports.object({ doc: external_exports.string(), heading: external_exports.string().nullable() })).default([])
 });
 function spawnOverlapRunner(opts = {}) {
   const transport = opts.transport ?? cliTransport({ bin: opts.bin });
@@ -197628,7 +197642,7 @@ async function classifyOne(repoRoot5, doc, runner) {
   await writeCache4(repoRoot5, cacheKey, verdict);
   return verdict;
 }
-var RELEVANCE_SYSTEM_PROMPT = `You are a documentation relevance classifier. Classify by CONTENT, not by folder or filename: does this doc state durable, intended behavior or decisions about THE SYSTEM IN THIS REPOSITORY (its endpoints, data, auth, events, invariants, business rules, architecture)?
+var RELEVANCE_SYSTEM_PROMPT = `You are a documentation relevance classifier. Judge mainly by CONTENT \u2014 does this doc state durable, intended behavior or decisions about THE SYSTEM IN THIS REPOSITORY (its endpoints, data, auth, events, invariants, business rules, architecture)? The doc's PATH (given below) is evidence too, never an automatic verdict: weigh path and content together.
 
 ${OUTPUT_ONLY_GUARDRAIL}
 
@@ -197641,22 +197655,23 @@ INCLUDE (spec-source material):
 SKIP (not spec-source material):
   - Pure status / TODO checklists, kanban boards, release notes / changelog drafts
   - Docs about a THIRD-PARTY / external system (vendor API research, integration notes) \u2014 that is someone else's contract, not ours, and cannot be verified against this codebase
+  - TEST-DATA specs: a doc under a test / fixture / sample / example tree (PATH segments like tests/, fixtures/, __fixtures__/, examples/, sample-*) that describes a FICTIONAL or sample product used as test data for THIS repo's own tooling \u2014 that product is not this repository's system, so its "spec" is not ours. (The path is evidence, not proof: if the doc plainly describes THIS repository's real product or engineering, keep it.)
   - SUPERSEDED docs \u2014 an older version of a newer doc covering the same subject
   - Process / meta docs not about product behavior: contribution / onboarding guides, code-style guides, deployment runbooks (keep a deployment doc ONLY if it states our runtime contracts)
   - Exploratory scratch with no committed decisions (brain dumps, open-questions-only notes)
   - AI-agent instructions / prompt templates; personal engineering journals
 
-Distinguish "states a decision about our system" (INCLUDE) from "tracks status / describes an external system / is superseded / is process" (SKIP). The SKIP categories above are explicit \u2014 they are not "doubt." WHEN GENUINELY AMBIGUOUS: include (dropping a real spec doc costs more than keeping noise).
+Distinguish "states a decision about our system" (INCLUDE) from "tracks status / describes an external or test-data product / is superseded / is process" (SKIP). The SKIP categories above are explicit \u2014 they are not "doubt." WHEN GENUINELY AMBIGUOUS: include (dropping a real spec doc costs more than keeping noise).
 
 Output ONLY a JSON object:
 
   { "include": true|false, "reason": "short explanation" }
 
-The reason is shown to the user in the dashboard \u2014 be specific ("vendor API research (ServiceTitan)", "superseded by capacity-ml-plan-v3", "deployment runbook, no product contracts") so they can verify the call.`;
+The reason is shown to the user in the dashboard \u2014 be specific ("vendor API research (ServiceTitan)", "superseded by capacity-ml-plan-v3", "deployment runbook, no product contracts", "test-data spec for a sample product (tests/fixtures/\u2026)") so they can verify the call.`;
 function buildRelevanceUserPrompt(doc) {
   const preview = doc.preview.split("\n").slice(0, 60).join("\n");
   return [
-    `Path: ${doc.path}`,
+    `PATH (repo-relative): ${doc.path}`,
     `Detected kind: ${doc.kind}`,
     `Size: ${doc.size} bytes`,
     "",
@@ -210089,12 +210104,18 @@ async function runSpecDocsSkipped(opts = {}) {
     "Force-include a skipped doc with `spec docs include <path>`; force-exclude a kept doc with `spec docs exclude <path>`."
   );
 }
-async function runSpecDocsInclude(docPath, opts = {}) {
+async function runSpecDocsInclude(docPaths, opts = {}) {
   const root2 = repoRoot3(opts);
-  if (!docPath) return fail3("Missing doc path");
-  await addManualInclude(root2, docPath);
+  const paths = docPaths.filter(Boolean);
+  if (paths.length === 0) return fail3("Missing doc path");
+  for (const docPath of paths) {
+    await addManualInclude(root2, docPath);
+    O2.step(`Force-included ${docPath}`);
+  }
   await reScan2(root2);
-  gt(`Force-include ${docPath} \u2014 re-scanned. Review \`truecourse spec conflicts list\`.`);
+  gt(
+    paths.length === 1 ? `Force-include ${paths[0]} \u2014 re-scanned. Review \`truecourse spec conflicts list\`.` : `Force-included ${paths.length} docs \u2014 re-scanned once. Review \`truecourse spec conflicts list\`.`
+  );
 }
 async function runSpecDocsUninclude(docPath, opts = {}) {
   const root2 = repoRoot3(opts);
@@ -210103,12 +210124,18 @@ async function runSpecDocsUninclude(docPath, opts = {}) {
   await reScan2(root2);
   gt(`Removed force-include for ${docPath} \u2014 re-scanned.`);
 }
-async function runSpecDocsExclude(docPath, opts = {}) {
+async function runSpecDocsExclude(docPaths, opts = {}) {
   const root2 = repoRoot3(opts);
-  if (!docPath) return fail3("Missing doc path");
-  await addManualExclude(root2, docPath);
+  const paths = docPaths.filter(Boolean);
+  if (paths.length === 0) return fail3("Missing doc path");
+  for (const docPath of paths) {
+    await addManualExclude(root2, docPath);
+    O2.step(`Force-excluded ${docPath}`);
+  }
   await reScan2(root2);
-  gt(`Force-exclude ${docPath} \u2014 re-scanned. Review \`truecourse spec conflicts list\`.`);
+  gt(
+    paths.length === 1 ? `Force-exclude ${paths[0]} \u2014 re-scanned. Review \`truecourse spec conflicts list\`.` : `Force-excluded ${paths.length} docs \u2014 re-scanned once. Review \`truecourse spec conflicts list\`.`
+  );
 }
 async function runSpecDocsUnexclude(docPath, opts = {}) {
   const root2 = repoRoot3(opts);
@@ -211080,7 +211107,7 @@ async function runHooksRun() {
 
 // tools/cli/src/index.ts
 var program2 = new Command();
-program2.name("truecourse").version("0.7.0-next.0").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
+program2.name("truecourse").version("0.7.0-next.1").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
 var dashboardCmd = program2.command("dashboard").description("Start the TrueCourse dashboard and open it in your browser").option("--reconfigure", "Re-prompt for console vs background service mode").option("--service", "Run as a background service (skips mode prompt)").option("--console", "Run in this terminal (skips mode prompt)").action(async (options) => {
   if (options.service && options.console) {
     console.error("error: --service and --console are mutually exclusive");
@@ -211193,14 +211220,14 @@ docsCmd.command("list").description("List the kept (corpus) docs with their area
 docsCmd.command("skipped").description("List docs the relevance filter excluded from extraction").action(async () => {
   await runSpecDocsSkipped();
 });
-docsCmd.command("include <path>").description("Force-include a skipped doc and re-scan").action(async (docPath) => {
-  await runSpecDocsInclude(docPath);
+docsCmd.command("include <path...>").description("Force-include one or more skipped docs and re-scan once").action(async (docPaths) => {
+  await runSpecDocsInclude(docPaths);
 });
 docsCmd.command("uninclude <path>").description("Remove a force-include override").action(async (docPath) => {
   await runSpecDocsUninclude(docPath);
 });
-docsCmd.command("exclude <path>").description("Force-exclude a kept doc from the corpus and re-scan").action(async (docPath) => {
-  await runSpecDocsExclude(docPath);
+docsCmd.command("exclude <path...>").description("Force-exclude one or more kept docs from the corpus and re-scan once").action(async (docPaths) => {
+  await runSpecDocsExclude(docPaths);
 });
 docsCmd.command("unexclude <path>").description("Remove a force-exclude override").action(async (docPath) => {
   await runSpecDocsUnexclude(docPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "truecourse",
-  "version": "0.7.0-next.0",
+  "version": "0.7.0-next.1",
   "description": "Visualize your codebase architecture as an interactive graph",
   "type": "module",
   "bin": {