@juzser/blacksmith 0.4.0 → 0.5.0

package/factory/orchestrator/dist/lessons.js

@@ -30,11 +30,12 @@ import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import picomatch from 'picomatch';
 import { isOperatorActor } from './actors.js';
+import { templateFileFor } from './agentNames.js';
 import { foldLessons } from './db/projector.js';
 import { SmithError } from './errors.js';
 import { appendEvent, readLineageEvents } from './events.js';
 import { AGENTS_DIR, lessonsReadPath } from './paths.js';
-import { FILE_SCOPED_SCOPES, isFileScopedScope, LESSON_SCOPES, parseLessons, } from './severity.js';
+import { BULLET, CONTINUATION, ENTRY_HEADING, FILE_SCOPED_SCOPES, isFileScopedScope, LESSON_SCOPES, parseLessons, SECTION_HEADING, } from './severity.js';
 import { loadTaxonomy, validateTag } from './taxonomy.js';
 export class LessonsError extends SmithError {
 }
@@ -301,8 +302,8 @@ select on. Each names its own bullet, validated against \`taxonomy.yml\`:
 At dispatch, an \`agent-role\` entry reaches only the role its \`agent_role\`
 names, and a \`case-type\` entry only a task whose \`case\` its \`case_type\`
 names. An entry in one of those scopes with **no** selector reaches NOBODY —
-it is inert, not universal, and \`smith lessons for-dispatch\` reports it as
-such. \`smith lessons raise\` refuses to mint one; the entries that predate
+it is inert, not universal, and \`bs lessons for-dispatch\` reports it as
+such. \`bs lessons raise\` refuses to mint one; the entries that predate
 the selector (D-129) are the only ones that can still be in that state.
 
 Two kinds of entry are therefore injected at dispatch and still never
@@ -388,22 +389,186 @@ function renderEntry(lesson) {
     bullets.push(renderBulletLines('statement', lesson.statement));
     return `### ${headingFor(lesson)}\n\n${bullets.join('\n')}\n`;
 }
