akm-cli 0.6.1 → 0.7.0

package/dist/tests/workflow-qa-fixes.test.js

@@ -0,0 +1,395 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const CLI = path.join(__dirname, "..", "src", "cli.ts");
+const tempDirs = [];
+function makeTempDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+function createWorkflowEnv() {
+    const stashDir = makeTempDir("akm-wfqa-stash-");
+    const xdgCache = makeTempDir("akm-wfqa-cache-");
+    const xdgConfig = makeTempDir("akm-wfqa-config-");
+    return {
+        ...process.env,
+        AKM_STASH_DIR: stashDir,
+        XDG_CACHE_HOME: xdgCache,
+        XDG_CONFIG_HOME: xdgConfig,
+    };
+}
+function runCli(args, env) {
+    return spawnSync("bun", [CLI, ...args], {
+        encoding: "utf8",
+        timeout: 30_000,
+        env,
+    });
+}
+afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+const TWO_STEP_WORKFLOW = `---
+description: Test workflow
+---
+
+# Workflow: Test Flow
+
+## Step: First Step
+Step ID: first
+
+### Instructions
+Do the first thing.
+
+### Completion Criteria
+- First thing done
+
+## Step: Second Step
+Step ID: second
+
+### Instructions
+Do the second thing.
+`;
+function setupWorkflow(env, name = "test-flow") {
+    const sourceDir = makeTempDir("akm-wfqa-src-");
+    const sourcePath = path.join(sourceDir, "wf.md");
+    fs.writeFileSync(sourcePath, TWO_STEP_WORKFLOW, "utf8");
+    const result = runCli(["workflow", "create", name, "--from", sourcePath], env);
+    if (result.status !== 0) {
+        throw new Error(`Failed to create workflow: ${result.stderr}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// 1. resumeWorkflowRun — blocked → active; fails on completed
+// ---------------------------------------------------------------------------
+describe("workflow resume command", () => {
+    test("resume flips a blocked run back to active", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const started = runCli(["workflow", "start", "workflow:test-flow"], env);
+        expect(started.status).toBe(0);
+        const { run: startRun } = JSON.parse(started.stdout);
+        // Complete first step as blocked
+        expect(runCli(["workflow", "complete", startRun.id, "--step", "first", "--state", "blocked"], env).status).toBe(0);
+        // Verify it's blocked
+        const statusBlocked = runCli(["workflow", "status", startRun.id], env);
+        expect(statusBlocked.status).toBe(0);
+        const { run: blockedRun } = JSON.parse(statusBlocked.stdout);
+        expect(blockedRun.status).toBe("blocked");
+        // Resume it
+        const resumed = runCli(["workflow", "resume", startRun.id], env);
+        expect(resumed.status).toBe(0);
+        const { run: resumedRun } = JSON.parse(resumed.stdout);
+        expect(resumedRun.status).toBe("active");
+    });
+    test("resume on a completed run returns an error", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const started = runCli(["workflow", "start", "workflow:test-flow"], env);
+        expect(started.status).toBe(0);
+        const { run: startRun } = JSON.parse(started.stdout);
+        expect(runCli(["workflow", "complete", startRun.id, "--step", "first"], env).status).toBe(0);
+        expect(runCli(["workflow", "complete", startRun.id, "--step", "second"], env).status).toBe(0);
+        const resumed = runCli(["workflow", "resume", startRun.id], env);
+        expect(resumed.status).toBe(2);
+        const err = JSON.parse(resumed.stderr);
+        expect(err.error).toContain("already completed");
+    });
+    test("resume on a failed run flips it to active", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const started = runCli(["workflow", "start", "workflow:test-flow"], env);
+        expect(started.status).toBe(0);
+        const { run: startRun } = JSON.parse(started.stdout);
+        expect(runCli(["workflow", "complete", startRun.id, "--step", "first", "--state", "failed"], env).status).toBe(0);
+        const resumed = runCli(["workflow", "resume", startRun.id], env);
+        expect(resumed.status).toBe(0);
+        const { run: resumedRun } = JSON.parse(resumed.stdout);
+        expect(resumedRun.status).toBe("active");
+    });
+    // Issue #156: after resuming a blocked run, the previously-blocked step must be
+    // re-actionable so it can be reclassified to completed/failed/skipped.
+    for (const newState of ["completed", "failed", "skipped"]) {
+        test(`resume re-opens a blocked step so it can be reclassified to ${newState}`, () => {
+            const env = createWorkflowEnv();
+            setupWorkflow(env);
+            const started = runCli(["workflow", "start", "workflow:test-flow"], env);
+            expect(started.status).toBe(0);
+            const { run: startRun } = JSON.parse(started.stdout);
+            expect(runCli(["workflow", "complete", startRun.id, "--step", "first", "--state", "blocked"], env).status).toBe(0);
+            expect(runCli(["workflow", "resume", startRun.id], env).status).toBe(0);
+            const reclassified = runCli(["workflow", "complete", startRun.id, "--step", "first", "--state", newState, "--notes", "resolved"], env);
+            expect(reclassified.status).toBe(0);
+            const parsed = JSON.parse(reclassified.stdout);
+            const firstStep = parsed.workflow.steps.find((s) => s.id === "first");
+            expect(firstStep?.status).toBe(newState);
+        });
+    }
+    test("resume does not disturb already-completed earlier steps", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const started = runCli(["workflow", "start", "workflow:test-flow"], env);
+        expect(started.status).toBe(0);
+        const { run: startRun } = JSON.parse(started.stdout);
+        expect(runCli(["workflow", "complete", startRun.id, "--step", "first"], env).status).toBe(0);
+        expect(runCli(["workflow", "complete", startRun.id, "--step", "second", "--state", "blocked"], env).status).toBe(0);
+        expect(runCli(["workflow", "resume", startRun.id], env).status).toBe(0);
+        const status = runCli(["workflow", "status", startRun.id], env);
+        expect(status.status).toBe(0);
+        const detail = JSON.parse(status.stdout);
+        expect(detail.workflow.steps.find((s) => s.id === "first")?.status).toBe("completed");
+        expect(detail.workflow.steps.find((s) => s.id === "second")?.status).toBe("pending");
+    });
+});
+// ---------------------------------------------------------------------------
+// 2. listWorkflowRuns --active includes blocked runs
+// ---------------------------------------------------------------------------
+describe("workflow list --active includes blocked", () => {
+    test("blocked run appears in --active list", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const started = runCli(["workflow", "start", "workflow:test-flow"], env);
+        expect(started.status).toBe(0);
+        const { run: startRun } = JSON.parse(started.stdout);
+        expect(runCli(["workflow", "complete", startRun.id, "--step", "first", "--state", "blocked"], env).status).toBe(0);
+        const listed = runCli(["workflow", "list", "--ref", "workflow:test-flow", "--active"], env);
+        expect(listed.status).toBe(0);
+        const { runs } = JSON.parse(listed.stdout);
+        expect(runs.some((r) => r.id === startRun.id && r.status === "blocked")).toBe(true);
+    });
+    test("completed run does NOT appear in --active list", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const started = runCli(["workflow", "start", "workflow:test-flow"], env);
+        expect(started.status).toBe(0);
+        const { run: startRun } = JSON.parse(started.stdout);
+        expect(runCli(["workflow", "complete", startRun.id, "--step", "first"], env).status).toBe(0);
+        expect(runCli(["workflow", "complete", startRun.id, "--step", "second"], env).status).toBe(0);
+        const listed = runCli(["workflow", "list", "--active"], env);
+        expect(listed.status).toBe(0);
+        const { runs } = JSON.parse(listed.stdout);
+        expect(runs.some((r) => r.id === startRun.id)).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// 3. workflow next on a completed run: done:true, step:null
+// ---------------------------------------------------------------------------
+describe("workflow next — completed run signals done", () => {
+    test("next on a completed run-id returns done:true and step:null", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const started = runCli(["workflow", "start", "workflow:test-flow"], env);
+        expect(started.status).toBe(0);
+        const { run: startRun } = JSON.parse(started.stdout);
+        expect(runCli(["workflow", "complete", startRun.id, "--step", "first"], env).status).toBe(0);
+        expect(runCli(["workflow", "complete", startRun.id, "--step", "second"], env).status).toBe(0);
+        const next = runCli(["workflow", "next", startRun.id], env);
+        expect(next.status).toBe(0);
+        const nextJson = JSON.parse(next.stdout);
+        expect(nextJson.done).toBe(true);
+        expect(nextJson.step).toBeNull();
+    });
+});
+// ---------------------------------------------------------------------------
+// 4. workflow next <ref> auto-start: autoStarted:true
+// ---------------------------------------------------------------------------
+describe("workflow next — auto-start flags autoStarted", () => {
+    test("next on a ref with no existing run returns autoStarted:true", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const next = runCli(["workflow", "next", "workflow:test-flow"], env);
+        expect(next.status).toBe(0);
+        const nextJson = JSON.parse(next.stdout);
+        expect(nextJson.autoStarted).toBe(true);
+        expect(nextJson.run.status).toBe("active");
+        expect(nextJson.step.id).toBe("first");
+    });
+    test("next on a ref with existing active run does NOT set autoStarted", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        // First call auto-starts
+        const first = runCli(["workflow", "next", "workflow:test-flow"], env);
+        expect(first.status).toBe(0);
+        // Second call resumes existing — no autoStarted
+        const second = runCli(["workflow", "next", "workflow:test-flow"], env);
+        expect(second.status).toBe(0);
+        const secondJson = JSON.parse(second.stdout);
+        expect(secondJson.autoStarted).toBeUndefined();
+    });
+});
+// ---------------------------------------------------------------------------
+// 5. workflow next --params: sets params on auto-start; fails on existing run
+// ---------------------------------------------------------------------------
+describe("workflow next --params", () => {
+    test("--params is accepted when auto-starting a new run", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const next = runCli(["workflow", "next", "workflow:test-flow", "--params", '{"x":1}'], env);
+        expect(next.status).toBe(0);
+        const nextJson = JSON.parse(next.stdout);
+        expect(nextJson.autoStarted).toBe(true);
+        expect(nextJson.run.params?.x).toBe(1);
+    });
+    test("--params fails when an active run already exists (ref specifier)", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        // Start a run first
+        expect(runCli(["workflow", "start", "workflow:test-flow"], env).status).toBe(0);
+        const next = runCli(["workflow", "next", "workflow:test-flow", "--params", '{"x":1}'], env);
+        expect(next.status).toBe(2);
+        const err = JSON.parse(next.stderr);
+        expect(err.error).toContain("--params can only be set on a new run");
+    });
+    test("--params fails when given a direct run-id (existing run)", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const started = runCli(["workflow", "start", "workflow:test-flow"], env);
+        expect(started.status).toBe(0);
+        const { run: startRun } = JSON.parse(started.stdout);
+        const next = runCli(["workflow", "next", startRun.id, "--params", '{"x":1}'], env);
+        expect(next.status).toBe(2);
+        const err = JSON.parse(next.stderr);
+        expect(err.error).toContain("--params can only be used when starting a new run from a workflow ref");
+        expect(err.error).toContain("existing run id");
+    });
+});
+// ---------------------------------------------------------------------------
+// 6. workflow status workflow:<name> resolves to most-recent run
+// ---------------------------------------------------------------------------
+describe("workflow status with workflow ref", () => {
+    test("status workflow:<name> resolves to the most-recently-updated run", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const started = runCli(["workflow", "start", "workflow:test-flow"], env);
+        expect(started.status).toBe(0);
+        const { run: startRun } = JSON.parse(started.stdout);
+        const status = runCli(["workflow", "status", "workflow:test-flow"], env);
+        expect(status.status).toBe(0);
+        const statusJson = JSON.parse(status.stdout);
+        expect(statusJson.run.id).toBe(startRun.id);
+        expect(statusJson.run.status).toBe("active");
+    });
+    test("status workflow:<name> returns NotFoundError when no runs exist", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const status = runCli(["workflow", "status", "workflow:test-flow"], env);
+        // No runs created yet — should fail with not-found (exit 1)
+        expect(status.status).toBe(1);
+        const err = JSON.parse(status.stderr);
+        expect(err.error).toContain("No workflow runs found");
+    });
+    test("next with an unknown run id returns WORKFLOW_NOT_FOUND", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const next = runCli(["workflow", "next", "bogus-run-id"], env);
+        expect(next.status).toBe(1);
+        const err = JSON.parse(next.stderr);
+        expect(err.code).toBe("WORKFLOW_NOT_FOUND");
+        expect(err.hint).toContain("akm workflow list --active");
+    });
+    test("status with an unknown run id returns WORKFLOW_NOT_FOUND", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const status = runCli(["workflow", "status", "bogus-run-id"], env);
+        expect(status.status).toBe(1);
+        const err = JSON.parse(status.stderr);
+        expect(err.code).toBe("WORKFLOW_NOT_FOUND");
+        expect(err.hint).toContain("akm workflow list --active");
+    });
+});
+// ---------------------------------------------------------------------------
+// 7. workflow create name validation
+// ---------------------------------------------------------------------------
+describe("workflow create — name validation", () => {
+    test("name with spaces is rejected", () => {
+        const env = createWorkflowEnv();
+        const result = runCli(["workflow", "create", "name with spaces"], env);
+        expect(result.status).toBe(2);
+        const err = JSON.parse(result.stderr);
+        expect(err.error).toContain("Workflow name must start with a lowercase letter");
+    });
+    test("name with uppercase is rejected", () => {
+        const env = createWorkflowEnv();
+        const result = runCli(["workflow", "create", "MyWorkflow"], env);
+        expect(result.status).toBe(2);
+        const err = JSON.parse(result.stderr);
+        expect(err.error).toContain("Workflow name must start with a lowercase letter");
+    });
+    test("valid lowercase name is accepted", () => {
+        const env = createWorkflowEnv();
+        const result = runCli(["workflow", "create", "my-workflow"], env);
+        expect(result.status).toBe(0);
+        const json = JSON.parse(result.stdout);
+        expect(json.ref).toBe("workflow:my-workflow");
+    });
+    test("hierarchical name with forward slash is accepted", () => {
+        // Slashes are allowed for hierarchical naming (e.g. release/ship)
+        const env = createWorkflowEnv();
+        const result = runCli(["workflow", "create", "release/ship"], env);
+        expect(result.status).toBe(0);
+        const json = JSON.parse(result.stdout);
+        expect(json.ref).toBe("workflow:release/ship");
+    });
+    test("name validation error message mentions slashes", () => {
+        const env = createWorkflowEnv();
+        const result = runCli(["workflow", "create", "BAD NAME"], env);
+        expect(result.status).toBe(2);
+        const err = JSON.parse(result.stderr);
+        expect(err.error).toContain("slashes");
+    });
+});
+// ---------------------------------------------------------------------------
+// 8. workflow create --force without --from/--reset is rejected
+// ---------------------------------------------------------------------------
+describe("workflow create --force guard", () => {
+    test("--force without --from or --reset is rejected", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const result = runCli(["workflow", "create", "test-flow", "--force"], env);
+        expect(result.status).toBe(2);
+        const err = JSON.parse(result.stderr);
+        expect(err.error).toContain("Refusing to overwrite with template");
+    });
+    test("--force --reset succeeds and overwrites with template", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const result = runCli(["workflow", "create", "test-flow", "--force", "--reset"], env);
+        expect(result.status).toBe(0);
+        const json = JSON.parse(result.stdout);
+        expect(json.ok).toBe(true);
+        expect(json.ref).toBe("workflow:test-flow");
+    });
+    test("--force --from <file> succeeds and overwrites with file content", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const sourceDir = makeTempDir("akm-wfqa-src2-");
+        const sourcePath = path.join(sourceDir, "new.md");
+        fs.writeFileSync(sourcePath, TWO_STEP_WORKFLOW, "utf8");
+        const result = runCli(["workflow", "create", "test-flow", "--force", "--from", sourcePath], env);
+        expect(result.status).toBe(0);
+        const json = JSON.parse(result.stdout);
+        expect(json.ok).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// 9. complete --state help text documents default (just ensure it runs)
+// ---------------------------------------------------------------------------
+describe("workflow complete --state default", () => {
+    test("complete without --state defaults to completed", () => {
+        const env = createWorkflowEnv();
+        setupWorkflow(env);
+        const started = runCli(["workflow", "start", "workflow:test-flow"], env);
+        expect(started.status).toBe(0);
+        const { run: startRun } = JSON.parse(started.stdout);
+        // No --state flag → should default to 'completed'
+        const completed = runCli(["workflow", "complete", startRun.id, "--step", "first"], env);
+        expect(completed.status).toBe(0);
+        const json = JSON.parse(completed.stdout);
+        const step = json.workflow.steps.find((s) => s.id === "first");
+        expect(step?.status).toBe("completed");
+    });
+});

package/dist/tests/workflows/indexer-rejection.test.js

@@ -0,0 +1,213 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getDbPath } from "../../src/core/paths";
+import { resetQuiet, resetVerbose, setVerbose } from "../../src/core/warn";
+import { closeDatabase, openDatabase } from "../../src/indexer/db";
+import { akmIndex } from "../../src/indexer/indexer";
+let testConfigDir = "";
+let testCacheDir = "";
+const originalXdgConfigHome = process.env.XDG_CONFIG_HOME;
+const originalXdgCacheHome = process.env.XDG_CACHE_HOME;
+beforeEach(() => {
+    testConfigDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-wf-idx-config-"));
+    testCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-wf-idx-cache-"));
+    process.env.XDG_CONFIG_HOME = testConfigDir;
+    process.env.XDG_CACHE_HOME = testCacheDir;
+    const dbPath = getDbPath();
+    for (const f of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
+        try {
+            fs.unlinkSync(f);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    // Defensive: other test files may have left the warn module's quiet/verbose
+    // latches on. Reset both before each test so the noise-gate assertions read
+    // a clean state.
+    resetQuiet();
+    resetVerbose();
+    delete process.env.AKM_VERBOSE;
+});
+afterEach(() => {
+    if (originalXdgConfigHome === undefined)
+        delete process.env.XDG_CONFIG_HOME;
+    else
+        process.env.XDG_CONFIG_HOME = originalXdgConfigHome;
+    if (originalXdgCacheHome === undefined)
+        delete process.env.XDG_CACHE_HOME;
+    else
+        process.env.XDG_CACHE_HOME = originalXdgCacheHome;
+    if (testConfigDir) {
+        fs.rmSync(testConfigDir, { recursive: true, force: true });
+        testConfigDir = "";
+    }
+    if (testCacheDir) {
+        fs.rmSync(testCacheDir, { recursive: true, force: true });
+        testCacheDir = "";
+    }
+    resetVerbose();
+    delete process.env.AKM_VERBOSE;
+});
+function tmpStash() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-wf-idx-"));
+    fs.mkdirSync(path.join(dir, "workflows"), { recursive: true });
+    return dir;
+}
+function writeWorkflow(stashDir, name, content) {
+    const file = path.join(stashDir, "workflows", `${name}.md`);
+    fs.writeFileSync(file, content);
+    return file;
+}
+const VALID_WORKFLOW = `# Workflow: Ship Release
+
+## Step: Validate
+Step ID: validate
+
+### Instructions
+Confirm release notes are present.
+`;
+const BROKEN_WORKFLOW = `# Workflow: Bad
+
+## Step: First
+Step ID: first
+### Instructions
+do A
+
+## Step: Second
+Step ID: first
+### Instructions
+do B
+`;
+test("indexer admits valid workflows and writes their JSON to workflow_documents", async () => {
+    const stashDir = tmpStash();
+    writeWorkflow(stashDir, "good", VALID_WORKFLOW);
+    const result = await akmIndex({ stashDir, full: true });
+    expect(result.totalEntries).toBe(1);
+    const db = openDatabase();
+    try {
+        const row = db
+            .prepare(`SELECT wd.document_json, wd.schema_version, wd.source_path
+           FROM workflow_documents wd
+           JOIN entries e ON e.id = wd.entry_id
+          WHERE e.entry_type = 'workflow' AND e.entry_key LIKE ?`)
+            .get(`${stashDir}:workflow:%`);
+        expect(row).toBeDefined();
+        if (!row)
+            return;
+        expect(row.schema_version).toBe(1);
+        expect(row.source_path).toContain("good.md");
+        const doc = JSON.parse(row.document_json);
+        expect(doc.title).toBe("Ship Release");
+        expect(doc.steps).toHaveLength(1);
+        expect(doc.steps[0].instructions.text).toContain("Confirm release notes");
+        expect(doc.steps[0].source.start).toBeGreaterThan(0);
+    }
+    finally {
+        closeDatabase(db);
+    }
+});
+test("indexer rejects broken workflows and surfaces every error in IndexResponse.warnings", async () => {
+    const stashDir = tmpStash();
+    writeWorkflow(stashDir, "good", VALID_WORKFLOW);
+    const brokenPath = writeWorkflow(stashDir, "bad", BROKEN_WORKFLOW);
+    const result = await akmIndex({ stashDir, full: true });
+    expect(result.totalEntries).toBe(1); // only the good one
+    expect(result.warnings ?? []).toBeDefined();
+    const warnings = result.warnings ?? [];
+    // The broken workflow has a duplicate step ID; the warning string must
+    // mention the file and at least one of its errors.
+    const brokenWarning = warnings.find((w) => w.includes(brokenPath));
+    expect(brokenWarning).toBeDefined();
+    expect(brokenWarning).toMatch(/already used|Step ID/);
+    const db = openDatabase();
+    try {
+        const goodRow = db
+            .prepare(`SELECT 1 FROM workflow_documents wd
+           JOIN entries e ON e.id = wd.entry_id
+          WHERE e.entry_key = ?`)
+            .get(`${stashDir}:workflow:good`);
+        expect(goodRow).toBeDefined();
+        const badRow = db
+            .prepare(`SELECT 1 FROM workflow_documents wd
+           JOIN entries e ON e.id = wd.entry_id
+          WHERE e.entry_key = ?`)
+            .get(`${stashDir}:workflow:bad`);
+        expect(badRow).toBeFalsy();
+    }
+    finally {
+        closeDatabase(db);
+    }
+});
+// ── Workflow validation noise gate (issue #273) ─────────────────────────────
+async function captureStderr(fn) {
+    const lines = [];
+    const originalWarn = console.warn.bind(console);
+    console.warn = (...args) => {
+        lines.push(args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" "));
+    };
+    try {
+        const result = await fn();
+        return { result, lines };
+    }
+    finally {
+        console.warn = originalWarn;
+    }
+}
+test("default verbosity emits one summary line, not per-spec workflow warnings", async () => {
+    const stashDir = tmpStash();
+    // Two broken workflows so we can prove the summary line is emitted instead
+    // of two separate per-spec warnings on stderr.
+    writeWorkflow(stashDir, "bad1", BROKEN_WORKFLOW);
+    writeWorkflow(stashDir, "bad2", BROKEN_WORKFLOW);
+    const { lines } = await captureStderr(() => akmIndex({ stashDir, full: true }));
+    const perSpec = lines.filter((l) => l.startsWith("Skipped workflow "));
+    expect(perSpec).toHaveLength(0);
+    const summary = lines.filter((l) => l.includes("workflow specs skipped due to validation errors"));
+    expect(summary).toHaveLength(1);
+    expect(summary[0]).toMatch(/^2 workflow specs skipped/);
+    expect(summary[0]).toContain("--verbose");
+    expect(summary[0]).toContain("AKM_VERBOSE");
+});
+test("default verbosity uses singular 'workflow spec' when only one was skipped", async () => {
+    const stashDir = tmpStash();
+    writeWorkflow(stashDir, "bad", BROKEN_WORKFLOW);
+    const { lines } = await captureStderr(() => akmIndex({ stashDir, full: true }));
+    const summary = lines.filter((l) => l.includes("workflow spec skipped"));
+    expect(summary).toHaveLength(1);
+    expect(summary[0]).toMatch(/^1 workflow spec skipped/);
+});
+test("--verbose flag restores per-spec workflow warnings and suppresses the summary", async () => {
+    const stashDir = tmpStash();
+    writeWorkflow(stashDir, "bad1", BROKEN_WORKFLOW);
+    writeWorkflow(stashDir, "bad2", BROKEN_WORKFLOW);
+    setVerbose(true);
+    const { lines } = await captureStderr(() => akmIndex({ stashDir, full: true }));
+    const perSpec = lines.filter((l) => l.startsWith("Skipped workflow "));
+    expect(perSpec).toHaveLength(2);
+    const summary = lines.filter((l) => l.includes("workflow specs skipped due to validation errors"));
+    expect(summary).toHaveLength(0);
+});
+test("AKM_VERBOSE=1 restores per-spec output even with the verbose flag unset", async () => {
+    const stashDir = tmpStash();
+    writeWorkflow(stashDir, "bad", BROKEN_WORKFLOW);
+    process.env.AKM_VERBOSE = "1";
+    const { lines } = await captureStderr(() => akmIndex({ stashDir, full: true }));
+    const perSpec = lines.filter((l) => l.startsWith("Skipped workflow "));
+    expect(perSpec).toHaveLength(1);
+    const summary = lines.filter((l) => l.includes("workflow spec skipped"));
+    expect(summary).toHaveLength(0);
+});
+test("AKM_VERBOSE=0 hard-disables verbose output even when --verbose flag was set", async () => {
+    const stashDir = tmpStash();
+    writeWorkflow(stashDir, "bad", BROKEN_WORKFLOW);
+    setVerbose(true);
+    process.env.AKM_VERBOSE = "0";
+    const { lines } = await captureStderr(() => akmIndex({ stashDir, full: true }));
+    const perSpec = lines.filter((l) => l.startsWith("Skipped workflow "));
+    expect(perSpec).toHaveLength(0);
+    const summary = lines.filter((l) => l.includes("workflow spec skipped"));
+    expect(summary).toHaveLength(1);
+});

package/docs/README.md

@@ -6,9 +6,12 @@
 - [Getting Started](getting-started.md) -- Quick setup guide
 - [Agent Install Guide](agents/agent-install.md) -- Step-by-step automated install for agents
 - [Stash Maker's Guide](stash-makers.md) -- Build and share a stash on GitHub, npm, or a network directory
+- [Wikis](wikis.md) -- Multi-wiki knowledge bases (Karpathy-style)
 
 ## Upgrading
 
+- [v1 migration guide](migration/v1.md) -- The path from 0.x to v1.0
+- [Release notes (latest: 0.7.0)](migration/release-notes/0.7.0.md) -- Per-release notes drop into `migration/release-notes/`
 - [v0.5 → v0.6 migration guide](migration/v0.5-to-v0.6.md) -- Every breaking change with before/after code, publisher checklist, and troubleshooting
 
 ## Reference
@@ -28,3 +31,8 @@
 - [Ref Format](technical/ref.md) -- Wire format for asset references
 - [Test Coverage Guide](technical/test-coverage-guide.md) -- High-value testing areas
 - [Core Principles](technical/akm-core-principles.md) -- Design principles and constraints
+- [akm-bench](technical/benchmark.md) -- Search-quality benchmark suite
+
+## Posts
+
+- [Blog posts](posts/) -- Articles and posts about akm