@treeseed/dsh-chapters 0.1.0

package/lib/rules-commands.js

@@ -0,0 +1,138 @@
+/**
+ * P3 S2 — the /chapters-rule command family (record §7.2), as a pure-ish
+ * module so the lifecycle is testable without a commands service.
+ *
+ *   /chapters-rule add <category> <text…>
+ *   /chapters-rule list [--all | --proposed | --category <c>]
+ *   /chapters-rule approve <id> | revoke <id>
+ *
+ * Identity: '<harnessId>/<NNN>'. Files are write-once; status is a per-machine
+ * curation fact (§15 amendment) appended to the mirror's own edits/<harness>/
+ * curation.jsonl and pushed immediately (offline-safe: the local commit still
+ * happens; push coalesces later). Commands never enter the model context.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { renderRuleFile, rulePath, collectMirrorRules, appendRuleStatusFact, } from "./rules.js";
+const HELP = 'usage: /chapters-rule add <category> <text> | list [--all|--proposed|--category <c>] | approve <id> | revoke <id>';
+export async function rulesCommand(io, args) {
+    const parts = args.trim().split(/\s+/).filter((p) => p.length > 0);
+    const verb = parts[0] ?? 'help';
+    const cwd = io.cwd();
+    const project = io.projectFor(cwd);
+    if (project === undefined) {
+        return { kind: 'error', text: 'no knowledge repository is linked for this workspace — link one with /chapters-link first (rules are shared state)' };
+    }
+    const mirror = io.mirrorDir(cwd);
+    // every rule known to THIS machine: mirror files (all authors) ∪ own domain records (pre-sync)
+    const known = () => {
+        const byId = new Map();
+        for (const r of collectMirrorRules(mirror, project.projectKey, io.harnessId)) {
+            byId.set(r.id, { id: r.id, category: r.category, title: r.title, status: r.status, sourceSession: '' });
+        }
+        for (const [, rec] of io.store.rules()) {
+            if (rec.projectKey !== project.projectKey)
+                continue;
+            const prev = byId.get(rec.id);
+            byId.set(rec.id, { id: rec.id, category: rec.category, title: rec.title, status: prev?.status ?? 'proposed', sourceSession: io.sourceSession ?? 'manual' });
+        }
+        return [...byId.values()].sort((a, b) => a.id < b.id ? -1 : 1);
+    };
+    if (verb === 'add') {
+        const category = parts[1];
+        const body = parts.slice(2).join(' ');
+        if (category === undefined || body.length < 10) {
+            return { kind: 'error', text: `add needs a category and at least a sentence of rule text. ${HELP}` };
+        }
+        let number = 1;
+        for (const [id] of io.store.rules()) {
+            const m = new RegExp(`^${io.harnessId}/(\\d{3})$`).exec(id);
+            if (m !== null)
+                number = Math.max(number, Number(m[1]) + 1);
+        }
+        const title = body.split(/[.!?\n]/)[0].trim().slice(0, 60);
+        let rel = rulePath(io.storeRoot, io.harnessId, number, category, title);
+        let abs = path.join(cwd, rel);
+        // The domain may be fresh while disk is not (e2e rebuilds the home every
+        // boot; per-machine rule files are write-once): walk past any number the
+        // disk already holds rather than refuse. Refusing was the r39-era e2e
+        // deadlock — add could never land again in a dirty workspace. The walk is
+        // keyed on the NUMBER PREFIX, not the exact path: a disk ghost of a dead
+        // rule (its title killed, its domain record gone) still owns its number —
+        // reusing that number for a different title would mint two files sharing
+        // one id (approve-by-id would be ambiguous).
+        const rulesDir = path.join(cwd, io.storeRoot, 'rules', io.harnessId);
+        const numberTaken = (n) => {
+            const prefix = `${String(n).padStart(3, '0')}-`;
+            try {
+                return fs.readdirSync(rulesDir).some((f) => f.startsWith(prefix));
+            }
+            catch {
+                return false;
+            }
+        };
+        for (let hops = 0; (numberTaken(number) || fs.existsSync(abs)) && hops < 200; hops += 1) {
+            number += 1;
+            rel = rulePath(io.storeRoot, io.harnessId, number, category, title);
+            abs = path.join(cwd, rel);
+        }
+        if (numberTaken(number) || fs.existsSync(abs))
+            return { kind: 'error', text: `refusing to overwrite ${rel} (rule files are write-once; 200 number slots exhausted?)` };
+        const id = `${io.harnessId}/${String(number).padStart(3, '0')}`;
+        const rec = {
+            id, projectKey: project.projectKey, number, path: rel,
+            category: category.toLowerCase(), title, sourceSession: io.sourceSession ?? 'manual', at: io.now().toISOString(),
+        };
+        try {
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, renderRuleFile({ number, category: rec.category, title, sourceSession: io.sourceSession ?? 'manual', at: rec.at, body: body + '\n' }));
+            await io.store.putRule(id, rec);
+        }
+        catch (error) {
+            return { kind: 'error', text: `rule add failed: ${String(error?.message ?? error).slice(0, 160)}` };
+        }
+        await io.syncNow(cwd);
+        return { kind: 'success', text: `rule ${id} proposed (category ${rec.category}) — approve it into this machine's core set with: /chapters-rule approve ${id}` };
+    }
+    if (verb === 'list') {
+        const all = parts.includes('--all');
+        const proposedOnly = parts.includes('--proposed');
+        const catIdx = parts.indexOf('--category');
+        const cat = catIdx > -1 ? (parts[catIdx + 1] ?? '').toLowerCase() : '';
+        let rows = known();
+        if (cat !== '')
+            rows = rows.filter((r) => r.category === cat);
+        if (!all && !proposedOnly)
+            rows = rows.filter((r) => r.status !== 'revoked');
+        if (proposedOnly)
+            rows = rows.filter((r) => r.status === 'proposed');
+        if (rows.length === 0)
+            return { kind: 'success', text: 'no rules match' };
+        const text = rows.map((r) => `${r.id.padEnd(12)} ${r.status.padEnd(9)} ${r.category.padEnd(14)} ${r.title}`).join('\n');
+        return { kind: 'success', text: `id           status    category       title\n${text}` };
+    }
+    if (verb === 'approve' || verb === 'revoke') {
+        let id = parts[1] ?? '';
+        if (id === '')
+            return { kind: 'error', text: `${verb} needs a rule id (see /chapters-rule list)` };
+        if (!id.includes('/'))
+            id = `${io.harnessId}/${id.padStart(3, '0')}`;
+        const exists = known().some((r) => r.id === id);
+        if (!exists)
+            return { kind: 'error', text: `no rule ${id} in project ${project.slug} — unknown id (list shows what exists)` };
+        try {
+            // 'approve' is the verb; 'core' is the status — conflating them writes a
+            // fact no resolver recognizes (caught by unit test)
+            appendRuleStatusFact(mirror, io.harnessId, { rule: id, status: verb === 'approve' ? 'core' : 'revoked', at: io.now().toISOString() });
+        }
+        catch (error) {
+            return { kind: 'error', text: `${verb} failed: ${String(error?.message ?? error).slice(0, 160)}` };
+        }
+        await io.syncNow(cwd);
+        return { kind: 'success', text: verb === 'approve'
+                ? `rule ${id} is CORE on THIS machine (other machines approve independently) — it will render into continuations from this workspace`
+                : `rule ${id} revoked on this machine (out of the notice, still in the repo)` };
+    }
+    return { kind: 'success', text: HELP };
+}
+//# sourceMappingURL=rules-commands.js.map

package/lib/rules-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules-commands.js","sourceRoot":"","sources":["../src/rules-commands.ts"],"names":[],"mappings":"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"}

package/lib/rules.d.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+export declare const RULE_STATUS: readonly ["proposed", "core", "revoked"];
+export type RuleStatus = (typeof RULE_STATUS)[number];
+export interface RuleRecord {
+    id: string;
+    projectKey: string;
+    number: number;
+    path: string;
+    category: string;
+    title: string;
+    sourceSession: string;
+    at: string;
+}
+export declare const ruleRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    projectKey: z.ZodString;
+    number: z.ZodNumber;
+    path: z.ZodString;
+    category: z.ZodString;
+    title: z.ZodString;
+    sourceSession: z.ZodString;
+    at: z.ZodString;
+}, z.core.$strip>;
+export declare const ruleSlug: (category: string, title: string) => string;
+export declare const rulePath: (storeRoot: string, harnessId: string, number: number, category: string, title: string) => string;
+/** one write, ever: rules are proposed by their author and never rewritten (status rides facts) */
+export declare function renderRuleFile(input: {
+    number: number;
+    category: string;
+    title: string;
+    sourceSession: string;
+    at: string;
+    body: string;
+}): string;
+export interface ParsedRule {
+    number: number;
+    category: string;
+    title: string;
+    fileStatus: RuleStatus;
+    sourceSession: string;
+    body: string;
+}
+export declare function parseRuleFile(text: string): ParsedRule | null;
+export interface RuleStatusFact {
+    rule: string;
+    status: RuleStatus;
+    at: string;
+}
+/** the machine's own facts, last-write-wins per rule (append-only file order) */
+export declare function loadRuleStatusFacts(mirrorDir: string, harnessId: string): Map<string, RuleStatusFact>;
+/** append-only, like every other curation write */
+export declare function appendRuleStatusFact(mirrorDir: string, harnessId: string, fact: RuleStatusFact): void;
+export declare function effectiveStatus(ruleId: string, facts: Map<string, RuleStatusFact>, fileStatus: RuleStatus): RuleStatus;
+export interface MirrorRule {
+    id: string;
+    relPath: string;
+    status: RuleStatus;
+    category: string;
+    title: string;
+    body: string;
+    bodyTokens: number;
+}
+/** every rule file the mirror knows for one project, with THIS machine's effective status */
+export declare function collectMirrorRules(mirrorDir: string, projectKey: string, harnessId: string): MirrorRule[];
+export type RulesSectionResult = {
+    kind: 'none';
+} | {
+    kind: 'ok';
+    text: string;
+    tokens: number;
+} | {
+    kind: 'refusal';
+    reason: string;
+    perRule: Array<{
+        id: string;
+        tokens: number;
+    }>;
+    cap: number;
+    total: number;
+};
+/**
+ * §7.3: the notice's rules block. `kind: 'none'` (empty rules or no corpus)
+ * MUST produce zero injected bytes at the call site — the existing tape
+ * corpus depends on it. Overflow refuses with per-rule numbers, never clips.
+ */
+export declare function buildRulesSection(mirrorDir: string, opts: {
+    projectKey: string;
+    harnessId: string;
+    budgetTokens: number;
+}): RulesSectionResult;