+/**
+ * Walks a PRE-EXISTING lessons.md, salvaging every entry compileLessons()
+ * would otherwise have to overwrite from scratch. Deliberately stricter than
+ * severity.ts's parseLessons(): that parser is read-only, so silently
+ * skipping an entry it can't make sense of just leaves the same-mistake gate
+ * with one fewer rule. Here, skipping one means DELETING hand-authored
+ * content from the compiled file with no store row left to regenerate it
+ * from — so an entry under a real `## <scope>` section that doesn't parse is
+ * a hard error instead (never a silent drop), while content above the first
+ * `## <scope>` heading (this file's own header, including its illustrative
+ * fenced `### ` example) is ignored exactly as parseLessons ignores it: real
+ * entries only start once `scope` is one of severity.ts's `LESSON_SCOPES`.
+ *
+ * Line endings are normalized to `\n` before any of the above line-based
+ * regexes run: `SECTION_HEADING`/`BULLET`'s trailing `$` and `.` never match a
+ * `\r`, so on an unmodified `\r\n` file every line silently fails to match,
+ * `scope` never leaves `''`, and every entry in the file is dropped with no
+ * error at all — the exact silent-loss failure this function exists to
+ * prevent, just triggered by a different byte.
+ *
+ * A `### ` entry that carries a `lesson_id` bullet but sits under a `##`
+ * heading that is NOT one of `LESSON_SCOPES` — an unknown or misspelled
+ * section — is refused the same way an unparseable entry is, but only once a
+ * real scope section has already been seen once in the file: before that
+ * point the file is still in its own header/doc zone (the `## Schema`
+ * walkthrough, with its illustrative fenced example), which parseLessons has
+ * always ignored and must keep being ignored here too. After the first real
+ * scope section, though, a `## ` heading is no longer prose — it is a typo
+ * or a moved section, and an entry stranded under it would otherwise vanish
+ * exactly like the CRLF case above: no bucket matches, so it is never
+ * pushed, and flush()'s `heading === null` guard means it is never even
+ * counted as unparseable.
+ */
+function extractExistingLessonEntries(markdown) {
+    const lines = markdown.replace(/\r\n/g, '\n').split('\n');
+    const entries = [];
+    let scope = '';
+    let seenValidScope = false;
+    let heading = null;
+    let entryLines = [];
+    let bullets = {};
+    let lastKey = null;
+    /** Whether the entry currently being tracked sits under an unrecognized scope (see header comment). */
+    let orphan = false;
+    function flush() {
+        if (heading === null)
+            return;
+        while (entryLines.length > 0 && entryLines[entryLines.length - 1]?.trim() === '') {
+            entryLines.pop();
+        }
+        const lessonId = bullets.lesson_id;
+        const statement = bullets.statement;
+        if (orphan) {
+            if (lessonId) {
+                throw new LessonsError('lessons.entry-under-unknown-scope', `Existing lessons.md entry ${JSON.stringify(heading)} carries lesson_id ` +
+                    `${JSON.stringify(lessonId)} under "## ${scope}", which is not a recognized lesson ` +
+                    `scope (${VALID_SCOPES.join(', ')}) — refusing to compile, which would silently drop ` +
+                    'it. Fix the scope heading or remove the entry by hand, then recompile.', { scope, heading, lessonId });
+            }
+            // No lesson_id: treated like the header's own doc examples — ignored,
+            // not an error, so free-standing prose under a stray heading doesn't
+            // become a hard failure.
+            heading = null;
+            entryLines = [];
+            bullets = {};
+            lastKey = null;
+            orphan = false;
+            return;
+        }
+        if (!lessonId || !statement) {
+            throw new LessonsError('lessons.unparseable-existing-entry', `Existing lessons.md entry ${JSON.stringify(heading)} under "## ${scope}" is missing its ` +
+                `${!lessonId ? 'lesson_id' : 'statement'} bullet — refusing to compile, which would ` +
+                'silently drop it. Fix or remove the entry by hand, then recompile.', { scope, heading });
+        }
+        entries.push({ lessonId, scope, raw: `${entryLines.join('\n')}\n` });
+        heading = null;
+        entryLines = [];
+        bullets = {};
+        lastKey = null;
+        orphan = false;
+    }
+    for (const line of lines) {
+        const sectionMatch = line.match(SECTION_HEADING);
+        if (sectionMatch) {
+            flush();
+            scope = sectionMatch[1].trim();
+            if (VALID_SCOPES.includes(scope))
+                seenValidScope = true;
+            continue;
+        }
+        if (ENTRY_HEADING.test(line)) {
+            flush();
+            if (VALID_SCOPES.includes(scope)) {
+                heading = line;
+                entryLines = [line];
+                bullets = {};
+                lastKey = null;
+                orphan = false;
+            }
+            else if (seenValidScope) {
+                heading = line;
+                entryLines = [line];
+                bullets = {};
+                lastKey = null;
+                orphan = true;
+            }
+            continue;
+        }
+        if (heading === null)
+            continue;
+        entryLines.push(line);
+        const bulletMatch = line.match(BULLET);
+        if (bulletMatch) {
+            const key = bulletMatch[1];
+            bullets[key] = bulletMatch[2].trim();
+            lastKey = key;
+            continue;
+        }
+        if (line.trim() === '') {
+            lastKey = null;
+            continue;
+        }
+        const continuationMatch = line.match(CONTINUATION);
+        if (continuationMatch && lastKey) {
+            const existingValue = bullets[lastKey] ?? '';
+            bullets[lastKey] = `${existingValue} ${continuationMatch[1].trim()}`.trim();
+        }
+    }
+    flush();
+    return entries;
+}
+/**
+ * Which pre-existing entries a compile of `lessons` against `existingMarkdown`
+ * would preserve — the same set compileLessons() itself splices in, exposed
+ * so a caller (the CLI's `lessons compile` handler) can report how many
+ * survived without re-deriving the "now store-tracked, so the fresh render
+ * wins" filter a second time and risking the two counts drifting apart.
+ */
+export function lessonsToPreserve(lessons, existingMarkdown) {
+    if (existingMarkdown === undefined)
+        return [];
+    const knownIds = new Set(lessons.map((l) => l.lessonId));
+    return extractExistingLessonEntries(existingMarkdown).filter((entry) => !knownIds.has(entry.lessonId));
+}
 /**
  * Regenerates the full factory/policies/lessons.md content from a list of
  * APPROVED lessons. Round-trips through severity.ts's parseLessons(): every
  * entry here that carries a `finding_category` + `statement` (claim-path or
  * stack-wide scoped) survives the parse back into a `LessonRule`.
+ *
+ * `existingMarkdown`, when given, is the compiled file's own PRIOR content
+ * (e.g. read from `--out` before overwriting it). Compiling `lessons` alone
+ * loses every entry lessons.md carries that has no row in the store — a hand
+ * lesson raised before the store existed, or one `smith lessons raise` never
+ * touched — because this function only ever knew how to build the file from
+ * scratch. With `existingMarkdown`, any such entry (its `lesson_id` absent
+ * from `lessons`) is preserved verbatim instead of dropped; an entry whose id
+ * DOES appear in `lessons` is regenerated fresh from the store, same as
+ * before — the store stays the one source of truth for anything it tracks.
+ * Compiling the real repo file against the current store this way is
+ * insertions-only: nothing already there disappears.
  */
