@jamie-tam/forge 6.0.0

package/commands/setup.md

@@ -0,0 +1,201 @@
+---
+name: setup
+description: "Infer project stack from manifests, fill in the CLAUDE.md and AGENTS.md project profiles, and scaffold the .forge and aiwiki directories. Run after forge init."
+---
+
+# /setup — Configure Project Profile
+
+You are configuring the forge project profile. The CLI (`npx @jamie-tam/forge init`) already installed skills, commands, agents, hooks, all language rules, and the CLAUDE.md / AGENTS.md templates. This command infers the project's tech profile, fills the templates, and scaffolds the working directories.
+
+Language rules ship complete (typescript, react, python). Agents read the rule files matching the work at hand — no install-time pruning needed.
+
+## Step 1: Detect Optional Tools & Build Graph
+
+Detect optional tools first — Graphify's knowledge graph enriches stack inference and reduces tokens for all later steps.
+
+**Graphify (knowledge graph):**
+
+Run the graphify status check from `protocols/graphify.md`:
+
+1. Check three things:
+   - `graphify-out/graph.json` exists?
+   - `graphify --version` succeeds (CLI installed)?
+   - `~/.claude/skills/graphify/SKILL.md` exists (skill installed for `/graphify` to work)?
+2. Prompt based on status (see the full guard table in `protocols/graphify.md`):
+   - **Nothing installed** → offer install (CLI + skill manual path from protocol)
+   - **CLI installed, skill missing** → offer skill install only (so `/graphify` works)
+   - **Both installed, no graph** → offer build (`/graphify`)
+   - **Graph exists, both installed** → offer update (`/graphify --update`)
+   - **Graph exists, CLI missing** → use static files only
+3. If user accepts build/update → invoke the `/graphify` skill, then continue.
+4. If graph is available after this step, it will enrich Step 2.
+
+**Codex plugin:**
+```bash
+codex --version 2>/dev/null
+```
+- If detected: note the version for the report.
+- If not detected: do not mention it.
+
+**Gitignore setup:**
+Ensure `.forge/local.yaml` is in `.gitignore`. This file stores per-user preferences (e.g., Codex consent, Graphify consent) and must not be committed.
+
+```bash
+grep -q '.forge/local.yaml' .gitignore 2>/dev/null || echo '.forge/local.yaml' >> .gitignore
+```
+
+<GATE>
+STOP. If Graphify was recommended for installation or a graph build was offered, wait for the user's response before proceeding. Do NOT skip ahead to stack inference — the graph data from this step enriches the next step. Only proceed to Step 2 after the user has responded to all tool recommendations.
+</GATE>
+
+## Step 2: Infer Project Profile & Fill Templates
+
+Read the project's manifest files to infer the tech profile. Check whichever exist:
+
+| Look for | Tells you |
+|---|---|
+| `package.json` | name, dependencies, frameworks (React/Vue/Next/Astro/Hono/etc.), test runner (vitest/jest/playwright), bundler |
+| `pnpm-workspace.yaml`, `package.json` `workspaces` | monorepo structure — scan each workspace's manifest |
+| `pyproject.toml`, `requirements.txt`, `Pipfile` | Python deps, framework (FastAPI/Django/Flask), test runner (pytest) |
+| `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle` | Go / Rust / Java / Kotlin |
+| Lock files (`pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `package-lock.json`, `uv.lock`, `poetry.lock`) | Package manager |
+| `tsconfig.json` | TypeScript |
+| `Dockerfile`, `docker-compose.yml` | Container setup, often database hints |
+| `vite.config.*`, `next.config.*`, `astro.config.*`, etc. | Confirm framework |
+| `tailwind.config.*`, `postcss.config.*` | Styling stack |
+
+If a Graphify graph is available, cross-reference its technology nodes and community labels to validate and enrich the inference (especially for monorepos and modern frameworks the manifests don't fully reveal).
+
+Synthesize what you find into a profile. Aim for accurate version numbers (read package versions, not just names). Present for confirmation:
+
+```
+Inferred project profile:
+  Name:            my-app
+  Stack:           typescript/react 18 + next 14
+  Database:        postgresql (via @prisma/client)
+  Unit tests:      vitest
+  E2E tests:       playwright
+  Package manager: pnpm
+  Notable libs:    zustand, tailwind 4, lucide-react
+
+Is this right? (y / correct field=value / describe what's off)
+```
+
+Let the user correct any fields. Honor user corrections — they know their project; you're inferring.
+
+<GATE>
+STOP. Do NOT proceed until the user has confirmed or corrected the inferred profile. The values flow into project docs and the wiki — wrong values mislead every later session.
+</GATE>
+
+After confirmation, fill both project docs. Show the filled content for review before writing:
+
+- **`.claude/CLAUDE.md`** — populate the `project:` YAML block: name, stack, database, test_runner, package_manager.
+- **`AGENTS.md`** (repo root) — populate the Project section: Name, Stack, Test runner, Package manager. Replace the `(run /setup)` placeholders with actual values.
+
+<GATE>
+STOP. Present the filled CLAUDE.md and AGENTS.md content to the user for review before writing. Do NOT write files without user confirmation.
+</GATE>
+
+## Step 2a: Configure Gate Enforcement Mode
+
+`npx @jamie-tam/forge init` installs PreToolUse hooks that block manifest `gate-passed: true` edits unless telemetry shows the matching skill was invoked via the Skill tool. Useful for production-grade work; high-friction for prototype iteration where most phases are explicitly skipped.
+
+**Default suggestion** (computed from Step 2 profile):
+- If signals match **prototype mode** (path under `pocs/`, `package.json` `"private": true` with no CI, no `aiwiki/architecture/`): suggest **disable**
+- If signals match **production mode** (CI configured, tests present, codified architecture exists or imminent): suggest **keep enabled**
+
+Ask the user:
+
+```
+Gate enforcement (PreToolUse hooks that block manifest gate-passed edits without skill-invocation telemetry):
+
+Suggested for this project: <KEEP ENABLED | DISABLE>
+
+  • Keep enabled — production-grade discipline; manifests cannot lie about gate state
+  • Disable     — prototype iteration; faster loop, telemetry still recorded for retrospective audit
+
+Choice? [Y]es (keep enabled) / [d]isable / [k]eep enabled regardless of suggestion
+```
+
+**On "disable"**: remove the two gate-enforcer matcher entries from `.claude/settings.local.json` (the entries with `matcher: Edit` or `matcher: Write` whose command invokes `.claude/hooks/scripts/gate-enforcer.sh`). The file is gitignored so this is a local-only change. Keep the PostToolUse telemetry hook — telemetry is still recorded for retrospective audit; only the blocking is removed.
+
+**On "keep enabled"**: leave settings.local.json as installed.
+
+Tell the user: "Gate enforcement <enabled / disabled>. To toggle later, edit `.claude/settings.local.json` — see `hooks/hooks.json` in the forge repo for the canonical entries."
+
+Note in the manifest or session memo what was chosen, so future sessions don't have to re-detect.
+
+## Step 3: Create .forge Directory
+
+Create the working directory structure if it doesn't exist:
+
+```
+.forge/
+├── work/               # Per-work-item artifacts and manifests, one subdir per type
+│   ├── feature/
+│   ├── bugfix/
+│   ├── refactor/
+│   ├── hotfix/
+│   └── greenfield/
+├── state/              # Runtime state (telemetry, wiki receipts, dream history)
+└── wiki-history/       # Pre-swap snapshots of aiwiki/ before atomic accept (for rollback)
+```
+
+Only create the top-level directories. Individual work-item folders are created on demand by the relevant command.
+
+## Step 4: Create aiwiki Directory
+
+The `aiwiki/` is the project's persistent context layer — typed pages (decisions, gotchas, conventions, architecture, sessions), an auto-loaded usage rules file, and the schema definitions LINT validates against. Scaffold from templates installed by `npx @jamie-tam/forge init`:
+
+```
+aiwiki/
+├── CLAUDE.md          # Auto-loaded by Claude Code at session start (wiki usage rules)
+├── INDEX.md           # Sortable index of recent activity (dream-maintained)
+├── projectbrief.md    # One-pager: what this project is (filled by user)
+├── decisions/         # ADRs
+├── gotchas/           # Recurring failures + prevention
+├── conventions/       # Codebase patterns + rationale
+├── architecture/      # System-shape docs (one file per subsystem)
+├── sessions/          # Per-session handoff index (hook + dream maintained)
+├── raw/               # Incoming, unclassified — compile or delete at phase close
+├── proposed/          # Dream output awaiting user review (input untouched)
+└── schemas/           # Per-page-type schemas used by wiki-lint
+```
+
+REQUIRED SUB-SKILL: Use **support-wiki-bootstrap** to ensure aiwiki/ exists.
+
+After bootstrap, update `aiwiki/projectbrief.md` with the project name and stack from Step 2 (replace the placeholder description). Ask the user to fill `projectbrief.md` before continuing — the wiki references it for orientation context.
+
+<GATE>
+STOP. The aiwiki/CLAUDE.md is auto-loaded by Claude Code on every session start in this project. Confirm with the user that they accept the wiki usage rules (citation requirements, typed page schemas, no-speculation rule, dream review flow) before completing setup. They can edit aiwiki/CLAUDE.md to customize.
+</GATE>
+
+## Step 5: Report
+
+Print a summary:
+```
+Setup complete!
+
+Project profile:
+  Name:            {name}
+  Stack:           {stack}
+  Test runner:     {test_runner}
+  Package manager: {package_manager}
+
+Configured:
+  - CLAUDE.md and AGENTS.md profiles filled
+  - .forge/ working directory (work/, state/, wiki-history/)
+  - aiwiki/ directory scaffolded (CLAUDE.md, schemas/, projectbrief.md, typed-page subdirs)
+
+Optional tools:
+  - Codex plugin: {detected version | not detected}
+    {If detected: "Second opinions available during quality and planning phases."}
+  - Graphify: {detected version | "not installed — pip install graphifyy"}
+    {If detected + graph built: "Knowledge graph available ({N} nodes, {N} communities)."}
+    {If detected + no graph: "Run /graphify to build a knowledge graph."}
+
+Next steps:
+  1. Review .claude/CLAUDE.md and AGENTS.md
+  2. Run /validate to verify system health
+  3. Start with /feature or /greenfield
+```

package/commands/status.md

@@ -0,0 +1,27 @@
+---
+name: status
+description: "List in-flight .forge/work items and their current phase."
+---
+
+# /status — Work Item Status
+
+List active work items from `.forge/work/` without modifying files.
+
+## Scope
+
+Reports in-flight `.forge/work/` items and their current phase. Read-only — does not modify manifests, files, or wiki. Does NOT resume work, route between commands, or judge whether a stalled item should be aborted. Invoke when the user asks "what's in flight?", before `/resume` (to pick a target), or before `/abort` (to confirm which item).
+
+## Steps
+
+1. Find manifests at `.forge/work/*/*/manifest.yaml`.
+2. Exclude items whose `status` is `completed`, `abandoned`, or `escalated`.
+3. For each remaining item, infer the current phase from the first phase or gate that is not complete, locked, skipped, or not-applicable. Prefer explicit fields such as `build.current_phase` when present.
+4. Print a table:
+
+```markdown
+| Type | Name | Status | Current phase | Manifest |
+|---|---|---|---|---|
+| feature | add-payments | in-progress | quality.test-execution | .forge/work/feature/add-payments/manifest.yaml |
+```
+
+If no in-flight items exist, say so clearly.

package/commands/task-force.md

@@ -0,0 +1,110 @@
+---
+name: task-force
+description: "Dispatch a parallel task-force per item in a user-provided punch list. Phase-aware sizing (light teams in prototype phases, full crew in production). Routes command-shaped items (features, bugfixes, refactors) to their owning commands. Include !max (or --full-power) in your prompt to force full-crew production teams regardless of detected phase."
+argument-hint: "task1; task2; task3 (or numbered/bulleted list); append !max to force full crew"
+---
+
+# /task-force
+
+Run a parallel ad-hoc task-force dispatcher over a punch list of independent tasks.
+
+## When to use
+
+- You have 3-20 independent tasks to do in parallel
+- The tasks are heterogeneous (mix of dev, research, docs, debug, quick fixes)
+- None of the tasks individually warrants a full `/feature` or `/bugfix` workflow
+- You want Codex-paired second opinions where it earns its keep
+
+## When NOT to use
+
+- A single task — use the appropriate skill or command directly
+- A coherent feature spec — use `/feature`
+- A single bug to fix — use `/bugfix`
+- A refactor — use `/refactor`
+- Everything in the list is command-shaped — invoke those commands instead
+
+## Process
+
+REQUIRED SUB-SKILL: Use **support-task-force** to:
+1. Run Codex consent (one-time per run, per `protocols/codex.md`)
+2. Detect repo phase (prototype vs production) from active manifest or repo state
+3. Parse the task list (numbered, bulleted, or semicolon-separated argument)
+4. Classify each task by type (dev / research / debug / docs / review / security / quick / complex / command-shaped)
+5. Route command-shaped items to their owning commands (do NOT dispatch task-forces for them)
+6. Assemble a team per task, sized by task type AND phase mode
+7. Dispatch all task-forces in parallel (background subagents)
+8. Aggregate per-task verdicts with Claude+Codex consensus check
+9. Surface a run-summary with conflicts highlighted
+
+## Arguments
+
+Either:
+- Pass the list directly: `/task-force update README; explore caching options; add test for parser`
+- Or pass a numbered/bulleted list in the next prompt after invoking `/task-force` bare
+
+## Output
+
+`.forge/task-force/{run-id}/` containing:
+- `codex.yaml` — Codex consent choice
+- `tasks.yaml` — task classifications
+- `task-{n}/{role}.md` — per-agent output
+- `task-{n}/verdict.md` — per-task consensus verdict
+- `run-summary.md` — consolidated report
+
+## Caps
+
+- Hard cap: 20 tasks per run
+- Soft cap: 10 tasks (warn, offer to batch)
+- Per-task team: 1-5 agents depending on phase mode and task type
+- Total agents per run: ~5-80 typically
+
+## Examples
+
+### Standard (phase-aware sizing)
+
+```
+/task-force
+1. Update README with new install steps
+2. Explore options for adding a /status command
+3. Add unit test for parser edge cases
+4. Bump dep "yaml" to ^2.3
+5. Investigate why CI is flaky on test 17
+```
+
+Expected behavior (production phase detected):
+- Task 1 (docs): `doc-writer` + Codex verify
+- Task 2 (research): 2 explorers + Codex
+- Task 3 (dev): `builder` + dispatch `quality-code-review`
+- Task 4 (quick): one agent + Codex verify
+- Task 5 (debug): dispatch `support-debug` + `gotcha-hunter` + Codex
+- Total: ~12 agents in parallel
+
+In prototype phase, the same list dispatches ~5 agents (light templates, no Codex on quick/docs).
+
+### Force full power (`!max` override)
+
+```
+/task-force !max
+1. Update README with new install steps
+2. Add helper function for date parsing
+3. Investigate why CI is flaky on test 17
+```
+
+Expected behavior (production teams enforced even if repo is in prototype phase):
+- All tasks dispatch with full production templates
+- Mandatory Codex pairing throughout
+- No "quick mode" shortcut
+- Total: ~8 agents
+
+Use `!max` (short form) or `--full-power` (canonical form) when prototype code is about to graduate to production, or when you want maximum review depth regardless of phase state. Both forms are equivalent.
+
+## Manifest
+
+This command does NOT create a `.forge/work/{type}/{name}/` manifest — task-force runs are not phase-gated. State lives in `.forge/task-force/{run-id}/` only.
+
+If an active feature/bugfix manifest exists, the task-force run-id is appended to its current phase as `task-force-runs: [...]` for audit.
+
+## See also
+
+- `skills/support-task-force/SKILL.md` — full process documentation
+- `/feature`, `/bugfix`, `/refactor` — for command-shaped work that this skill refuses to swallow

package/commands/validate.md

@@ -0,0 +1,12 @@
+---
+name: validate
+description: "Validate that all skills, rules, and commands are consistent. Run after modifying skills or to check system health."
+---
+
+# /validate — System Consistency Check
+
+REQUIRED SUB-SKILL: Use **support-skill-validator** in **full scan mode**.
+
+Run all five validation checks: directive conflicts, I/O graph integrity, responsibility overlaps, gate completeness, post-evolve drift.
+
+Present results to the user. For Critical issues, suggest specific fixes. If fixes are applied, re-run to confirm resolution.

package/dist/__tests__/active-manifest.test.js

@@ -0,0 +1,272 @@
+/**
+ * Smoke test for src/active-manifest.ts.
+ *
+ * Run via: npm run build && node dist/__tests__/active-manifest.test.js
+ *
+ * Uses a tmp dir as cwd so the real .forge/state is untouched.
+ */
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { clearActiveManifest, getActiveManifest, getActivePointerPath, setActiveManifest, } from "../active-manifest.js";
+let passed = 0;
+let failed = 0;
+const fails = [];
+function test(name, fn) {
+    try {
+        fn();
+        passed++;
+        console.log(`  PASS  ${name}`);
+    }
+    catch (e) {
+        failed++;
+        const msg = e instanceof Error ? e.message : String(e);
+        fails.push(`${name}: ${msg}`);
+        console.log(`  FAIL  ${name}\n        ${msg}`);
+    }
+}
+function withTmpProject(fn) {
+    const tmp = mkdtempSync(join(tmpdir(), "forge-active-"));
+    // Make it a git repo so getStateDir resolves cleanly
+    try {
+        require("node:child_process").execSync("git init -q", { cwd: tmp });
+    }
+    catch {
+        /* ignore */
+    }
+    const manifestPath = join(tmp, "manifest.yaml");
+    writeFileSync(manifestPath, "schema_version: \"5\"\n");
+    try {
+        fn(tmp, manifestPath);
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+console.log("\n=== active-manifest.ts smoke tests ===\n");
+test("get when not set returns null", () => {
+    withTmpProject((cwd) => {
+        const ptr = getActiveManifest(cwd);
+        if (ptr !== null)
+            throw new Error(`expected null, got ${JSON.stringify(ptr)}`);
+    });
+});
+test("set + get roundtrip", () => {
+    withTmpProject((cwd, manifestPath) => {
+        const setResult = setActiveManifest(manifestPath, { cwd, setBy: "test" });
+        if (setResult.manifest_path !== manifestPath) {
+            throw new Error(`set returned wrong path: ${setResult.manifest_path}`);
+        }
+        if (setResult.set_by !== "test") {
+            throw new Error(`set_by mismatch: ${setResult.set_by}`);
+        }
+        const got = getActiveManifest(cwd);
+        if (!got)
+            throw new Error("expected pointer, got null");
+        if (got.manifest_path !== manifestPath) {
+            throw new Error(`get returned wrong path: ${got.manifest_path}`);
+        }
+        if (!got.set_at.match(/^\d{4}-\d{2}-\d{2}T/)) {
+            throw new Error(`set_at not ISO-8601: ${got.set_at}`);
+        }
+    });
+});
+test("set rejects non-existent path", () => {
+    withTmpProject((cwd) => {
+        let threw = false;
+        try {
+            setActiveManifest(join(cwd, "does-not-exist.yaml"), { cwd });
+        }
+        catch {
+            threw = true;
+        }
+        if (!threw)
+            throw new Error("expected throw on non-existent path");
+    });
+});
+test("set with skipExistsCheck allows missing path (for tests)", () => {
+    withTmpProject((cwd) => {
+        const r = setActiveManifest(join(cwd, "future.yaml"), { cwd, skipExistsCheck: true });
+        if (!r.manifest_path.endsWith("future.yaml")) {
+            throw new Error("path not set");
+        }
+    });
+});
+test("clear when not set returns false (idempotent)", () => {
+    withTmpProject((cwd) => {
+        const r = clearActiveManifest(cwd);
+        if (r !== false)
+            throw new Error(`expected false, got ${r}`);
+    });
+});
+test("set + clear + get returns null", () => {
+    withTmpProject((cwd, manifestPath) => {
+        setActiveManifest(manifestPath, { cwd });
+        const cleared = clearActiveManifest(cwd);
+        if (cleared !== true)
+            throw new Error("clear should return true after a set");
+        const got = getActiveManifest(cwd);
+        if (got !== null)
+            throw new Error("expected null after clear");
+    });
+});
+test("corrupt JSON throws on get (no silent degradation)", () => {
+    withTmpProject((cwd) => {
+        const stateDir = join(cwd, ".forge", "state");
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(join(stateDir, "active-manifest.json"), "{ this is not valid json }");
+        let threw = false;
+        try {
+            getActiveManifest(cwd);
+        }
+        catch (e) {
+            threw = true;
+            const msg = e instanceof Error ? e.message : String(e);
+            if (!msg.includes("corrupt")) {
+                throw new Error(`expected 'corrupt' in error message, got: ${msg}`);
+            }
+        }
+        if (!threw)
+            throw new Error("expected throw on corrupt JSON");
+    });
+});
+test("missing required fields throws on get", () => {
+    withTmpProject((cwd) => {
+        const stateDir = join(cwd, ".forge", "state");
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(join(stateDir, "active-manifest.json"), JSON.stringify({ manifest_path: "x" }));
+        let threw = false;
+        try {
+            getActiveManifest(cwd);
+        }
+        catch (e) {
+            threw = true;
+            const msg = e instanceof Error ? e.message : String(e);
+            if (!msg.includes("missing required fields")) {
+                throw new Error(`expected 'missing required fields', got: ${msg}`);
+            }
+        }
+        if (!threw)
+            throw new Error("expected throw on missing fields");
+    });
+});
+test("atomic write: pointer file ends with newline + valid JSON", () => {
+    withTmpProject((cwd, manifestPath) => {
+        setActiveManifest(manifestPath, { cwd });
+        const path = getActivePointerPath(cwd);
+        const raw = readFileSync(path, "utf-8");
+        if (!raw.endsWith("\n"))
+            throw new Error("pointer file should end with newline");
+        JSON.parse(raw); // throws if invalid
+    });
+});
+test("set rejects directory paths (not a regular file)", () => {
+    withTmpProject((cwd) => {
+        let threw = false;
+        try {
+            setActiveManifest(cwd, { cwd });
+        }
+        catch (e) {
+            threw = true;
+            const msg = e instanceof Error ? e.message : String(e);
+            if (!msg.includes("not a regular file")) {
+                throw new Error(`expected 'not a regular file', got: ${msg}`);
+            }
+        }
+        if (!threw)
+            throw new Error("expected throw on directory path");
+    });
+});
+test("get throws when pointed-to manifest has been deleted", () => {
+    withTmpProject((cwd, manifestPath) => {
+        setActiveManifest(manifestPath, { cwd });
+        rmSync(manifestPath); // simulate deletion / branch switch
+        let threw = false;
+        try {
+            getActiveManifest(cwd);
+        }
+        catch (e) {
+            threw = true;
+            const msg = e instanceof Error ? e.message : String(e);
+            if (!msg.includes("cannot be read")) {
+                throw new Error(`expected 'cannot be read', got: ${msg}`);
+            }
+        }
+        if (!threw)
+            throw new Error("expected throw on stale pointer");
+    });
+});
+test("get throws when manifest_path is relative in pointer JSON", () => {
+    withTmpProject((cwd) => {
+        const stateDir = join(cwd, ".forge", "state");
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(join(stateDir, "active-manifest.json"), JSON.stringify({ manifest_path: "relative/path.yaml", set_at: "2026-05-04T00:00:00Z", set_by: "test" }));
+        let threw = false;
+        try {
+            getActiveManifest(cwd);
+        }
+        catch (e) {
+            threw = true;
+            const msg = e instanceof Error ? e.message : String(e);
+            if (!msg.includes("must be absolute")) {
+                throw new Error(`expected 'must be absolute', got: ${msg}`);
+            }
+        }
+        if (!threw)
+            throw new Error("expected throw on relative manifest_path");
+    });
+});
+test("get throws when manifest_path is wrong type (e.g. number)", () => {
+    withTmpProject((cwd) => {
+        const stateDir = join(cwd, ".forge", "state");
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(join(stateDir, "active-manifest.json"), JSON.stringify({ manifest_path: 42, set_at: "2026-05-04T00:00:00Z", set_by: "test" }));
+        let threw = false;
+        try {
+            getActiveManifest(cwd);
+        }
+        catch (e) {
+            threw = true;
+            const msg = e instanceof Error ? e.message : String(e);
+            if (!msg.includes("wrong types") && !msg.includes("missing required fields")) {
+                throw new Error(`expected type-validation error, got: ${msg}`);
+            }
+        }
+        if (!threw)
+            throw new Error("expected throw on wrong type");
+    });
+});
+test("set + clear leaves no orphan tmp files", () => {
+    withTmpProject((cwd, manifestPath) => {
+        setActiveManifest(manifestPath, { cwd });
+        clearActiveManifest(cwd);
+        const stateDir = join(cwd, ".forge", "state");
+        const entries = readdirSync(stateDir);
+        const orphans = entries.filter((e) => e.includes(".tmp"));
+        if (orphans.length > 0)
+            throw new Error(`found orphan tmp files: ${orphans.join(", ")}`);
+    });
+});
+test("set replaces existing pointer (last writer wins)", () => {
+    withTmpProject((cwd, manifestPath) => {
+        const otherManifest = join(cwd, "other.yaml");
+        writeFileSync(otherManifest, "schema_version: \"5\"\n");
+        setActiveManifest(manifestPath, { cwd, setBy: "first" });
+        setActiveManifest(otherManifest, { cwd, setBy: "second" });
+        const got = getActiveManifest(cwd);
+        if (!got)
+            throw new Error("expected pointer");
+        if (got.manifest_path !== otherManifest) {
+            throw new Error(`expected second writer to win, got ${got.manifest_path}`);
+        }
+        if (got.set_by !== "second")
+            throw new Error(`set_by should be 'second', got ${got.set_by}`);
+    });
+});
+console.log(`\n=== ${passed} passed, ${failed} failed ===`);
+if (failed > 0) {
+    console.log("\nFailures:");
+    fails.forEach((f) => console.log("  - " + f));
+    process.exit(1);
+}
+process.exit(0);