package/lib/rules.js

@@ -0,0 +1,185 @@
+/**
+ * P3 — rules are chapters of a different kind (record §7.1): same file
+ * format, same sync, searched like anything else; this module adds ONLY the
+ * lifecycle-shaped parts:
+ *
+ *   - the rule file (written ONCE, status: proposed, immutable thereafter),
+ *   - the per-machine status resolution (§15 amendment 2026-09-20): effective
+ *     status comes from the APPROVING MACHINE's own curation facts
+ *     (edits/<harnessId>/curation.jsonl, `rule-status` entries), never from a
+ *     file rewrite — authorship stays partitioned, and a rule proposed on one
+ *     machine affects no other machine's notice until a human there approves,
+ *   - the notice section (§7.3): core rules verbatim + a category index,
+ *     budgeted, refuse-with-numbers on overflow, and — load-bearing for the
+ *     tape corpus — BYTE-IDENTICAL NOTHING when there are no rules: an empty
+ *     project renders no section at all.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { estimateTokens, sha256 } from "./render.js";
+import { parseCuration } from "./indexing.js";
+import { parseChapterFile } from "./enrich-store.js";
+export const RULE_STATUS = ['proposed', 'core', 'revoked'];
+export const ruleRecordSchema = z.object({
+    id: z.string().min(3),
+    projectKey: z.string().min(1),
+    number: z.number().int().positive(),
+    path: z.string().min(1),
+    category: z.string().min(1),
+    title: z.string(),
+    sourceSession: z.string(),
+    at: z.string(),
+});
+export const ruleSlug = (category, title) => {
+    const s = (t) => t.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40);
+    return `${s(category) || 'rule'}-${s(title) || 'untitled'}`;
+};
+export const rulePath = (storeRoot, harnessId, number, category, title) => path.posix.join(storeRoot, 'rules', harnessId, `${String(number).padStart(3, '0')}-${ruleSlug(category, title)}.md`);
+/** one write, ever: rules are proposed by their author and never rewritten (status rides facts) */
+export function renderRuleFile(input) {
+    return [
+        '---',
+        `number: ${input.number}`,
+        'kind: rule',
+        `category: ${JSON.stringify(input.category)}`,
+        `title: ${JSON.stringify(input.title)}`,
+        'status: proposed',
+        `sourceSession: ${JSON.stringify(input.sourceSession)}`,
+        `authoredAt: ${JSON.stringify(input.at)}`,
+        `sha256: ${sha256(input.body)}`,
+        '---',
+        input.body,
+    ].join('\n');
+}
+export function parseRuleFile(text) {
+    try {
+        const doc = parseChapterFile(text);
+        const fm = new Map();
+        for (const line of doc.fmLines) {
+            const m = /^([A-Za-z][\w]*):\s*(.*)$/.exec(line);
+            if (m !== null)
+                fm.set(m[1], m[2].trim());
+        }
+        if (fm.get('kind') !== 'rule')
+            return null;
+        const unq = (v, d) => (v ?? d).replace(/^"|"$/g, '');
+        const rawStatus = unq(fm.get('status'), 'proposed');
+        return {
+            number: Number(fm.get('number') ?? '0'),
+            category: unq(fm.get('category'), 'general'),
+            title: unq(fm.get('title'), ''),
+            fileStatus: RULE_STATUS.includes(rawStatus) ? rawStatus : 'proposed',
+            sourceSession: unq(fm.get('sourceSession'), ''),
+            body: doc.body,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** the machine's own facts, last-write-wins per rule (append-only file order) */
+export function loadRuleStatusFacts(mirrorDir, harnessId) {
+    const out = new Map();
+    const file = path.join(mirrorDir, 'edits', harnessId, 'curation.jsonl');
+    if (!fs.existsSync(file))
+        return out;
+    for (const f of parseCuration(fs.readFileSync(file, 'utf8'))) {
+        if (f.type !== 'rule-status')
+            continue;
+        const f2 = f;
+        if (typeof f2.rule !== 'string' || typeof f2.status !== 'string')
+            continue;
+        if (!RULE_STATUS.includes(f2.status))
+            continue;
+        out.set(f2.rule, { rule: f2.rule, status: f2.status, at: f2.at ?? '' });
+    }
+    return out;
+}
+/** append-only, like every other curation write */
+export function appendRuleStatusFact(mirrorDir, harnessId, fact) {
+    const dir = path.join(mirrorDir, 'edits', harnessId);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(path.join(dir, 'curation.jsonl'), JSON.stringify({ type: 'rule-status', ...fact }) + '\n');
+}
+export function effectiveStatus(ruleId, facts, fileStatus) {
+    return facts.get(ruleId)?.status ?? fileStatus;
+}
+/** every rule file the mirror knows for one project, with THIS machine's effective status */
+export function collectMirrorRules(mirrorDir, projectKey, harnessId) {
+    const root = path.join(mirrorDir, 'rules', projectKey);
+    if (!fs.existsSync(root))
+        return [];
+    const facts = loadRuleStatusFacts(mirrorDir, harnessId);
+    const out = [];
+    const walk = (dir, rel) => {
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            const p = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                walk(p, rel === '' ? e.name : path.join(rel, e.name));
+                continue;
+            }
+            if (!e.name.endsWith('.md'))
+                continue;
+            const relPath = path.posix.join('rules', projectKey, rel === '' ? e.name : `${rel}/${e.name}`);
+            const rule = parseRuleFile(fs.readFileSync(p, 'utf8'));
+            if (rule === null)
+                continue;
+            const harness = e.name === '' ? harnessId : path.basename(path.dirname(p));
+            const id = `${harness}/${String(rule.number).padStart(3, '0')}`;
+            const status = effectiveStatus(id, facts, rule.fileStatus);
+            out.push({ id, relPath, status, category: rule.category, title: rule.title, body: rule.body.trim(), bodyTokens: estimateTokens(rule.body.trim()) });
+        }
+    };
+    walk(root, '');
+    return out.sort((a, b) => a.category < b.category ? -1 : a.category > b.category ? 1 : a.id < b.id ? -1 : 1);
+}
+/**
+ * §7.3: the notice's rules block. `kind: 'none'` (empty rules or no corpus)
+ * MUST produce zero injected bytes at the call site — the existing tape
+ * corpus depends on it. Overflow refuses with per-rule numbers, never clips.
+ */
+export function buildRulesSection(mirrorDir, opts) {
+    const rules = collectMirrorRules(mirrorDir, opts.projectKey, opts.harnessId);
+    const core = rules.filter((r) => r.status === 'core');
+    const categories = new Map();
+    for (const r of rules) {
+        if (r.status === 'revoked')
+            continue;
+        const prev = categories.get(r.category);
+        categories.set(r.category, {
+            count: (prev?.count ?? 0) + 1,
+            essence: prev?.essence ?? r.title,
+            samplePath: prev?.samplePath ?? r.relPath,
+        });
+    }
+    if (core.length === 0 && categories.size === 0)
+        return { kind: 'none' };
+    const lines = [];
+    if (core.length > 0) {
+        lines.push('## CORE RULES (approved for this project — follow them)');
+        let total = 0;
+        for (const r of core)
+            total += r.bodyTokens;
+        if (total > opts.budgetTokens) {
+            return {
+                kind: 'refusal',
+                reason: `core rules exceed their budget: ${total} tokens over a cap of ${opts.budgetTokens}. Revoke one ("/chapters-rule revoke <id>") or split a category — the notice never clips rules.`,
+                perRule: core.map((r) => ({ id: r.id, tokens: r.bodyTokens })),
+                cap: opts.budgetTokens,
+                total,
+            };
+        }
+        for (const r of core)
+            lines.push(`[${r.id}] (${r.category}) ${r.body}`, '');
+    }
+    if (categories.size > 0) {
+        lines.push('Rule categories (load a category from the repo when this session\u2019s topics overlap it):');
+        for (const [cat, m] of [...categories.entries()].sort((a, b) => a[0] < b[0] ? -1 : 1)) {
+            lines.push(`- ${cat} (${m.count}): ${m.essence} — e.g. ${m.samplePath}`);
+        }
+    }
+    const text = lines.join('\n').trimEnd();
+    return { kind: 'ok', text, tokens: estimateTokens(text) };
+}
+//# sourceMappingURL=rules.js.map

package/lib/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"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"}

