project-librarian 0.2.1 → 0.3.0

package/dist/templates.js

@@ -1,8 +1,67 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.starterFiles = exports.decisionPolicy = exports.wikiOperatingModel = exports.inboxIndexBlock = exports.glossaryIndexBlock = exports.glossary = exports.index = exports.startup = exports.metadata = exports.wikiAgentsSection = exports.cursorRule = exports.geminiSection = exports.claudeSection = exports.agentsSection = void 0;
+exports.defaultStarterFilePaths = exports.starterFiles = exports.documentTaxonomy = exports.decisionPolicy = exports.wikiOperatingModel = exports.inboxIndexBlock = exports.glossaryIndexBlock = exports.glossary = exports.index = exports.startup = exports.metadata = exports.wikiAgentsSection = exports.cursorRule = exports.geminiSection = exports.claudeSection = exports.STARTUP_TLDR_MAX_CHARS = exports.startupTldrSyncLabel = exports.codeEvidenceTrustContract = exports.wikiTrustContract = void 0;
+exports.extractStartupTldr = extractStartupTldr;
+exports.agentsSection = agentsSection;
 const workspace_1 = require("./workspace");
-exports.agentsSection = `<!-- PROJECT-WIKI-FIRST:START -->
+// B4 (gated on B2, which ships in the same phase): a single-sentence trust
+// contract in the managed AGENTS.md block. It is the substitution mechanism that
+// stops repo-wide re-verification greps; the --doctor router-truth rule (B2)
+// guards against trusting a stale router.
+exports.wikiTrustContract = "Wiki decision documents are authoritative for project decisions: do not re-verify them against the repository unless directly conflicting code evidence appears, since the `--doctor` router-truth rule guards against stale routers.";
+// B4 analogue for code evidence: a single-sentence trust contract making the
+// code-evidence tool/report outputs authoritative for code-structure questions,
+// gated on the same staleness check the tools surface (`--code-status` /
+// `code_status`). Mirrors wikiTrustContract scale; kept budget-conscious. The
+// closing clause is the scale-conditional guidance (2026-06-12 decision, stageR1
+// evidence): on small repos simple lookups measured cheaper via direct reads.
+exports.codeEvidenceTrustContract = "Code-evidence tool and report outputs (`--code-impact`, `--code-report`, and the `project-librarian mcp` tools) are authoritative for code-structure questions: do not re-verify them with repo-wide greps unless `--code-status`/`code_status` reports staleness; on small repos below the measured scale threshold, prefer direct reads over these tools for simple lookups (measured cheaper at small scale).";
+// B1 fallback: label for the auto-synced startup TL;DR sub-block embedded in the
+// managed AGENTS.md marker section. Non-interactive `codex exec` does not run
+// SessionStart hooks (measured 2026-06-10), so AGENTS.md is the only startup
+// context carrier there; the sync stays TL;DR-only per token discipline.
+exports.startupTldrSyncLabel = "Startup TL;DR (auto-synced for non-interactive sessions; source: wiki/startup.md)";
+// Hard cap on the extracted TL;DR text embedded in AGENTS.md. The startup hook
+// budget is 3500 chars for the full wiki/startup.md; the TL;DR sub-section must
+// stay well under that so the managed block remains token-efficient. 2000 chars is
+// a documented hard bound: it leaves headroom for frontmatter, other sections, and
+// the AGENTS.md surrounding content. Per the no-fallback rule, we NEVER truncate —
+// if the extracted bullets exceed this limit the sync fails loudly so the author
+// knows to trim the TL;DR.
+exports.STARTUP_TLDR_MAX_CHARS = 2000;
+// Extract the `## TL;DR` bullet list from a startup.md body (TL;DR section ONLY —
+// never Recent Decisions or Project State). Returns the `- ` bullet lines between
+// the `## TL;DR` heading and the next `## ` heading. Throws loudly when the
+// startup body has no `## TL;DR` section, that section has no bullets, or the
+// extracted text exceeds STARTUP_TLDR_MAX_CHARS (no fallback, no silent truncation).
+function extractStartupTldr(startupMarkdown) {
+    const match = startupMarkdown.match(/^##\s+TL;DR[^\n]*\n([\s\S]*?)(?=\n##\s|(?![\s\S]))/m);
+    if (!match) {
+        throw new Error("cannot sync startup TL;DR into AGENTS.md: wiki/startup.md has no \"## TL;DR\" section");
+    }
+    const bullets = (match[1] ?? "")
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .filter((line) => /^\s*-\s+\S/.test(line));
+    if (bullets.length === 0) {
+        throw new Error("cannot sync startup TL;DR into AGENTS.md: the wiki/startup.md \"## TL;DR\" section has no bullet items");
+    }
+    const result = bullets.join("\n");
+    if (result.length > exports.STARTUP_TLDR_MAX_CHARS) {
+        throw new Error(`cannot sync startup TL;DR into AGENTS.md: extracted TL;DR is ${result.length} chars, which exceeds the ${exports.STARTUP_TLDR_MAX_CHARS}-char limit; trim the ## TL;DR section in wiki/startup.md`);
+    }
+    return result;
+}
+// Build the managed AGENTS.md marker section. The startup TL;DR is synced in as a
+// clearly labeled sub-block (B1 fallback) so non-interactive Codex sessions, which
+// never run the SessionStart hook, still receive compact startup context; the
+// trust contract sentence (B4) is appended to the during-conversation rules. Only
+// this marker block changes; user content outside the markers is untouched, and
+// because the section is built deterministically from the current startup TL;DR a
+// re-run with unchanged startup yields the same section ("exists" via
+// upsertMarkedSection).
+function agentsSection(startupTldr) {
+    return `<!-- PROJECT-WIKI-FIRST:START -->
 ## Wiki-First Planning
 
 This project uses \`./wiki\` as the durable project-planning source of truth.
@@ -13,13 +72,21 @@ At the start of every session:
 2. Review \`wiki/index.md\` as the router for which files to read next.
 3. Read detailed \`wiki/canonical/\`, \`wiki/decisions/\`, \`wiki/meta/\`, and \`wiki/sources/\` files on demand only when the current question needs them.
 
+### ${exports.startupTldrSyncLabel}
+
+${startupTldr}
+
 During conversation:
 
 - Update \`./wiki\` in the same turn when project planning content is added, changed, or removed.
+- Classify new project-planning content with \`wiki/meta/document-taxonomy.md\` before writing or consolidating it.
 - Do not store non-project LLM memory, assistant preferences, collaboration reminders, or workflow instructions in project wiki canonical or decision docs.
 - Follow \`wiki/AGENTS.md\` for detailed rules when editing files under \`wiki/\`.
 - Let \`.githooks/prepare-commit-msg\` append wiki trailers automatically for staged wiki, hook, AGENTS, or project-librarian files.
+- ${exports.wikiTrustContract}
+- ${exports.codeEvidenceTrustContract}
 <!-- PROJECT-WIKI-FIRST:END -->`;
+}
 exports.claudeSection = `<!-- PROJECT-WIKI-CLAUDE:START -->
 # Claude Code Project Instructions
 
@@ -79,6 +146,14 @@ Storage boundaries:
 - Do not store non-project LLM memory, assistant preferences, collaboration reminders, or workflow instructions in \`canonical/\` or \`decisions/\`; use root \`AGENTS.md\`, compatibility instruction files, hooks, rules, or skills instead.
 - During migration review, preserve useful meaning while converting it to the current wiki structure. Legacy files, sections, blocks, and wording may be retained when review confirms they belong in the new topic shape and remain current project truth. Do not link to or cite \`wiki_legacy*\` from the new wiki; cite current-project evidence when possible and keep unresolved or ambiguous material in migration inboxes.
 
+Classification rules:
+
+- Before adding or consolidating project content, classify it with \`meta/document-taxonomy.md\`.
+- Write current agreement to the narrowest durable canonical document that fits the taxonomy; do not append unrelated material to \`canonical/project-brief.md\`.
+- If one input crosses several lifecycle areas, split it into separate canonical updates and link the related pages.
+- If the input explains why a direction changed, update the relevant decision log or Decision Pack in addition to canonical truth.
+- If an external artifact is the better source of truth (for example Figma, OpenAPI, ERD, issue tracker, or code), keep a concise canonical summary and link the external source as the authoritative location.
+
 Update rules:
 
 - Every wiki knowledge markdown file should include compact metadata with \`status\`, \`updated\`, \`scope\`, \`read_budget\`, \`decision_ref\`, and \`review_trigger\`. This \`wiki/AGENTS.md\` instruction file is excluded from that wiki-page metadata requirement.
@@ -117,14 +192,12 @@ exports.startup = `${(0, exports.metadata)("startup-router", "short", "wiki/meta
 - At session start, read only this file and \`wiki/index.md\` first; read detailed files on demand.
 - Project canonical content language is not fixed by this bootstrap. The LLM should choose the language that best matches the user and project context.
 - Update the wiki in the same turn when project-planning content changes.
+- Classify new project-planning content with \`wiki/meta/document-taxonomy.md\` before writing or consolidating it.
 
 ## Read On Demand
 
 - [[index]]: document router.
-- [[canonical/project-brief]]: read only when product direction, audience, scope, success criteria, or core scenarios matter.
-- [[canonical/open-questions]]: read only when unresolved questions or next clarification items matter.
-- [[canonical/assumptions]]: read only when temporary assumptions or unverified premises matter.
-- [[canonical/risks]]: read only when risks, revisit triggers, or uncertainty matter.
+- [[meta/document-taxonomy]]: read only when classifying or reorganizing project wiki content.
 
 ## Project State
 
@@ -179,22 +252,7 @@ This file is a router, not a file to expand into every answer. Read only the fil
 
 ## Canonical
 
-- [[canonical/project-brief]]
-  - Read: product direction, audience, scope, success criteria, core scenarios.
-  - Update: product, audience, scope, or success criteria changes.
-  - Token budget: medium.
-- [[canonical/open-questions]]
-  - Read: unresolved questions or next clarifications.
-  - Update: questions are added, answered, or moved.
-  - Token budget: short.
-- [[canonical/assumptions]]
-  - Read: temporary assumptions or unverified premises.
-  - Update: assumptions are added, validated, or retired.
-  - Token budget: short.
-- [[canonical/risks]]
-  - Read: risks, revisit triggers, uncertainty.
-  - Update: risks are added, mitigated, or resolved.
-  - Token budget: short.
+No empty canonical starter pages are created by default. Create focused pages under \`wiki/canonical/\` only when durable project truth exists, then route them here or with \`--refresh-index\`.
 
 ## Project Decisions
 
@@ -202,18 +260,14 @@ This file is a router, not a file to expand into every answer. Read only the fil
   - Read: recent important project decisions.
   - Update: a decision belongs in startup context.
   - Token budget: short.
+- [[decisions/README]]
+  - Read: decision directory structure or decision routing conventions.
+  - Update: decision directory conventions change.
+  - Token budget: short.
 - [[decisions/log]]
   - Read: project decision timing matters.
   - Update: a trivial decision needs timestamp tracking.
   - Token budget: on-demand.
-- [[decisions/decision-pack-template]]
-  - Read: creating a Decision Pack.
-  - Update: Decision Pack format changes.
-  - Token budget: short.
-- [[decisions/full-adr-template]]
-  - Read: creating a Full ADR.
-  - Update: Full ADR format changes.
-  - Token budget: short.
 
 ## Wiki Meta
 
@@ -221,6 +275,10 @@ This file is a router, not a file to expand into every answer. Read only the fil
   - Read: wiki operation, hooks, bootstrap, maintenance, language policy.
   - Update: wiki operation or startup behavior changes.
   - Token budget: medium.
+- [[meta/document-taxonomy]]
+  - Read: classifying, writing, consolidating, splitting, or reorganizing project wiki content.
+  - Update: wiki information architecture or service-documentation categories change.
+  - Token budget: medium.
 - [[meta/decision-policy]]
   - Read: decision level, ADR need, canonical/decision split.
   - Update: decision classification or ADR criteria changes.
@@ -281,6 +339,7 @@ exports.wikiOperatingModel = `${(0, exports.metadata)("wiki-meta", "medium", "wi
 - Operating documents generated by bootstrap are English by default.
 - Project canonical content language is selected from user/project context, not hardcoded by this bootstrap.
 - Search, index refresh, inbox capture, and lifecycle checks are explicit script modes.
+- New project content is classified through [[meta/document-taxonomy]] before it is written or consolidated.
 
 ## Purpose
 
@@ -299,6 +358,18 @@ Karpathy's LLM Wiki pattern favors a continuously maintained markdown wiki over
 5. Router: read/update/token-budget guidance in \`wiki/index.md\`.
 6. Wiki meta: operating rules, decision policy, bootstrap, migration, lint, and language policy under \`wiki/meta/\`.
 
+## Content Classification Procedure
+
+Before writing or reorganizing project-planning content:
+
+1. Identify the content's lifecycle area with [[meta/document-taxonomy]].
+2. Decide whether the content is current truth, decision rationale, source evidence, an unresolved candidate, or a wiki operating rule.
+3. Write current truth to the narrowest relevant \`canonical/\` page, decision rationale to \`decisions/\`, source notes to \`sources/\`, candidates to \`inbox/\`, and wiki operating rules to \`meta/\`.
+4. Split multi-area inputs instead of making one catch-all document.
+5. Link upstream and downstream pages when the content derives from another artifact or produces another artifact.
+
+Do not treat \`canonical/project-brief.md\` as a default dumping ground. It should summarize direction, audience, scope, and success criteria; detailed product, policy, UX, data, engineering, QA, release, or operations truth should move into focused pages when it grows.
+
 ## Language Policy
 
 - Bootstrap-generated operating documents are English.
@@ -371,6 +442,106 @@ Use a Full ADR when the decision affects product direction, architecture, public
 - Do not inject full canonical or decision bodies into startup context.
 - Read long decision files only when \`wiki/index.md\` routing says they are relevant.
 `;
+exports.documentTaxonomy = `${(0, exports.metadata)("wiki-meta", "medium", "wiki/meta/wiki-ops-v1-decisions.md", "wiki information architecture, documentation categories, or content classification rules change")}
+# Document Taxonomy
+
+## TL;DR
+
+- Classify new project-planning content before writing it into the wiki.
+- Use this page to classify content into \`canonical/\`, \`decisions/\`, \`sources/\`, \`inbox/\`, or \`meta/\`.
+- Keep \`canonical/project-brief.md\` compact; move detailed truth into focused canonical pages.
+- Preserve derivation links: evidence -> strategy -> requirements -> design/data/engineering -> QA -> release/operations -> feedback.
+
+## Top-Level Flow
+
+\`\`\`text
+0. Source-of-truth governance
+  -> 1. Research and evidence
+    -> 2. Strategy and business model
+      -> 3. Product scope and requirements
+        -> 4. Policies and rules
+        -> 5. UX and content
+        -> 6. Design
+        -> 7. Data and analytics
+        -> 8. Engineering
+          -> 9. Security, legal, compliance
+          -> 10. QA and verification
+            -> 11. Release and operations
+              -> 12. Business operations
+                -> 13. Improvement, migration, and end-of-life
+                  -> next product scope, policy, or roadmap change
+\`\`\`
+
+## Storage Decision
+
+| Content Type | Store In | Notes |
+| --- | --- | --- |
+| Current valid project truth | \`wiki/canonical/\` | Split by topic and read frequency. |
+| Why a choice was made | \`wiki/decisions/\` | Use log, Decision Pack, or ADR by impact. |
+| Source material or summarized evidence | \`wiki/sources/\` | Keep links, checked dates, and applicability. |
+| Unreviewed or ambiguous material | \`wiki/inbox/\` | Do not treat as canonical truth. |
+| Wiki operation, taxonomy, hooks, migration, lint, language rules | \`wiki/meta/\` | Keep outside project canonical truth. |
+| Better external source of truth | External artifact plus a concise wiki route | Examples: Figma, OpenAPI, ERD, Jira, code. |
+
+## Lifecycle Areas
+
+| Area | Put Here | Usually Derives From | Usually Produces |
+| --- | --- | --- | --- |
+| 0. Governance | source-of-truth map, owners, RACI, approval flow, change rules, glossary, state dictionary, assumptions, risk register | team/process constraints | routing, ownership, conflict resolution |
+| 1. Research | market, competitor, user interviews, VOC, analytics, legal/regulatory, technical feasibility, cost, vendor, accessibility research | raw discovery | strategy, risks, sources |
+| 2. Strategy | service overview, vision, problem, target users, personas, jobs-to-be-done, value offer, positioning, business model, KPI/OKR, success/stop criteria, roadmap, MVP, non-goals | research | PRD, roadmap, scope |
+| 3. Product | PRD, user stories, use cases, priorities, backlog rules, acceptance criteria, feature spec, exceptions, state definitions, notification rules, search/filter/sort rules, admin requirements | strategy and policy | UX, API, data, QA |
+| 4. Policy | operations policy, auth/account, permissions, pricing, payment/refund, coupon/credit, content moderation, notifications, retention/deletion, abuse response, support, EOL | business model, law, risks | feature constraints, API rules, CS/ops |
+| 5. UX and Content | IA, sitemap, user flow, task flow, screen list, wireframes, screen specs, content model, UX writing, empty/error states, help/FAQ, localization, SEO, accessibility criteria | product and policy | design, frontend, QA |
+| 6. Design | brand guide, design principles, design system, component spec, responsive rules, interaction spec, prototype, design QA | UX and brand | UI implementation, design QA |
+| 7. Data and Analytics | ERD, data dictionary, classification, ownership/stewardship, event taxonomy, metric definitions, funnels, data quality, lineage, export/import, anonymization, dashboards | product, policy, KPI | schemas, events, reports |
+| 8. Engineering | architecture, technology decisions, API/OpenAPI, integrations, webhooks/idempotency, state machines, jobs/cron, error codes, env vars, secrets, local dev, conventions, branch/release strategy, CI/CD, feature flags, dependencies, migrations, performance, scalability, FinOps | product, UX, data, policy | implementation and verification |
+| 9. Security/Legal | security requirements, threat model, privacy rules, privacy impact, terms, privacy policy, audit logs, permission history, internal access controls, key rotation, vulnerability response, licenses, vendor and DPA documents | data, architecture, law | controls, tests, release gates |
+| 10. QA | test strategy, QA scenarios, test cases, regression checklist, UAT, browser/device matrix, accessibility tests, performance tests, security tests, data quality tests, design QA, quality gates | requirements, design, engineering | release approval |
+| 11. Release/Ops | release plan, deployment procedure, rollback, release notes, operator manual, runbooks, monitoring, observability, SLO/SLA, on-call/escalation, incident response, backup/restore, DR/BCP, recurring checks | QA and infrastructure | stable operation |
+| 12. Business Ops | CS macros, support policy, training, sales/adoption guide, CRM rules, onboarding playbook, churn/offboarding, admin operations, communication templates, revenue recognition, tax/invoice, partner operations | policy, release, sales motion | customer-facing operation |
+| 13. Improvement/EOL | VOC summary, retrospectives, experiments, experiment results, cohort/retention analysis, feature deprecation, migration/data transfer, service end-of-life | operations and analytics | next PRD, policy, roadmap |
+
+## Writing Rule
+
+When a new note arrives:
+
+1. Identify the lifecycle area and storage location.
+2. Update an existing focused page when the topic already has a canonical home.
+3. Create a new focused page only when the topic is durable, likely to be read independently, or too large for its current page.
+4. Add an \`index.md\` route when the page becomes durable.
+5. Add upstream/downstream links in prose or tables when one artifact derives from another.
+6. Record decision rationale separately when the change explains why the project chose one option over another.
+
+## Page Shape
+
+Use this shape for focused canonical pages unless a domain-specific shape is clearly better:
+
+\`\`\`md
+---
+status: active
+updated: YYYY-MM-DD
+scope: project-canonical
+read_budget: short|medium|on-demand
+decision_ref: none|wiki/decisions/...
+review_trigger: what should cause this page to change
+---
+
+# <Topic>
+
+## TL;DR
+
+- Current agreement in one to five bullets.
+
+## Current Truth
+
+## Upstream Inputs
+
+## Downstream Artifacts
+
+## Open Questions
+\`\`\`
+`;
 exports.starterFiles = {
     "wiki/README.md": `${(0, exports.metadata)("wiki-entry", "short", "wiki/meta/wiki-ops-v1-decisions.md", "top-level wiki structure changes")}
 # Project Wiki
@@ -381,10 +552,7 @@ This directory is the durable project-planning source of truth. Keep product dir
 
 - [[startup]]
 - [[index]]
-- [[canonical/project-brief]]
-- [[canonical/open-questions]]
-- [[canonical/assumptions]]
-- [[canonical/risks]]
+- [[meta/document-taxonomy]]
 `,
     "wiki/canonical/project-brief.md": `${(0, exports.metadata)("project-canonical", "medium", "none", "product direction, audience, scope, success criteria, or language choice changes")}
 # Project Brief
@@ -502,17 +670,18 @@ No project decisions yet.
 ## TL;DR
 
 - This Decision Pack records accepted wiki operating choices for project-librarian.
-- It covers wiki structure, startup hook scope, metadata, language policy, git hook behavior, migration review, and inbox handling.
+- It covers wiki structure, document taxonomy, startup hook scope, metadata, language policy, git hook behavior, migration review, and inbox handling.
 - Project product decisions belong in \`wiki/decisions/\`, while these operating decisions stay in \`wiki/meta/\`.
 
 Status: accepted
 Scope: wiki operation
-Canonical: [[meta/operating-model]], [[meta/decision-policy]]
+Canonical: [[meta/operating-model]], [[meta/decision-policy]], [[meta/document-taxonomy]]
 
 | Date | Decision | Rationale | Rejected Alternative | Revisit Trigger | Canonical Link |
 | --- | --- | --- | --- | --- | --- |
 | ${workspace_1.today} | Keep the wiki root at \`./wiki\`. | Planning docs live with the project. | External docs only. | Another tool cannot read \`./wiki\` or the team needs another path. | [[meta/operating-model]] |
 | ${workspace_1.today} | Split \`canonical/\` and \`decisions/\`. | Current truth and decision history are easier to scan when separated. | A single mixed docs directory. | The structure proves too heavy for small projects. | [[meta/decision-policy]] |
+| ${workspace_1.today} | Classify new wiki content through a service-lifecycle document taxonomy before writing or consolidating it. | Agents need a structural contract for deciding whether content is strategy, product, policy, UX, design, data, engineering, security/legal, QA, release/ops, business ops, or improvement/EOL truth. | Let agents append new content to whichever existing page is nearby. | The taxonomy becomes too heavy for small projects or repeatedly misroutes content. | [[meta/document-taxonomy]], [[meta/operating-model]] |
 | ${workspace_1.today} | Inject only \`startup.md\` and \`index.md\` through Codex, Claude Code, Cursor, and Gemini CLI startup hooks; route detailed files Read On Demand. | Full canonical and decision bodies waste startup tokens. | Always read detailed canonical and decision files first. | Important context is repeatedly missed at startup. | [[startup]], [[index]] |
 | ${workspace_1.today} | Use metadata headers on wiki knowledge pages. | Agents and humans can quickly judge status, scope, budget, and review triggers. | Body-only conventions. | Header maintenance costs more than it saves. | [[meta/operating-model]] |
 | ${workspace_1.today} | Keep wiki operating docs in \`wiki/meta/\`. | Project truth stays focused on product/project content. | Store operating docs in \`canonical/\` or \`decisions/\`. | Meta docs become hard to discover. | [[meta/operating-model]] |
@@ -523,6 +692,7 @@ Canonical: [[meta/operating-model]], [[meta/decision-policy]]
 | ${workspace_1.today} | Migration may mark rows \`needs-human-review\`. | Ambiguous, risky, or high-impact legacy content should not be closed automatically. | Force every migrated row into adopted/rejected/resolved. | Human review queues become too large. | [[meta/operating-model]] |
 | ${workspace_1.today} | Capture stores candidates in \`wiki/inbox/\`. | Useful ideas are not lost, but unreviewed content does not become canonical truth. | Save all conversation content directly into canonical docs. | Inbox content is frequently abandoned. | [[meta/operating-model]] |
 `,
+    "wiki/meta/document-taxonomy.md": exports.documentTaxonomy,
     "wiki/decisions/decision-pack-template.md": `${(0, exports.metadata)("project-decision-template", "short", "wiki/meta/decision-policy.md", "decision pack format changes", "template")}
 # <Topic> v<N> Decisions
 
@@ -571,3 +741,11 @@ Checked: ${workspace_1.today}
 - \`wiki/meta/\` stores wiki operating rules and operating decisions.
 `,
 };
+exports.defaultStarterFilePaths = new Set([
+    "wiki/README.md",
+    "wiki/decisions/README.md",
+    "wiki/decisions/log.md",
+    "wiki/decisions/recent.md",
+    "wiki/meta/document-taxonomy.md",
+    "wiki/sources/karpathy-llm-wiki.md",
+]);

package/dist/wiki-files.js

@@ -46,10 +46,9 @@ exports.extractWikiLinks = extractWikiLinks;
 exports.wikiTitleForFile = wikiTitleForFile;
 exports.metadataSummary = metadataSummary;
 exports.stripMarkedSection = stripMarkedSection;
-exports.extractMarkedSection = extractMarkedSection;
-exports.withPreservedMarkedSections = withPreservedMarkedSections;
 exports.hasGlossaryNeedSignal = hasGlossaryNeedSignal;
 exports.hasGlossaryTable = hasGlossaryTable;
+exports.firstTldrBullet = firstTldrBullet;
 exports.canonicalBodyForLint = canonicalBodyForLint;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -75,24 +74,22 @@ exports.standardWikiFiles = new Set([
     "wiki/index.md",
     "wiki/inbox/project-candidates.md",
     "wiki/migration/inventory.md",
+    "wiki/migration/unit-map.md",
+    "wiki/migration/split-plan.md",
     "wiki/migration/coverage.md",
     "wiki/migration/plan.md",
     "wiki/migration/review.md",
     "wiki/migration/verification.md",
-    "wiki/canonical/project-brief.md",
+    "wiki/migration/bulk-review.md",
     "wiki/canonical/glossary.md",
-    "wiki/canonical/open-questions.md",
-    "wiki/canonical/assumptions.md",
-    "wiki/canonical/risks.md",
     "wiki/canonical/migration-inbox.md",
     "wiki/decisions/README.md",
     "wiki/decisions/log.md",
     "wiki/decisions/recent.md",
-    "wiki/decisions/decision-pack-template.md",
-    "wiki/decisions/full-adr-template.md",
     "wiki/decisions/migration-inbox.md",
     "wiki/meta/operating-model.md",
     "wiki/meta/decision-policy.md",
+    "wiki/meta/document-taxonomy.md",
     "wiki/meta/wiki-ops-v1-decisions.md",
     "wiki/sources/karpathy-llm-wiki.md",
     "wiki/sources/migration-inbox.md",
@@ -264,25 +261,6 @@ function stripMarkedSection(text, startMarker, endMarker) {
         return text;
     return `${text.slice(0, start).trimEnd()}\n\n${text.slice(end + endMarker.length).trimStart()}`.trim() + "\n";
 }
-function extractMarkedSection(text, startMarker, endMarker) {
-    const start = text.indexOf(startMarker);
-    const end = text.indexOf(endMarker);
-    if (start < 0 || end <= start)
-        return "";
-    return text.slice(start, end + endMarker.length).trim();
-}
-function withPreservedMarkedSections(relativePath, base, markerPairs) {
-    if (!(0, workspace_1.exists)(relativePath))
-        return base;
-    const current = (0, workspace_1.read)(relativePath);
-    const preserved = markerPairs
-        .map(([startMarker, endMarker]) => extractMarkedSection(current, startMarker, endMarker))
-        .filter(Boolean)
-        .filter((section) => !base.includes(section));
-    if (preserved.length === 0)
-        return base;
-    return `${base.trimEnd()}\n\n${preserved.join("\n\n")}\n`;
-}
 function hasGlossaryNeedSignal(text) {
     return /(^|\n)##\s+(Glossary|Terms|Roles|Entities|Data Model|State Model|Permissions|Events|용어|역할|엔티티|상태 모델|권한|이벤트)(\s|$)|`[^`]+`\s*(term|role|state|permission|event|entity|API|DB|UI|용어|역할|상태|권한|이벤트|엔티티)/i.test(text);
 }
@@ -290,6 +268,16 @@ function hasGlossaryTable(text) {
     const body = (0, workspace_1.stripMetadataHeader)(text);
     return /\|\s*Term\s*\|\s*Definition\s*\|\s*Avoid\s*\|\s*Related Canonical Doc\s*\|\s*Status\s*\|/.test(body);
 }
+// First "## TL;DR" bullet for answer-shaped query envelopes: gives an agent the
+// page's one-line summary without opening the page. Pages without a TL;DR section
+// return "" and the envelope simply omits the line — quality-check separately
+// flags the missing TL;DR, so this is optional enrichment, not a fallback path.
+function firstTldrBullet(text) {
+    const body = (0, workspace_1.stripMetadataHeader)(text);
+    const match = body.match(/^##\s+TL;DR[^\n]*\n([\s\S]*?)(?=\n##\s|(?![\s\S]))/m);
+    const bullet = match?.[1]?.split(/\r?\n/).find((line) => /^\s*-\s+\S/.test(line));
+    return bullet ? bullet.replace(/^\s*-\s*/, "").trim().slice(0, 160) : "";
+}
 function canonicalBodyForLint() {
     return (0, workspace_1.walkFilesUnder)("wiki/canonical", (file) => /\.(md|mdx)$/i.test(file) && file !== "wiki/canonical/glossary.md")
         .map((file) => (0, workspace_1.stripMetadataHeader)((0, workspace_1.read)(file)))

package/dist/wiki-graph.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wikiAnswerTruncationNotice = exports.wikiAnswerCharCap = exports.wikiRouterExemptPages = exports.wikiRouterDepthBudget = exports.wikiRouterRoot = void 0;
+exports.finalizeWikiAnswer = finalizeWikiAnswer;
+exports.buildWikiGraph = buildWikiGraph;
+exports.wikiRouterDepths = wikiRouterDepths;
+exports.wikiImpactAnswer = wikiImpactAnswer;
+const wiki_files_1 = require("./wiki-files");
+const workspace_1 = require("./workspace");
+// Router reachability budget. The benchmark fixture A1 assert guarantees
+// startup -> index -> answer page within two hops; real wikis add one hop for
+// generated scoped routers (startup -> index -> wiki/indexes/auto-*.md -> page),
+// so the real-wiki budget is three hops from wiki/startup.md.
+exports.wikiRouterRoot = "wiki/startup.md";
+exports.wikiRouterDepthBudget = 3;
+// startup is the BFS root; README is a human entry document that is deliberately
+// unrouted (the same exemption the orphan-page rule uses).
+exports.wikiRouterExemptPages = new Set([exports.wikiRouterRoot, "wiki/README.md"]);
+// Answer-shape discipline for wiki-side query/impact output: answer-first text,
+// hard char cap, explicit truncation notice (never silent). Mirrors the MCP
+// server constants (src/mcp-server.ts MAX_RESPONSE_CHARS / TRUNCATION_NOTICE);
+// kept separate so the MCP server module and its node:sqlite loading path stay
+// out of the bootstrap/diagnostics path.
+exports.wikiAnswerCharCap = 4000;
+exports.wikiAnswerTruncationNotice = "[truncated — refine the query]";
+function finalizeWikiAnswer(body) {
+    if (body.length <= exports.wikiAnswerCharCap)
+        return body;
+    const budget = exports.wikiAnswerCharCap - exports.wikiAnswerTruncationNotice.length - 1;
+    return `${body.slice(0, budget > 0 ? budget : 0).trimEnd()}\n${exports.wikiAnswerTruncationNotice}`;
+}
+// decision_ref is frontmatter, not a wiki link, so the link extractor never sees
+// it; normalize it here into a page edge. "none"/"-" are the documented empty
+// markers in generated metadata headers.
+function normalizedDecisionRef(file, value) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed === "none" || trimmed === "-")
+        return "";
+    return (0, wiki_files_1.normalizeWikiLinkTarget)(file, trimmed.replace(/^\[\[|\]\]$/g, ""));
+}
+function buildWikiGraph(pages) {
+    const files = new Set(pages.map((page) => page.file));
+    const links = [];
+    const incomingLinks = new Map();
+    const outgoingLinks = new Map();
+    const incomingDecisionRefs = new Map();
+    const outgoingDecisionRef = new Map();
+    for (const page of pages) {
+        for (const link of (0, wiki_files_1.extractWikiLinks)(page.file, page.text)) {
+            links.push(link);
+            outgoingLinks.set(page.file, [...(outgoingLinks.get(page.file) ?? []), link]);
+            incomingLinks.set(link.normalizedTarget, [...(incomingLinks.get(link.normalizedTarget) ?? []), link]);
+        }
+        const ref = normalizedDecisionRef(page.file, (0, workspace_1.metadataValue)(page.text, "decision_ref"));
+        if (ref && files.has(ref)) {
+            outgoingDecisionRef.set(page.file, ref);
+            incomingDecisionRefs.set(ref, [...(incomingDecisionRefs.get(ref) ?? []), page.file]);
+        }
+    }
+    return { files, links, incomingLinks, outgoingLinks, incomingDecisionRefs, outgoingDecisionRef };
+}
+// BFS depths over existing pages from wiki/startup.md (depth 0). Pages absent
+// from the result are unreachable through the router chain. Only links whose
+// target exists are traversed; broken links are the broken-link rule's job.
+function wikiRouterDepths(graph) {
+    const depths = new Map();
+    if (!graph.files.has(exports.wikiRouterRoot))
+        return depths;
+    depths.set(exports.wikiRouterRoot, 0);
+    const queue = [exports.wikiRouterRoot];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const depth = depths.get(current) ?? 0;
+        for (const link of graph.outgoingLinks.get(current) ?? []) {
+            const target = link.normalizedTarget;
+            if (!graph.files.has(target) || depths.has(target))
+                continue;
+            depths.set(target, depth + 1);
+            queue.push(target);
+        }
+    }
+    return depths;
+}
+// Wiki impact: the --code-impact envelope shape applied to wiki maintenance.
+// Given a page or term, report which pages link to it (review candidates when it
+// changes), which pages cite it as decision_ref, what it depends on, and how the
+// router reaches it. Bounded by sampling plus the shared answer cap.
+const impactMatchCap = 5;
+const impactListCap = 12;
+function sampled(items, cap) {
+    if (items.length === 0)
+        return "none";
+    const shown = items.slice(0, cap).join(", ");
+    return items.length > cap ? `${shown}, …+${items.length - cap} more` : shown;
+}
+function uniqueSorted(values) {
+    return Array.from(new Set(values)).sort();
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+function wikiImpactAnswer(pages, term) {
+    const graph = buildWikiGraph(pages);
+    const depths = wikiRouterDepths(graph);
+    const textByFile = new Map(pages.map((page) => [page.file, page.text]));
+    const lowered = term.toLowerCase();
+    const exactTarget = (0, wiki_files_1.normalizeWikiLinkTarget)("wiki/index.md", term.replace(/^\[\[|\]\]$/g, ""));
+    const matches = pages
+        .map((page) => ({ file: page.file, title: (0, wiki_files_1.wikiTitleForFile)(page.file, page.text) }))
+        .filter((page) => page.file === exactTarget || page.file.toLowerCase().includes(lowered) || page.title.toLowerCase().includes(lowered))
+        .sort((a, b) => Number(b.file === exactTarget) - Number(a.file === exactTarget) || a.file.localeCompare(b.file));
+    if (matches.length === 0)
+        return `Wiki impact "${term}": no matching wiki pages.`;
+    const shown = matches.slice(0, impactMatchCap);
+    // Headline counts are unions across the shown matches, not sums: a page that
+    // links two matched targets is one review candidate, not two.
+    const incomingUnion = new Set(shown.flatMap((match) => (graph.incomingLinks.get(match.file) ?? []).map((link) => link.file)));
+    const refUnion = new Set(shown.flatMap((match) => graph.incomingDecisionRefs.get(match.file) ?? []));
+    const lines = [
+        `Wiki impact "${term}": ${plural(matches.length, "matching page")}${matches.length > impactMatchCap ? ` (top ${impactMatchCap} shown)` : ""}; review the ${plural(incomingUnion.size, "linking page")} and ${plural(refUnion.size, "decision_ref citation")} below when ${matches.length === 1 ? "this page changes" : "these pages change"}.`,
+    ];
+    for (const match of shown) {
+        const text = textByFile.get(match.file) ?? "";
+        const incoming = uniqueSorted((graph.incomingLinks.get(match.file) ?? []).map((link) => link.file));
+        const refs = uniqueSorted(graph.incomingDecisionRefs.get(match.file) ?? []);
+        const outgoing = uniqueSorted((graph.outgoingLinks.get(match.file) ?? []).map((link) => link.normalizedTarget));
+        const depth = depths.get(match.file);
+        const trigger = (0, workspace_1.metadataValue)(text, "review_trigger");
+        lines.push("");
+        lines.push(`${match.file} — ${match.title}`);
+        if (trigger)
+            lines.push(`  review_trigger: ${trigger}`);
+        lines.push(`  incoming links (${incoming.length}): ${sampled(incoming, impactListCap)}`);
+        lines.push(`  decision_ref from (${refs.length}): ${sampled(refs, impactListCap)}`);
+        lines.push(`  outgoing links (${outgoing.length}): ${sampled(outgoing, impactListCap)}`);
+        lines.push(depth === undefined
+            ? `  router: unreachable from ${exports.wikiRouterRoot}`
+            : `  router: reachable at depth ${depth} (budget ${exports.wikiRouterDepthBudget})`);
+    }
+    return finalizeWikiAnswer(lines.join("\n"));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-librarian",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Create and maintain compact project context for humans and LLM coding agents.",
   "license": "MIT",
   "type": "commonjs",
@@ -28,8 +28,6 @@
     "LICENSE",
     "README.md",
     "README.ko.md",
-    "README.ja.md",
-    "README.zh.md",
     "SKILL.md"
   ],
   "bin": {
@@ -45,6 +43,8 @@
     "benchmark:llm": "npm run build && node benchmarks/codex-llm-metrics.js",
     "benchmark:llm:dry-run": "npm run build && node benchmarks/codex-llm-metrics.js --dry-run",
     "benchmark:llm:parse-smoke": "node tests/validators/codex-llm-benchmark-smoke.js",
+    "benchmark:injection-sentinel": "node benchmarks/tools/injection-sentinel.js",
+    "benchmark:real-corpus:demo": "npm run build && node benchmarks/tools/real-corpus-offline-demo.js",
     "benchmark:release": "npm run benchmark:llm -- --full-matrix --runs 3 --warmup-runs 1 --min-runs-for-claim 3 --require-clean --require-claimable --out benchmarks/reports/llm/current.json --markdown benchmarks/reports/llm/current.md",
     "build": "tsc && chmod +x dist/init-project-wiki.js",
     "typecheck": "tsc --noEmit",