-export function compileLessons(lessons) {
+export function compileLessons(lessons, existingMarkdown) {
     const bySection = new Map(VALID_SCOPES.map((s) => [s, []]));
     for (const lesson of lessons) {
         const bucket = bySection.get(lesson.lessonScope);
         if (bucket)
             bucket.push(lesson);
     }
+    const preservedBySection = new Map(VALID_SCOPES.map((s) => [s, []]));
+    for (const entry of lessonsToPreserve(lessons, existingMarkdown)) {
+        const bucket = preservedBySection.get(entry.scope);
+        if (bucket)
+            bucket.push(entry.raw);
+    }
     const sections = VALID_SCOPES.map((scope) => {
-        const entries = bySection.get(scope) ?? [];
-        const body = entries.length === 0 ? '_(none yet)_\n' : entries.map(renderEntry).join('\n');
+        const freshBlocks = (bySection.get(scope) ?? []).map(renderEntry);
+        const keptBlocks = preservedBySection.get(scope) ?? [];
+        const blocks = [...keptBlocks, ...freshBlocks];
+        const body = blocks.length === 0 ? '_(none yet)_\n' : blocks.join('\n');
         return `## ${scope}\n\n${body}`;
     });
     return `${LESSONS_MD_HEADER}\n${sections.join('\n')}`;
@@ -494,7 +659,7 @@ export function scopesForRole(role, opts = {}) {
     if (!ROLE_NAME.test(role)) {
         throw new LessonsError('lessons.invalid-role-name', `Not a role name: ${JSON.stringify(role)} (expected e.g. "coder", "security-reviewer").`, { role });
     }
-    const templatePath = path.join(opts.agentsDir ?? AGENTS_DIR, `${role}.md`);
+    const templatePath = path.join(opts.agentsDir ?? AGENTS_DIR, templateFileFor(role));
     let template;
     try {
         template = readFileSync(templatePath, 'utf8');
@@ -506,13 +671,13 @@ export function scopesForRole(role, opts = {}) {
     for (const match of template.matchAll(SCOPE_MARKER)) {
         const scope = match[1];
         if (!VALID_SCOPES.includes(scope)) {
-            throw new LessonsError('lessons.unknown-lesson-scope', `${role}.md declares lesson scope "${scope}", which is not one of: ${VALID_SCOPES.join(', ')}.`, { role, scope, templatePath });
+            throw new LessonsError('lessons.unknown-lesson-scope', `${templateFileFor(role)} declares lesson scope "${scope}", which is not one of: ${VALID_SCOPES.join(', ')}.`, { role, scope, templatePath });
         }
         if (!scopes.includes(scope))
             scopes.push(scope);
     }
     if (scopes.length === 0) {
-        throw new LessonsError('lessons.role-template-has-no-scope-marker', `${role}.md carries no <!-- LESSONS:<scope> --> marker, so no lesson can reach it.`, { role, templatePath });
+        throw new LessonsError('lessons.role-template-has-no-scope-marker', `${templateFileFor(role)} carries no <!-- LESSONS:<scope> --> marker, so no lesson can reach it.`, { role, templatePath });
     }
     return scopes;
 }
@@ -594,7 +759,7 @@ export function lessonsForDispatch(role, claimPaths, opts = {}) {
         markdown = readFileSync(lessonsPath, 'utf8');
     }
     catch {
-        throw new LessonsError('lessons.compiled-file-not-found', `No compiled lessons at ${lessonsPath} — run \`smith lessons compile\`.`, { role, lessonsPath });
+        throw new LessonsError('lessons.compiled-file-not-found', `No compiled lessons at ${lessonsPath} — run \`bs lessons compile\`.`, { role, lessonsPath });
     }
     // A mistyped case would otherwise match no entry and emit no warning — a
     // silent empty injection, the exact failure D-129 is about. The role needs
@@ -877,6 +1042,17 @@ export async function dream(events, ctx, opts = {}, options = {}) {
             noveltyRejected.push(lessonId);
         }
     }
+    // DS8 plan §2.3 -- a durable mark that a pass happened, even one that
+    // raised nothing, so the Lessons page can show when lessons were last
+    // checked rather than only when one was last raised.
+    await appendEvent({
+        session_id: ctx.sessionId,
+        actor: ctx.actor ?? 'system',
+        event_type: 'lessons-pass-completed',
+        plan_version: ctx.planVersion,
+        causal_parent: parent,
+        payload: { raised: raised.length },
+    }, opts);
     return {
         checkpointsExtracted: checkpoints.length,
         raised,
@@ -1111,8 +1287,9 @@ export async function raiseLessonCandidate(input, ctx, opts = {}, options = {})
             ...(contradictionOf ? { possible_contradiction_of: contradictionOf } : {}),
         },
     }, opts);
+    let lastEventId = raisedEvent.event_id;
     if (!novelty.novel) {
-        await appendEvent({
+        const rejectedEvent = await appendEvent({
             session_id: ctx.sessionId,
             actor: 'system',
             event_type: 'lesson-status-changed',
@@ -1120,6 +1297,7 @@ export async function raiseLessonCandidate(input, ctx, opts = {}, options = {})
             causal_parent: raisedEvent.event_id,
             payload: { lesson_id: lessonId, from_status: 'candidate', to_status: 'novelty-rejected' },
         }, opts);
+        lastEventId = rejectedEvent.event_id;
     }
     return {
         lessonId,
@@ -1128,6 +1306,7 @@ export async function raiseLessonCandidate(input, ctx, opts = {}, options = {})
         mostSimilar: novelty.mostSimilar,
         possibleContradictionOf: contradictionOf,
         warnings,
+        event_id: lastEventId,
     };
 }
 // ---------------------------------------------------------------------------

package/factory/orchestrator/dist/mcp.js

@@ -260,7 +260,7 @@ export function addMcpSurface(opts) {
     const targetDir = opts.targetDir ?? path.join(opts.projectsDir ?? PROJECTS_DIR, opts.projectName);
     const manifestPath = path.join(targetDir, 'mcp.manifest.json');
     if (!existsSync(path.join(targetDir, 'package.json'))) {
-        throw new McpError('mcp.unknown-project', `${targetDir} is not a scaffolded project (no package.json). Run \`smith new ${opts.projectName}\` first.`, { targetDir, projectName: opts.projectName });
+        throw new McpError('mcp.unknown-project', `${targetDir} is not a scaffolded project (no package.json). Run \`bs new ${opts.projectName}\` first.`, { targetDir, projectName: opts.projectName });
     }
     if (existsSync(manifestPath)) {
         throw new McpError('mcp.surface-exists', `${manifestPath} already exists. Edit the manifest in place; re-scaffolding would discard declared tools and their operator sign-off.`, { manifestPath, projectName: opts.projectName });
@@ -314,7 +314,7 @@ export function registerMcpMilestone(projectName, roadmapPath = ensureWritableRo
         // in the roadmap itself which epic closes the milestone, the way
         // envkit-config-loader already does, instead of leaving it to convention.
         `- epics: [${id}]\n` +
-        '- goal: Declare and harden the MCP surface — `smith mcp check` green against ' +
+        '- goal: Declare and harden the MCP surface — `bs mcp check` green against ' +
         'docs/standards/mcp.md. Required before the final milestone can close.\n';
     writeFileSync(roadmapPath, `${text.trimEnd()}\n${block}`, 'utf8');
     return id;
@@ -339,7 +339,7 @@ export function checkRoadmapMcpMilestone(project, milestones) {
             {
                 rule: 'MCP-M1',
                 path: `/milestones/${project}`,
-                message: `Project "${project}" has no \`${project}-${MCP_MILESTONE_SUFFIX}\` milestone. Run \`smith mcp init ${project}\` to register it.`,
+                message: `Project "${project}" has no \`${project}-${MCP_MILESTONE_SUFFIX}\` milestone. Run \`bs mcp init ${project}\` to register it.`,
             },
         ];
     }
@@ -453,7 +453,7 @@ export function runMcpCheck(opts) {
     const manifestPath = path.join(targetDir, MANIFEST_NAME);
     const roadmapPath = opts.roadmapPath ?? roadmapReadPath();
     if (!existsSync(manifestPath)) {
-        throw new McpError('mcp.no-surface', `${manifestPath} does not exist. Run \`smith mcp init ${opts.projectName}\` before checking the surface.`, { manifestPath, projectName: opts.projectName });
+        throw new McpError('mcp.no-surface', `${manifestPath} does not exist. Run \`bs mcp init ${opts.projectName}\` before checking the surface.`, { manifestPath, projectName: opts.projectName });
     }
     let manifest;
     try {
@@ -548,8 +548,8 @@ export function mcpBlockers(epicId, status) {
     if (!status.check) {
         return [
             status.problem === 'unreadable'
-                ? `epic ${epicId} is under milestone ${milestone} but its MCP surface at ${manifest} exists and could not be read, so no verdict could be rendered — fix the manifest in place and run \`smith mcp check\` for the parser's own message. Do not re-run \`smith mcp init\`: it refuses over an existing manifest, because re-scaffolding would discard the declared tools and their operator sign-off.`
-                : `epic ${epicId} is under milestone ${milestone} but has no MCP surface at ${manifest} — run \`smith mcp init\` and declare it.`,
+                ? `epic ${epicId} is under milestone ${milestone} but its MCP surface at ${manifest} exists and could not be read, so no verdict could be rendered — fix the manifest in place and run \`bs mcp check\` for the parser's own message. Do not re-run \`bs mcp init\`: it refuses over an existing manifest, because re-scaffolding would discard the declared tools and their operator sign-off.`
+                : `epic ${epicId} is under milestone ${milestone} but has no MCP surface at ${manifest} — run \`bs mcp init\` and declare it.`,
         ];
     }
     return status.check.violations.map((v) => `mcp surface ${milestone}: ${v.rule} at ${v.path} — ${v.message}`);

package/factory/orchestrator/dist/paths.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { readEnv } from './env.js';
 // factory/orchestrator/src/paths.ts -> repo root is three levels up.
 const here = path.dirname(fileURLToPath(import.meta.url));
 /**
@@ -29,7 +30,7 @@ export function isFactoryCheckout(dir) {
  * `package.json#files` could not ship it if it tried. A linked worktree spells
  * it as a file rather than a directory, which `existsSync` reads either way.
  */
-const IS_CLONE = existsSync(path.join(REPO_ROOT, '.git'));
+export const IS_CLONE = existsSync(path.join(REPO_ROOT, '.git'));
 /**
  * Where the work root goes when the CLI is not standing in a clone.
  *
@@ -46,9 +47,10 @@ const WORK_DIR_NAME = '.blacksmith';
  *
  * Pure, and exported for the test: the constants below call it once at module
  * load, but the install case can only be stated by a test that passes its own
- * roots in. `env.SMITH_HOME` wins outright; otherwise a clone keeps writing
- * into itself, and an install writes beside the operator instead of into
- * `node_modules/@juzser/blacksmith`, which the next `npm i` replaces wholesale.
+ * roots in. `BS_HOME` (or its legacy `SMITH_HOME` fallback) wins outright;
+ * otherwise a clone keeps writing into itself, and an install writes beside
+ * the operator instead of into `node_modules/@juzser/blacksmith`, which the
+ * next `npm i` replaces wholesale.
  *
  * The layout *under* the root is identical in both cases on purpose. A path
  * like `state/events/<session>.jsonl` is spelled in runbooks, in agent
@@ -56,9 +58,10 @@ const WORK_DIR_NAME = '.blacksmith';
  * if only the anchor moves.
  */
 export function resolveWorkRoot(repoRoot, cwd, env, isClone) {
-    const declared = env.SMITH_HOME?.trim();
-    // An empty `SMITH_HOME=` is how an unset variable gets spelled by accident in
-    // a shell profile or a CI matrix; resolved literally it would mean cwd.
+    const declared = readEnv(env, 'BS_HOME')?.trim();
+    // An empty `BS_HOME=`/`SMITH_HOME=` is how an unset variable gets spelled by
+    // accident in a shell profile or a CI matrix; resolved literally it would
+    // mean cwd.
     if (declared)
         return path.resolve(cwd, declared);
     return isClone ? repoRoot : path.join(cwd, WORK_DIR_NAME);