package/lib/search.d.ts

@@ -0,0 +1,48 @@
+import { type IndexEntry } from './indexing.ts';
+export interface SearchResult {
+    score: number;
+    date: string;
+    kind: 'chapter' | 'rule';
+    title: string;
+    path: string;
+    /** S5 stitch view: every member file behind a coherented entry. */
+    paths?: string[];
+    topics: string[];
+}
+export interface SearchOutcome {
+    results: SearchResult[];
+    /** Every match found (results may be a packed prefix of this). */
+    total: number;
+    shown: number;
+    budget: {
+        requested: number;
+        used: number;
+        remaining: number;
+    };
+    line: string;
+}
+/** Term-hit score: topic hits 2x, title 1x, summary 1x. Zero = no match, full stop. */
+export declare function baseScore(entry: IndexEntry, terms: readonly string[], summary: string): number;
+/**
+ * The full score: term hits plus a recency tie-break. Recency ONLY breaks
+ * ties between real matches — a fresh mtime must never rank an entry that
+ * matches no term (that would surface unrelated fresh files on any query).
+ */
+export declare function scoreEntry(entry: IndexEntry, terms: readonly string[], now: number, summary: string): number;
+/** Load the corpus from a clone directory: chapters + rules, frontmatter-parsed. */
+export declare function loadCorpus(cloneDir: string): {
+    entries: IndexEntry[];
+    summaries: Map<string, string>;
+};
+/**
+ * The search itself: score, sort (score desc, then path for determinism),
+ * format lines `score | date | kind | title | path (topics: …)`, and pack
+ * lines to the requested token budget. The agent sees `total` vs `shown` so
+ * it can re-request with a larger budget — no silent truncation.
+ */
+export declare function searchKnowledge(cloneDir: string, query: string, maxTokens: number, opts?: {
+    now?: number;
+    projectKey?: string;
+    harnessId?: string;
+    rulesCoreBonus?: number;
+}): SearchOutcome;

