@nusoft/nuos-build-catalogue 0.11.0 → 0.14.0

package/dist/cli.js

@@ -10,8 +10,6 @@
  * Implementation note — uses minimist-free arg parsing to keep deps lean.
  * If we need richer parsing later, swap in commander/yargs.
  */
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 // Static imports — these don't pull in NuVector / NuFlow transitively.
 // init / migrate / regenerate / summary / list / show / install-protocols all
 // work without those native deps being installed.
@@ -21,28 +19,7 @@ import { listRegister, showRecord, commandToRegister, listAcrossRegisters, } fro
 import { runRegenerate } from './regenerate/check.js';
 import { openPrompt } from './commands/prompt.js';
 import { cmdInit, cmdInstallProtocols } from './commands/init.js';
-// Dynamic imports below — index / search / write commands / create commands
-// load NuVector or NuFlow transitively. Loading them at module-parse time
-// would crash on platforms where the NuVector native binary isn't resolved
-// (e.g. fresh npx installs before @nusoft/nuvector ships its platform-specific
-// binaries as optionalDependencies). Lazy-load so the lightweight commands
-// (init, migrate, etc.) work universally; the heavyweight commands degrade
-// gracefully when their deps are missing.
-const __filename = fileURLToPath(import.meta.url);
-const PACKAGE_ROOT = path.resolve(path.dirname(__filename), '..');
-// Defaults resolve in this order: env var > flag-supplied > package-relative
-// fallback. The package-relative fallback only makes sense when running
-// against the nuos catalogue as a sibling (the original WU 110 use case);
-// for any other consumer (Sensight, NuTutor, etc.) the env vars or the
-// per-command flags are the right path. CLAUDE.md guidance for adopters:
-// set NUOS_CATALOGUE_BUILD_ROOT and NUOS_CATALOGUE_WORKFLOWS in your
-// shell profile.
-const DEFAULT_CATALOGUE_ROOT = process.env.NUOS_CATALOGUE_ROOT ?? path.resolve(PACKAGE_ROOT, '../nuos/docs');
-const DEFAULT_BUILD_ROOT = process.env.NUOS_CATALOGUE_BUILD_ROOT ?? path.resolve(PACKAGE_ROOT, '../nuos/docs/build');
-const DEFAULT_INDEX_DIR = process.env.NUOS_CATALOGUE_INDEX_DIR ?? path.resolve(PACKAGE_ROOT, '.nuos-catalogue');
-const DEFAULT_INDEX_PATH = path.join(DEFAULT_INDEX_DIR, 'index.nv');
-const DEFAULT_HASH_PATH = path.join(DEFAULT_INDEX_DIR, 'hashes.json');
-const DEFAULT_WORKFLOWS_PATH = process.env.NUOS_CATALOGUE_WORKFLOWS ?? path.join(DEFAULT_INDEX_DIR, 'workflows.json');
+import { resolveBuildRoot, resolveCatalogueRoot, resolveWorkflowsPath, resolveIndexPath, resolveHashPath, gitignoreCatalogueNote, } from './path-resolution.js';
 function parseArgs(argv) {
     const [command, ...rest] = argv;
     const positional = [];
@@ -64,9 +41,10 @@ function parseArgs(argv) {
     return { command: command ?? 'help', positional, flags };
 }
 async function cmdIndex(flags) {
-    const catalogueRoot = String(flags['catalogue'] ?? DEFAULT_CATALOGUE_ROOT);
-    const indexPath = String(flags['index'] ?? DEFAULT_INDEX_PATH);
-    const hashPath = String(flags['hash-file'] ?? DEFAULT_HASH_PATH);
+    const catalogueRoot = resolveCatalogueRoot(flags['catalogue']);
+    const buildRoot = resolveBuildRoot(flags['build-root']);
+    const indexPath = resolveIndexPath(buildRoot, flags['index']);
+    const hashPath = resolveHashPath(buildRoot, flags['hash-file']);
     const { selectEmbedderFromEnv } = await import('./embedder/select.js');
     const { openStore } = await import('./store/open.js');
     const { runIndex } = await import('./indexer/upsert.js');
@@ -99,7 +77,8 @@ async function cmdSearch(positional, flags) {
         console.error('Usage: nuos-catalogue search "<query>" [--kind=...] [--status=...] [--limit=N] [--json]');
         process.exit(2);
     }
-    const indexPath = String(flags['index'] ?? DEFAULT_INDEX_PATH);
+    const buildRoot = resolveBuildRoot(flags['build-root']);
+    const indexPath = resolveIndexPath(buildRoot, flags['index']);
     const { selectEmbedderFromEnv } = await import('./embedder/select.js');
     const { openStore } = await import('./store/open.js');
     const { runSearch } = await import('./search/query.js');
@@ -132,8 +111,8 @@ async function cmdSearch(positional, flags) {
     }
 }
 async function cmdMigrate(flags) {
-    const buildRoot = String(flags['build-root'] ?? DEFAULT_BUILD_ROOT);
-    const workflowsPath = String(flags['workflows'] ?? DEFAULT_WORKFLOWS_PATH);
+    const buildRoot = resolveBuildRoot(flags['build-root']);
+    const workflowsPath = resolveWorkflowsPath(buildRoot, flags['workflows']);
     const dryRun = Boolean(flags['dry-run']);
     console.log(`migrating ${buildRoot}`);
     console.log(`  workflows file: ${workflowsPath}`);
@@ -161,6 +140,17 @@ async function cmdMigrate(flags) {
         console.log('     Resolve by renaming the conflicting files (e.g. give them distinct number prefixes) then re-run migrate.');
     }
     console.log(`(${(report.durationMs / 1000).toFixed(2)}s)`);
+    // Surface a gitignore hint if the project's .gitignore is missing the
+    // `.nuos-catalogue/` entry. Silent if .gitignore is absent or correct.
+    // (We do this after the success block so the report is the first thing
+    // the operator reads; the note follows.)
+    if (!dryRun) {
+        const note = gitignoreCatalogueNote(buildRoot);
+        if (note) {
+            console.log('');
+            console.log(note);
+        }
+    }
 }
 async function cmdRegisterDispatch(command, positional, flags) {
     const register = commandToRegister(command);
@@ -169,8 +159,8 @@ async function cmdRegisterDispatch(command, positional, flags) {
         process.exit(2);
     }
     const action = positional[0];
-    const workflowsPath = String(flags['workflows'] ?? DEFAULT_WORKFLOWS_PATH);
-    const buildRoot = String(flags['build-root'] ?? DEFAULT_BUILD_ROOT);
+    const buildRoot = resolveBuildRoot(flags['build-root']);
+    const workflowsPath = resolveWorkflowsPath(buildRoot, flags['workflows']);
     const store = await openWorkflowStore(workflowsPath);
     const asJson = Boolean(flags['json']);
     switch (action) {
@@ -300,8 +290,8 @@ async function cmdRegisterDispatch(command, positional, flags) {
     }
 }
 async function cmdRegenerate(flags) {
-    const buildRoot = String(flags['build-root'] ?? DEFAULT_BUILD_ROOT);
-    const workflowsPath = String(flags['workflows'] ?? DEFAULT_WORKFLOWS_PATH);
+    const buildRoot = resolveBuildRoot(flags['build-root']);
+    const workflowsPath = resolveWorkflowsPath(buildRoot, flags['workflows']);
     const write = Boolean(flags['write']);
     const showDiffs = Boolean(flags['diff']);
     const registerFilter = flags['register'] ? String(flags['register']) : undefined;
@@ -353,7 +343,8 @@ async function cmdRegenerate(flags) {
     process.exit(report.differs > 0 || report.missing > 0 ? 1 : 0);
 }
 async function cmdSummary(flags) {
-    const workflowsPath = String(flags['workflows'] ?? DEFAULT_WORKFLOWS_PATH);
+    const buildRoot = resolveBuildRoot(flags['build-root']);
+    const workflowsPath = resolveWorkflowsPath(buildRoot, flags['workflows']);
     const store = await openWorkflowStore(workflowsPath);
     const { byRegister, total } = listAcrossRegisters(store);
     if (Boolean(flags['json'])) {
@@ -387,6 +378,7 @@ Usage:
   nuos-catalogue wu        create    (interactive — multi-step prompts)
   nuos-catalogue wu        advance   <handle> --to=<status> [--reason="..."]
   nuos-catalogue wu        tick      <handle> --index=N --evidence="..."
+                          (--index is 1-based: --index=1 ticks the first AC)
   nuos-catalogue decision  list      [--status=<s>] [--limit=N] [--json]
   nuos-catalogue decision  show      <handle> [--json]
   nuos-catalogue decision  create    (interactive)
@@ -399,17 +391,25 @@ Usage:
   nuos-catalogue persona   show      <handle> [--json]
   nuos-catalogue persona   create    (interactive — seven dimensions + acid-test per D046)
 
+  nuos-catalogue plan      status    show planning progress across the 5-phase arc
+
   nuos-catalogue help
 
 Handles accepted: canonical (wu-111, D046, Q009, P001) or friendly
 (WU 111, 111, D45, Q9). Unambiguous integers ("111" under "wu show")
 are normalised to the canonical form.
 
+Default locations: when --build-root / --workflows / --catalogue are
+omitted and the matching env vars are unset, the CLI walks up from the
+current working directory looking for a docs/build/ directory (the
+same way git finds its repo root). Invoke from anywhere inside the
+project. The workflow store lives at <project-root>/.nuos-catalogue/.
+
 Environment:
-  NUOS_CATALOGUE_BUILD_ROOT   default for --build-root (the catalogue's docs/build/ dir)
-  NUOS_CATALOGUE_WORKFLOWS    default for --workflows (the JSON workflow store path)
-  NUOS_CATALOGUE_ROOT         default for --catalogue (semantic-search index source)
-  NUOS_CATALOGUE_INDEX_DIR    default parent dir for index.nv + workflows.json
+  NUOS_CATALOGUE_BUILD_ROOT   override for --build-root (the catalogue's docs/build/ dir)
+  NUOS_CATALOGUE_WORKFLOWS    override for --workflows (the JSON workflow store path)
+  NUOS_CATALOGUE_ROOT         override for --catalogue (semantic-search index source)
+  NUOS_CATALOGUE_INDEX_DIR    override for parent dir of index.nv + workflows.json
   NUOS_CATALOGUE_EMBEDDER     vertex | openai | stub  (default: vertex)
   GOOGLE_CLOUD_PROJECT        required for vertex
   GOOGLE_CLOUD_LOCATION       optional (default: us-central1)
@@ -473,6 +473,19 @@ async function main() {
         case 'persona':
             await cmdRegisterDispatch(args.command, args.positional, args.flags);
             break;
+        case 'plan': {
+            const sub = args.positional[0];
+            if (sub === 'status') {
+                const { cmdPlanStatus } = await import('./commands/plan.js');
+                const code = await cmdPlanStatus({ cwd: process.cwd() });
+                if (code !== 0)
+                    process.exit(code);
+                break;
+            }
+            console.error(`unknown plan subcommand: ${sub ?? '(none)'}`);
+            console.error('available: plan status');
+            process.exit(1);
+        }
         case 'help':
         case '--help':
         case '-h':

package/dist/commands/init.js

@@ -39,6 +39,7 @@ const PROTOCOL_FILES = [
     'end-of-session.md',
     'wu-new.md',
     'persona-new.md',
+    'plan-orientation.md',
 ];
 /**
  * One-line descriptions used in the frontmatter of installed protocol
@@ -46,10 +47,11 @@ const PROTOCOL_FILES = [
  * read as an imperative summary.
  */
 const PROTOCOL_DESCRIPTIONS = {
-    'start-of-session': 'Read STATE, last session log, active WU; surface next action',
-    'end-of-session': 'Write session log, update STATE + indices, move ✅ WUs to done/, commit',
-    'wu-new': 'Create a new work unit with the six-field outcome shape (per D046)',
-    'persona-new': 'Create a new P-NNN persona with the seven dimensions and acid-test (per D046)',
+    'start-of-session': 'Read where the project is and propose the next concrete action',
+    'end-of-session': 'Capture what happened, update state, write session log, commit',
+    'wu-new': 'File a new work unit through a guided plain-English conversation',
+    'persona-new': 'File a new persona by walking the seven dimensions conversationally',
+    'plan-orientation': 'Phase A of planning — project description, personas, the horizon map',
 };
 const TOOLS = {
     claude: {
@@ -165,6 +167,12 @@ export async function cmdInit(prompt, options = {}) {
             log_line(`  · ${existed ? 'overwrote' : 'installed'} ${tool.destPath(slug)} (${tool.label})`);
         }
     }
+    // Step 3b: install the git hooks (pre-commit enforcement + post-commit
+    // auto-reindex). Two source files land in scripts/hooks/ so the consumer
+    // has the version-controlled source-of-truth; copies are pushed into
+    // .git/hooks/ so they fire immediately without the user re-running an
+    // installer.
+    await installHooks(cwd, log_line);
     // Step 4: CLAUDE.md
     const claudeMdPath = path.join(cwd, 'CLAUDE.md');
     const catalogueSection = renderCatalogueSection(name);
@@ -190,14 +198,24 @@ export async function cmdInit(prompt, options = {}) {
     prompt.print('');
     prompt.print(`✅ Catalogue initialised at ${path.join(cwd, 'docs/build')}`);
     prompt.print('');
-    prompt.print('Next steps:');
-    prompt.print('  1. Set env vars in your shell profile so the CLI knows where this catalogue lives:');
-    prompt.print(`       export NUOS_CATALOGUE_BUILD_ROOT="${path.join(cwd, 'docs/build')}"`);
-    prompt.print(`       export NUOS_CATALOGUE_WORKFLOWS="${path.join(cwd, '.nuos-catalogue/workflows.json')}"`);
-    prompt.print('  2. Edit docs/build/STATE.md to describe the actual current state of this project.');
-    prompt.print('  3. File the first WU: `nuos-catalogue wu create`');
+    prompt.print('Next step:');
+    prompt.print('  Run `/start-of-session` in Claude Code (or OpenCode, or Codex CLI).');
+    prompt.print('  The AI will detect this is a brand-new catalogue and walk you');
+    prompt.print('  through a 5-phase planning arc:');
     prompt.print('');
-    prompt.print('To refresh protocols only later (without re-running init): `nuos-catalogue install-protocols`');
+    prompt.print('    A. Orientation        — project description, personas, the horizon  (~30 min)');
+    prompt.print('    B. Architecture       — major pieces and their contracts            (~60-90 min)');
+    prompt.print('    C. UI/UX + Design     — surfaces and the design system              (~60-90 min)');
+    prompt.print('    D. Maps               — phases of work and near-term plan           (~45 min)');
+    prompt.print('    E. Initial work units — first 5-10 things to build                  (~60 min)');
+    prompt.print('');
+    prompt.print('  Each phase is its own session. Pause whenever you want.');
+    prompt.print('');
+    prompt.print('To read about the catalogue before starting:');
+    prompt.print(`  ${path.join(cwd, 'docs/build/WELCOME.md')}`);
+    prompt.print(`  ${path.join(cwd, 'docs/build/GLOSSARY.md')}`);
+    prompt.print('');
+    prompt.print('To refresh protocols and hooks later: `nuos-catalogue install-protocols`');
     return { output: '', exitCode: 0 };
 }
 export async function cmdInstallProtocols(prompt, options = {}) {
@@ -230,9 +248,76 @@ export async function cmdInstallProtocols(prompt, options = {}) {
     prompt.print(`Refreshing protocols (Claude Code / OpenCode / Codex CLI):`);
     for (const l of lines)
         prompt.print(l);
+    // Refresh hooks too — same idempotent shape.
+    prompt.print('');
+    prompt.print(`Refreshing git hooks (pre-commit enforcement, post-commit auto-reindex):`);
+    await installHooks(cwd, (msg) => prompt.print(msg));
     return { output: '', exitCode: 0 };
 }
 // ---------------------------------------------------------------------------
+// installHooks — copy bundled hook sources into the consumer + activate them
+// ---------------------------------------------------------------------------
+/**
+ * Bundled hooks ship in templates/hooks/. Two source files (pre-commit,
+ * post-commit) land in the consumer's scripts/hooks/ so the maintainer
+ * has the version-controlled source. Copies also land in .git/hooks/ so
+ * they fire immediately. The bash install-hooks.sh script also lands in
+ * scripts/ so re-running it after a fresh clone reconstitutes .git/hooks/.
+ *
+ * Idempotent: byte-identical sources are skipped silently. Permissions
+ * are set executable on every install so a chmod isn't required.
+ */
+async function installHooks(cwd, log_line) {
+    const hooksTemplatesRoot = path.join(TEMPLATES_ROOT, 'hooks');
+    if (!existsSync(hooksTemplatesRoot)) {
+        log_line('  · (hooks bundle not present in this CLI install — skipping)');
+        return;
+    }
+    // 1) Source-of-truth files in <cwd>/scripts/
+    const scriptsDir = path.join(cwd, 'scripts');
+    const scriptsHooksDir = path.join(scriptsDir, 'hooks');
+    await mkdir(scriptsHooksDir, { recursive: true });
+    const hookFiles = ['pre-commit', 'post-commit'];
+    for (const name of hookFiles) {
+        const src = path.join(hooksTemplatesRoot, name);
+        const dest = path.join(scriptsHooksDir, name);
+        await writeHookFile(src, dest, log_line, `  · `, `scripts/hooks/${name}`);
+    }
+    // install-hooks.sh — convenience bash installer; sits next to scripts/hooks/
+    const installerSrc = path.join(hooksTemplatesRoot, 'install-hooks.sh');
+    const installerDest = path.join(scriptsDir, 'install-hooks.sh');
+    await writeHookFile(installerSrc, installerDest, log_line, `  · `, `scripts/install-hooks.sh`);
+    // 2) Active copies in <cwd>/.git/hooks/ — only if .git/ exists. Some
+    // tests run init in a non-git directory; that's fine, skip the active
+    // install and let the user run install-hooks.sh later.
+    const gitHooksDir = path.join(cwd, '.git', 'hooks');
+    if (!existsSync(path.join(cwd, '.git'))) {
+        log_line(`  · (no .git/ found at ${cwd} — skipping active hook install; run scripts/install-hooks.sh after \`git init\`)`);
+        return;
+    }
+    await mkdir(gitHooksDir, { recursive: true });
+    for (const name of hookFiles) {
+        const src = path.join(hooksTemplatesRoot, name);
+        const dest = path.join(gitHooksDir, name);
+        await writeHookFile(src, dest, log_line, `  · `, `.git/hooks/${name}`);
+    }
+}
+async function writeHookFile(src, dest, log_line, prefix, label) {
+    const srcContent = await readFile(src, 'utf8');
+    let action = 'created';
+    if (existsSync(dest)) {
+        const destContent = await readFile(dest, 'utf8');
+        action = destContent === srcContent ? 'unchanged' : 'updated';
+    }
+    if (action !== 'unchanged') {
+        await writeFile(dest, srcContent, 'utf8');
+    }
+    // chmod +x — required for git to actually run them
+    const { chmod } = await import('node:fs/promises');
+    await chmod(dest, 0o755);
+    log_line(`${prefix}${action} ${label}`);
+}
+// ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 function substitute(content, subs) {
@@ -291,48 +376,40 @@ async function ensureGitignoreEntries(gitignorePath, log_line) {
 function renderCatalogueSection(projectName) {
     return `## Build catalogue (NuOS Build Method)
 
-This repo runs **the NuOS Build Method**. The catalogue lives at [docs/build/](docs/build/) and tracks work units, decisions, open questions, personas, sessions, and risks.
+This project uses the **NuOS Build Method catalogue** at [docs/build/](docs/build/). It is the project's memory — who it's for, what's been built, what's been decided, what's still unknown, what's at risk. Eleven registers in plain Markdown. The catalogue stays current through two protocols that bookend every session.
 
-### At the start of every session
+**Start here** if you're new:
 
-Run \`/start-of-session\` (or follow [docs/build/START-OF-SESSION.md](docs/build/START-OF-SESSION.md)).
+- [docs/build/WELCOME.md](docs/build/WELCOME.md) — what this catalogue is, in 5 minutes
+- [docs/build/GLOSSARY.md](docs/build/GLOSSARY.md) — every term defined once
 
-### At the end of every session
+### Three commands
 
-Run \`/end-of-session\`. **Without it, work is lost.**
+That's it. Everything else is automatic.
 
-### Daily use via the CLI
-
-Set these env vars in your shell profile so commands work without flags:
-
-\`\`\`bash
-export NUOS_CATALOGUE_BUILD_ROOT="$(pwd)/docs/build"
-export NUOS_CATALOGUE_WORKFLOWS="$(pwd)/.nuos-catalogue/workflows.json"
+\`\`\`text
+/start-of-session       — every time you begin working
+/end-of-session         — every time you stop
 \`\`\`
 
-Then:
+(\`init\` runs once at the start; you've already done that.)
 
-\`\`\`bash
-nuos-catalogue wu create                          # interactive — file a new WU
-nuos-catalogue wu list                            # what's in flight
-nuos-catalogue wu advance <handle> --to=in_progress
-nuos-catalogue wu tick <handle> --index=N --evidence="commit abc123"
-nuos-catalogue decision create
-nuos-catalogue question create
-nuos-catalogue regenerate                         # check store-vs-disk drift
-nuos-catalogue summary                            # totals by register
-\`\`\`
+If this is a brand-new project, \`/start-of-session\` will detect the empty catalogue and walk you through 5 short planning phases (Orientation, Architecture, UI/UX + Design System, Maps, Initial Work Units) before any building starts. Each phase is its own session. Take them in order; pause whenever you need to.
 
-To refresh the protocol bodies later (after a CLI upgrade):
+### The principle that makes it work
 
-\`\`\`bash
-nuos-catalogue install-protocols
-\`\`\`
+**Project memory never drifts from project reality.** Every decision made in conversation gets saved before the session ends. Every change to an existing piece flows through a protocol. The pre-commit hook blocks silent edits to accepted decisions; the post-commit hook auto-refreshes the search index after every commit. What the AI finds when you ask "what did we decide about X?" is always current.
 
 ### What never to do
 
-- Never make architectural decisions without recording them in \`docs/build/decisions/\`
-- Never start work outside the active work unit without recording why
-- Never skip end-of-session
-- Never modify a committed \`accepted\` decision file (use \`decision supersede\` instead)`;
+- **Never close a session without \`/end-of-session\`.** Work that isn't written down is work that's lost.
+- **Never edit an accepted decision file.** If something changes, file a new decision that supersedes the old one. The pre-commit hook will block silent edits.
+- **Never make an architectural decision in conversation without filing it.** If you and the AI agree on "let's go with X", file it as a decision *before moving on*. Drift is the failure mode that makes the catalogue worthless.
+
+### If you need more
+
+- All registers and their templates live under [docs/build/](docs/build/)
+- The full CLI surface (creating work units / decisions / personas / questions / contracts / surfaces from the command line) is documented at [docs/build/WELCOME.md](docs/build/WELCOME.md)
+- To refresh protocols and hooks later (after a CLI upgrade): \`npx @nusoft/nuos-build-catalogue install-protocols\`
+`;
 }

package/dist/commands/plan.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `nuos-catalogue plan status` — read methodfile.json's planning tracker
+ * and print a 5-line summary of where the project is in the planning arc.
+ *
+ * Read-only; never mutates state. The actual phase advancement is done by
+ * the relevant plan-* protocol when it finishes its work and updates the
+ * methodfile + STATE.md as part of its end-of-session.
+ */
+export interface PlanStatusOptions {
+    cwd?: string;
+}
+export declare function cmdPlanStatus(options?: PlanStatusOptions): Promise<number>;

package/dist/commands/plan.js

@@ -0,0 +1,83 @@
+/**
+ * `nuos-catalogue plan status` — read methodfile.json's planning tracker
+ * and print a 5-line summary of where the project is in the planning arc.
+ *
+ * Read-only; never mutates state. The actual phase advancement is done by
+ * the relevant plan-* protocol when it finishes its work and updates the
+ * methodfile + STATE.md as part of its end-of-session.
+ */
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+const PHASES = [
+    { key: 'phaseA_orientation', label: 'A. Orientation' },
+    { key: 'phaseB_architecture', label: 'B. Architecture & Contracts' },
+    { key: 'phaseC_uiUxDesignSystem', label: 'C. UI/UX + Design System' },
+    { key: 'phaseD_maps', label: 'D. Maps' },
+    { key: 'phaseE_initialWorkUnits', label: 'E. Initial Work Units' },
+];
+function statusIcon(s) {
+    switch (s) {
+        case 'complete':
+            return '✅';
+        case 'in_progress':
+            return '🟡';
+        default:
+            return '🔵';
+    }
+}
+function statusLabel(s) {
+    switch (s) {
+        case 'complete':
+            return 'complete';
+        case 'in_progress':
+            return 'in progress';
+        default:
+            return 'not started';
+    }
+}
+export async function cmdPlanStatus(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const methodfilePath = path.join(cwd, 'methodfile.json');
+    if (!existsSync(methodfilePath)) {
+        console.error(`No methodfile.json found at ${cwd}.`);
+        console.error('Run `nuos-catalogue init` first to set up a catalogue.');
+        return 1;
+    }
+    let mf;
+    try {
+        mf = JSON.parse(await readFile(methodfilePath, 'utf8'));
+    }
+    catch (err) {
+        console.error(`Couldn't read methodfile.json: ${err.message}`);
+        return 1;
+    }
+    const planning = mf.planning ?? {};
+    console.log('');
+    console.log('Planning progress for this project:');
+    console.log('');
+    for (const { key, label } of PHASES) {
+        const status = planning[key];
+        console.log(`  ${statusIcon(status)} ${label.padEnd(36)} ${statusLabel(status)}`);
+    }
+    console.log('');
+    const firstNotStarted = PHASES.find((p) => planning[p.key] !== 'complete');
+    if (!firstNotStarted) {
+        console.log('All five phases complete. The project is ready to build —');
+        console.log('use /start-of-session and /end-of-session for normal work from here.');
+        console.log('');
+        return 0;
+    }
+    if (planning[firstNotStarted.key] === 'in_progress') {
+        console.log(`Currently in: ${firstNotStarted.label} (in progress)`);
+        console.log('Resume by running /start-of-session — the AI reads the last session log');
+        console.log('and picks up at the right step.');
+    }
+    else {
+        console.log(`Next phase: ${firstNotStarted.label}`);
+        console.log('Begin by running /start-of-session — the AI detects the empty phase');
+        console.log('and routes to the right planning protocol.');
+    }
+    console.log('');
+    return 0;
+}

package/dist/commands/write.js

@@ -86,16 +86,25 @@ function inferWorkflowStatus(record) {
 }
 // ---------------------------------------------------------------------------
 // wu tick <handle> --index=N --evidence="..."
+//
+// --index is **1-based** at the CLI boundary (so --index=1 ticks the first
+// AC). Internally the pack workflow + ac-parse use 0-based indexing; the
+// conversion happens here so the user-facing surface matches the
+// human-readable summary text the mis-adapter writes into the markdown
+// changelog ("Acceptance criterion 3 ticked: ...").
 // ---------------------------------------------------------------------------
 export async function cmdWuTick(store, runtime, args) {
     if (!args.handle) {
         return {
-            output: 'Usage: nuos-catalogue wu tick <handle> --index=N --evidence="..."',
+            output: 'Usage: nuos-catalogue wu tick <handle> --index=N --evidence="..."  (--index is 1-based)',
             exitCode: 2,
         };
     }
-    if (typeof args.index !== 'number' || !Number.isInteger(args.index) || args.index < 0) {
-        return { output: '--index=<non-negative integer> is required', exitCode: 2 };
+    if (typeof args.index !== 'number' || !Number.isInteger(args.index) || args.index < 1) {
+        return {
+            output: '--index=<positive integer> is required (1-based: --index=1 ticks the first AC)',
+            exitCode: 2,
+        };
     }
     if (!args.evidence || args.evidence.trim().length === 0) {
         return { output: '--evidence="..." is required (non-empty)', exitCode: 2 };
@@ -104,17 +113,19 @@ export async function cmdWuTick(store, runtime, args) {
     if (!store.has(handle)) {
         return { output: `no work_unit record for handle "${handle}"`, exitCode: 1 };
     }
+    // Convert 1-based CLI input to 0-based for the workflow + ac-parse layer.
+    const zeroBasedIndex = args.index - 1;
     const capture = {
         channel: 'typed_note',
         content: `tick AC #${args.index} on ${handle}`,
         subjects: [{ kind: 'work_unit', id: handle }],
         metadata: {
             targetHandle: handle,
-            criterionIndex: args.index,
+            criterionIndex: zeroBasedIndex,
             evidence: args.evidence,
         },
     };
-    return await driveLifecycle(runtime, 'work_unit.tick_acceptance_criterion', capture, handle, `index ${args.index}`);
+    return await driveLifecycle(runtime, 'work_unit.tick_acceptance_criterion', capture, handle, `AC ${args.index}`);
 }
 // ---------------------------------------------------------------------------
 // decision supersede <target> --by=<superseding> [--reason="..."]

package/dist/embedder/ollama.d.ts

@@ -1,10 +1,16 @@
 /**
  * Ollama embedder — local inference, no network egress.
  *
- * Default model: qwen3-embedding:8b (4096 dims, 32k context). Config via
- * NUOS_CATALOGUE_OLLAMA_MODEL. Smaller variants (qwen3-embedding:4b,
- * qwen3-embedding:0.6b) work the same way; switching variants requires
- * a full reindex if the dimension changes.
+ * Default model: qwen3-embedding:0.6b (1024 dims). Picked as default
+ * because it runs on the broad majority of developer machines without
+ * meaningful CPU strain — the prior 8b default produced noticeable load
+ * on Apple Silicon during a catalogue reindex, and the build harness
+ * ships to projects whose maintainers won't necessarily have an
+ * M-series Mac. Higher-fidelity variants (qwen3-embedding:4b at 2560
+ * dims, qwen3-embedding:8b at 4096 dims) are available via
+ * NUOS_CATALOGUE_OLLAMA_MODEL when the user wants better recall and
+ * has the headroom. Switching variants requires a full reindex because
+ * dimensions change.
  *
  * Why local: keeps the catalogue's content (and any future workload that
  * uses the same Embedder interface) inside whatever boundary Ollama is
@@ -26,10 +32,10 @@
  * idle-timeout (the keep_alive: "1m" we sent) cleans up within a
  * minute.
  *
- * Sizing note — the 8b model at Q4_K_M is ~4.7GB on disk and benefits
- * from ~16GB of RAM. Apple Silicon Metal acceleration helps a lot. On
- * smaller boxes drop to qwen3-embedding:4b (better accuracy/RAM ratio)
- * or qwen3-embedding:0.6b (CPU-only friendly).
+ * Sizing note — the new 0.6b default is ~600MB on disk and runs
+ * comfortably on any modern laptop, including CPU-only. The 4b variant
+ * (~2.5GB) and 8b variant (~4.7GB, benefits from ~16GB RAM + Metal)
+ * are upgrades for users who want better recall and have the headroom.
  */
 import type { Embedder } from './types.js';
 export declare class OllamaEmbedder implements Embedder {

package/dist/embedder/ollama.js

@@ -1,10 +1,16 @@
 /**
  * Ollama embedder — local inference, no network egress.
  *
- * Default model: qwen3-embedding:8b (4096 dims, 32k context). Config via
- * NUOS_CATALOGUE_OLLAMA_MODEL. Smaller variants (qwen3-embedding:4b,
- * qwen3-embedding:0.6b) work the same way; switching variants requires
- * a full reindex if the dimension changes.
+ * Default model: qwen3-embedding:0.6b (1024 dims). Picked as default
+ * because it runs on the broad majority of developer machines without
+ * meaningful CPU strain — the prior 8b default produced noticeable load
+ * on Apple Silicon during a catalogue reindex, and the build harness
+ * ships to projects whose maintainers won't necessarily have an
+ * M-series Mac. Higher-fidelity variants (qwen3-embedding:4b at 2560
+ * dims, qwen3-embedding:8b at 4096 dims) are available via
+ * NUOS_CATALOGUE_OLLAMA_MODEL when the user wants better recall and
+ * has the headroom. Switching variants requires a full reindex because
+ * dimensions change.
  *
  * Why local: keeps the catalogue's content (and any future workload that
  * uses the same Embedder interface) inside whatever boundary Ollama is
@@ -26,12 +32,12 @@
  * idle-timeout (the keep_alive: "1m" we sent) cleans up within a
  * minute.
  *
- * Sizing note — the 8b model at Q4_K_M is ~4.7GB on disk and benefits
- * from ~16GB of RAM. Apple Silicon Metal acceleration helps a lot. On
- * smaller boxes drop to qwen3-embedding:4b (better accuracy/RAM ratio)
- * or qwen3-embedding:0.6b (CPU-only friendly).
+ * Sizing note — the new 0.6b default is ~600MB on disk and runs
+ * comfortably on any modern laptop, including CPU-only. The 4b variant
+ * (~2.5GB) and 8b variant (~4.7GB, benefits from ~16GB RAM + Metal)
+ * are upgrades for users who want better recall and have the headroom.
  */
-const DEFAULT_MODEL = 'qwen3-embedding:8b';
+const DEFAULT_MODEL = 'qwen3-embedding:0.6b';
 const DEFAULT_HOST = 'http://localhost:11434';
 // Qwen3-Embedding produces Matryoshka representations 32–4096 dims.
 // We use the model default. A future tweak could truncate to e.g. 1024