package/lib/search.js

@@ -0,0 +1,152 @@
+/**
+ * Knowledge search (knowledge-repo.md §8): a DETERMINISTIC scorer over the
+ * mirrored corpus (the clone is the corpus — it holds local + pulled files),
+ * packed to a token budget the AGENT chooses (it knows its window; we
+ * measure with the project's one estimator). No model in the loop, ever —
+ * reproducible, inspectable, and free.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { entryFromChapter } from "./indexing.js";
+function entryBody(text) {
+    const i = text.indexOf('\n---\n');
+    return i === -1 ? '' : text.slice(i + 5).trim();
+}
+import { estimateTokens } from "./render.js";
+import { collectMirrorRules } from "./rules.js";
+import { stitchFragments } from "./indexing.js";
+const DAY = 24 * 60 * 60 * 1000;
+const tokenize = (text) => text.toLowerCase().split(/[^a-z0-9/._-]+/).filter((t) => t.length >= 2 && t !== 'the' && t !== 'and');
+const recencyBonus = (mtime, now) => {
+    if (mtime === undefined)
+        return 0;
+    const ageDays = (now - mtime) / DAY;
+    if (ageDays <= 30)
+        return 1;
+    if (ageDays <= 180)
+        return 0.5;
+    return 0;
+};
+/** Term-hit score: topic hits 2x, title 1x, summary 1x. Zero = no match, full stop. */
+export function baseScore(entry, terms, summary) {
+    let score = 0;
+    for (const t of terms) {
+        if (entry.topics.some((topic) => topic.toLowerCase().includes(t)))
+            score += 2;
+        if (entry.category !== undefined && entry.category.toLowerCase().includes(t))
+            score += 1.5;
+        if (entry.title.toLowerCase().includes(t))
+            score += 1;
+        if (summary.toLowerCase().includes(t))
+            score += 1;
+    }
+    return score;
+}
+/**
+ * The full score: term hits plus a recency tie-break. Recency ONLY breaks
+ * ties between real matches — a fresh mtime must never rank an entry that
+ * matches no term (that would surface unrelated fresh files on any query).
+ */
+export function scoreEntry(entry, terms, now, summary) {
+    const base = baseScore(entry, terms, summary);
+    return base === 0 ? 0 : base + recencyBonus(entry.mtime, now);
+}
+/** Load the corpus from a clone directory: chapters + rules, frontmatter-parsed. */
+export function loadCorpus(cloneDir) {
+    const entries = [];
+    const summaries = new Map();
+    // rel paths mirror the REPO layout (chapters/<key>/…, rules/<key>/…) so
+    // search results are directly readable paths and project scoping is a
+    // prefix match on the second path segment.
+    const collect = (top, kind) => {
+        const root = path.join(cloneDir, top);
+        if (!fs.existsSync(root))
+            return;
+        const walk = (dir, rel) => {
+            for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+                const p = path.join(dir, e.name);
+                if (e.isDirectory()) {
+                    walk(p, rel === '' ? e.name : path.join(rel, e.name));
+                    continue;
+                }
+                if (e.name.endsWith('.md')) {
+                    const relPath = rel === '' ? e.name : path.join(rel, e.name);
+                    const text = fs.readFileSync(p, 'utf8');
+                    const entry = entryFromChapter(path.join(top, relPath), text, fs.statSync(p).mtimeMs);
+                    entries.push({ ...entry, kind });
+                    const fm = /^---[\s\S]*?summary:\s*(.*)$/m.exec(text);
+                    if (fm !== null)
+                        summaries.set(entry.path, fm[1].trim().replace(/^"|"$/g, ''));
+                    // P3: rules carry no summary field — their BODY is the scannable
+                    // surface; score terms against it like a chapter's summary
+                    else if (entry.kind === 'rule')
+                        summaries.set(entry.path, entryBody(text).slice(0, 500));
+                }
+            }
+        };
+        walk(root, '');
+    };
+    collect('chapters', 'chapter');
+    collect('rules', 'rule');
+    return { entries: stitchFragments(entries), summaries }; // S5: search sees stitched views too
+}
+/**
+ * The search itself: score, sort (score desc, then path for determinism),
+ * format lines `score | date | kind | title | path (topics: …)`, and pack
+ * lines to the requested token budget. The agent sees `total` vs `shown` so
+ * it can re-request with a larger budget — no silent truncation.
+ */
+export function searchKnowledge(cloneDir, query, maxTokens, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const terms = tokenize(query);
+    // P3 §8: rules that THIS machine approved get a small, explicit bonus —
+    // computed here (per-machine), never baked into the shared index shards.
+    let coreRuleIds = null;
+    if (opts.harnessId !== undefined && opts.rulesCoreBonus !== undefined && opts.rulesCoreBonus > 0) {
+        try {
+            coreRuleIds = new Set(collectMirrorRules(cloneDir, opts.projectKey ?? '', opts.harnessId)
+                .filter((r) => r.status === 'core').map((r) => r.relPath));
+        }
+        catch {
+            coreRuleIds = null;
+        }
+    }
+    if (terms.length === 0) {
+        return { results: [], total: 0, shown: 0, budget: { requested: maxTokens, used: 0, remaining: maxTokens }, line: '' };
+    }
+    const { entries, summaries } = loadCorpus(cloneDir);
+    const scoped = opts.projectKey !== undefined
+        ? entries.filter((e) => e.path.startsWith(`chapters/${opts.projectKey}`) || e.path.startsWith(`rules/${opts.projectKey}`))
+        : entries;
+    const scored = scoped
+        .map((e) => ({ e, score: scoreEntry(e, terms, now, summaries.get(e.path) ?? '') + (coreRuleIds !== null && e.kind === 'rule' && coreRuleIds.has(e.path) ? (opts.rulesCoreBonus ?? 0) : 0) }))
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score || (a.e.path < b.e.path ? -1 : 1));
+    const results = scored.map((s) => ({
+        score: Number(s.score.toFixed(2)),
+        date: s.e.mtime !== undefined ? new Date(s.e.mtime).toISOString().slice(0, 10) : '----',
+        kind: s.e.kind,
+        title: s.e.title,
+        path: s.e.path,
+        ...(s.e.paths !== undefined ? { paths: s.e.paths } : {}),
+        topics: s.e.topics,
+    }));
+    const lines = [];
+    let used = 0;
+    for (const r of results) {
+        const line = `${r.score.toFixed(2)} | ${r.date} | ${r.kind} | ${r.title} | ${r.path}${r.paths !== undefined && r.paths.length > 1 ? ` [+${r.paths.length - 1} stitched part(s)]` : ''}${r.topics.length > 0 ? ` (topics: ${r.topics.join(', ')})` : ''}`;
+        const cost = estimateTokens(line);
+        if (lines.length > 0 && used + cost > maxTokens)
+            break;
+        lines.push(line);
+        used += cost;
+    }
+    return {
+        results: results.slice(0, lines.length),
+        total: results.length,
+        shown: lines.length,
+        budget: { requested: maxTokens, used, remaining: Math.max(0, maxTokens - used) },
+        line: lines.join('\n'),
+    };
+}
+//# sourceMappingURL=search.js.map