nitm-ai-dev-toolkit 4.0.0 → 5.0.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.0.0]
+
+### Breaking
+
+- `/tasks` now writes a slim `tasks.md`: one checklist line per task (checkbox, ID, short description, optional `[P]`, optional ` — <ticket key>`). Details stay in `spec.md` and `plan.md`. `/assign-tasks` and `/implement-feature` read the slim lines and write ticket keys back after the em dash. Existing `tasks.md` files are not rewritten; re-run `/tasks` on a feature to convert one.
+- `upgrade` no longer overwrites your files. It used to run `install --force`. It now adds missing files and keeps existing ones (`patch` semantics), then re-emits the bootstrap handoff. Overwriting needs an explicit `upgrade --force`, which prints a warning first. Scripts that relied on `upgrade` to refresh templates must add `--force`.
+
+### Added
+
+- Factory pipeline (opt-in): `/factory <request>` takes a feature through intake, spec gate, plan gate, build, parallel lens reviews, approval, and local merge, with subcommands `start`, `approve`, `rework`, `status`, and `watch`. Nothing runs until `/factory` is invoked. Job state lives in `factory/jobs/`, which is git-ignored. Entry points ship for Claude Code, GitHub Copilot, Cursor, and OpenCode; Codex uses the orchestrator skill `.agents/skills/factory/SKILL.md`.
+- Factory gates and intake: intake reads `AGENTS.md`, related features in `docs/features/`, and the code it touches, asks at most five glaring questions, and saves the answers to `intake.md`. Every job stops at `awaiting-spec` and `awaiting-plan` in every approval mode, and nothing is ticketed or built before the operator confirms the plan. Change requests are saved as `spec-<k>.md` or `plan-<k>.md`.
+- Factory feature folders and tracking: each job belongs to `docs/features/<KEY>-<slug>/` (or `docs/features/<slug>/` before a ticket exists). `job.json` records `feature_dir`, `issue_key`, `size`, `tracking`, and `worktree`. Large work with a documented tracker creates tickets through `/assign-tasks`, writes their keys onto `tasks.md`, and moves them through In Progress, In Review, and Done. Done only follows `/factory approve`.
+- Factory builds run in a git worktree on `factory/<id>`. `--in-place` builds in the main checkout instead, and only from a clean default branch with no other in-place job open. The builder writes `qa.md` with suggested checks, printed before approval; it never gates anything.
+- Factory agents: `factory-spec-writer`, `factory-builder`, `factory-reviewer-code`, `factory-reviewer-security`, `factory-reviewer-ux`, `factory-reviewer-ui`, and `factory-approver`, with shared snippets in `.claude/agents-snippets/`. Their OpenCode wrappers use native V2 `permissions`.
+- `factory/` template folder (README, `_gitignore`) installed by default. CLI `factory status` (one-shot table) and `factory watch` (live view) are read-only over `factory/jobs/*/job.json`; `abandoned` jobs are shown as closed.
+- Factory `/factory archive [--all] [--dry-run]` moves closed jobs (`merged` or `abandoned`) from `factory/jobs/` to `factory/archive/`. By default only jobs last updated more than 7 days ago move. `--all` moves every closed job, and open jobs never move. CLI `factory archive` makes the same moves. `/factory archive` also asks before deleting an archived abandoned job's branch and worktree, and never pushes. Archived jobs are not resumable (`/factory start` says they are closed), and their ids count toward job numbering until a prune removes them.
+- Factory `/factory prune [--all] [--abandoned] [--dry-run]` permanently deletes closed jobs from `factory/jobs/` and `factory/archive/`. By default only `merged` jobs are deleted, and only those last updated more than 7 days ago. `--all` drops the age limit for merged jobs. `--abandoned` also deletes `abandoned` jobs under the same age rule. Without it, abandoned jobs are kept and counted, and the flow offers to rerun with `--abandoned`. It lists the candidates, asks once in chat, and deletes only after a yes. When abandoned jobs are pruned, it then asks, per abandoned branch, whether to delete the branch and its worktree, as archive does. Open jobs and `docs/features/` are never touched. `/factory archive` keeps its selection: merged and abandoned. CLI `factory prune` lists by default and deletes with `--yes`; `--abandoned` is accepted only by `factory prune`.
+- Link checks in `test/links.test.js`: every relative markdown link and `@path` import in `src/repo` and `src/monorepo` must resolve, and so must every scoped install (each `--env` × layout).
+
+### Changed
+
+- Factory dashboard: `factory status` and `factory watch` hide closed jobs by default and print `N closed jobs hidden (--all to show)`. `--all` shows closed jobs and archived ones.
+- Scoped installs (`--env`) also copy `.agents/skills/`, `.claude/agents-snippets/`, `.claude/prompt-snippets/`, `.claude/rules-snippets/`, and `factory/`, the shared references every harness's wrappers use.
+- Templates named `_gitignore` install as `.gitignore`, because npm drops `.gitignore` files from packages.
+- Releases publish through npm trusted publishing (OIDC, with provenance) from `.github/workflows/publish.yml`, which now also does the auto patch bump and tag (`auto-patch-tag.yml` removed). The `NPM_TOKEN` secret is no longer used.
+
+### Fixed
+
+- Scoped Cursor, Copilot, and OpenCode installs no longer leave dangling links: `.claude/rules-snippets/` is now shared by every scope, since Cursor rules link there.
+- Scoped installs share only `.agents/skills/`, so Claude/Codex ambient rules in `.agents/rules/` no longer appear in Cursor, Copilot, or OpenCode installs.
+- `doctor` placeholder scan matches names with digits (for example `{{DB2_HOST}}`), skips `templates/` blank forms, and ignores runtime-only placeholders (`ISSUE_ID`, `ISSUE_KEY`, `FEATURE_NAME`, `NAME`), so a bootstrapped project can report clean.
+- `.cursor/rules/orient-to-recent-work.mdc` skill link now resolves (`../` → `../../`).
+
+## [4.0.0]
+
 ### Migration
 
 - Toolkit v4 / package 4.0.0 requires native OpenCode V2 for OpenCode use; oh-my-opencode-slim >=3.0.0 requires OpenCode >=2.0.7. Native host config uses plural maps, ordered permissions, skill directories, and `mcp.servers`. Back up V1 (converted files are incompatible with it), preserve user/global settings and Slim's separate strict schema, leave the external starter unchanged, and activate on the next run/restart. Config `instructions` are ignored, ambient `AGENTS.md` works, `@refs` require explicit reads, and `request.body.temperature` is preserved but not currently sent by the runner. Preserve `lsp: true`; use project checks, not unavailable V2 LSP tools. Plugin/runtime integration is untested; publishing has not been executed.
@@ -118,5 +153,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Documentation structure templates (`docs/features/`, `docs/fixes/`)
 - Monthly fix log template
 
-[Unreleased]: https://github.com/ninjasitm/ai-assisted-dev-toolkit/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/ninjasitm/ai-assisted-dev-toolkit/compare/v4.0.0...HEAD
+[4.0.0]: https://github.com/ninjasitm/ai-assisted-dev-toolkit/compare/v3.0.23...v4.0.0
 [0.1.0]: https://github.com/ninjasitm/ai-assisted-dev-toolkit/releases/tag/v0.1.0

package/README.md

@@ -36,6 +36,7 @@ This repository serves as a **template source** for AI development instructions
 │   │   │   ├── rules/  # Agent behavior rules (ponytail, etc.)
 │   │   │   └── skills/ # Bundled skills (TDD, debugging, etc.)
 │   │   ├── docs/       # Documentation structure templates
+│   │   ├── factory/    # Opt-in factory pipeline (README, .gitignore)
 │   │   ├── templates/  # Reusable document templates
 │   │   ├── AGENTS.md   # AI agent context template
 │   │   └── README.md   # Project README template
@@ -59,6 +60,7 @@ This repository serves as a **template source** for AI development instructions
 │       ├── apps/       # App-specific templates
 │       ├── packages/   # Package-specific templates
 │       ├── docs/       # Documentation structure templates
+│       ├── factory/    # Opt-in factory pipeline (README, .gitignore)
 │       ├── templates/  # Reusable document templates
 │       └── AGENTS.md   # Monorepo agent context
 │
@@ -172,9 +174,12 @@ npx nitm-ai-dev-toolkit patch
 # Inspect the install: missing files and unresolved placeholders
 npx nitm-ai-dev-toolkit doctor
 
-# Upgrade to the latest published version
+# Upgrade to the latest published version: adds missing files and keeps your existing ones
 npx nitm-ai-dev-toolkit upgrade
 
+# Also overwrite existing files with the latest templates (back up customisations first)
+npx nitm-ai-dev-toolkit upgrade --force
+
 # Scaffold the oh-my-opencode-slim starter (delegates to `npx nitm-opencode-starter install`)
 npx nitm-ai-dev-toolkit omo-slim-starter install
 ```
@@ -214,7 +219,7 @@ Follow official V2 [migration](https://opencode.ai/v2/docs/migrate-v1), [config]
 
 ### Native Codex
 
-- `--env codex` includes `.codex/`, `.agents/`, and shared context, plus `.github/instructions/` and `.claude/rules-snippets/` solely to supply the standards linked from `AGENTS.md` and those standards' wrapper source content. It does not install other harness command, agent, or config directories. These reference files neither establish Copilot/Claude use nor load automatically as Codex rules; other harness scopes are unchanged.
+- `--env codex` includes `.codex/`, `.agents/`, and shared context, plus `.github/instructions/` solely to supply the standards linked from `AGENTS.md`. The shared `.claude/rules-snippets/` standards are installed in every scope, so those standards' wrapper source content is present too. It does not install other harness command, agent, or config directories. These reference files neither establish Copilot/Claude use nor load automatically as Codex rules; other harness scopes are unchanged.
 - Codex reads `AGENTS.md` and discovers `.agents/skills/*/SKILL.md` natively. Monorepos can use more-specific nested `AGENTS.md` files for app/package guidance. Linked standards are references to read as needed, not automatically loaded Claude/Copilot rules.
 - The optional `.codex/config.toml` is deliberately comment-only: it preserves the user's inherited defaults. Codex loads project config only after the user explicitly trusts the project; the toolkit does not grant trust or set model/provider, approval, sandbox, security, or feature overrides.
 - For manual copies without `.nitm/`, provide `.claude/prompt-snippets/bootstrap.md` to Codex directly. For incremental AI-guided merges, provide `.claude/prompt-snippets/bootstrap-patch.md` as a task document; the CLI `patch` command only adds missing files.
@@ -238,6 +243,7 @@ Templates use `{{PLACEHOLDER}}` syntax for values you need to customize. The boo
 | `{{PACKAGE_MANAGER}}`     | Package manager           | `npm`, `composer`, `dotnet`, `pip`, `bundler`, `go`, `cargo`, `maven` |
 | `{{FILE_EXTENSION}}`      | File extension            | `ts`, `php`, `cs`, `py`, `rb`, `go`, `rs`, `java`                     |
 | `{{DEV_PORT}}`            | Development server port   | `3000`, `8000`, `5000`                                                |
+| `{{DEV_PORT_FLAG}}`       | Flag or env var that sets the dev port | `--port 3000`, `PORT=3000`                                |
 | `{{DEPLOY_PLATFORM}}`     | Deployment target         | `Vercel`, `AWS`, `Azure`, `Heroku`                                    |
 | `{{DATABASE}}`            | Database/ORM              | `Prisma`, `Eloquent`, `EF Core`, `SQLAlchemy`, `ActiveRecord`         |
 | `{{TEST_FRAMEWORK}}`      | Testing framework         | `Vitest`, `PHPUnit`, `xUnit`, `pytest`, `RSpec`, `JUnit`              |
@@ -260,6 +266,7 @@ Templates use `{{PLACEHOLDER}}` syntax for values you need to customize. The boo
 | Placeholder           | Description          | Example                                             |
 | --------------------- | -------------------- | --------------------------------------------------- |
 | `{{INSTALL_COMMAND}}` | Install dependencies | `npm install`, `composer install`, `dotnet restore` |
+| `{{SETUP_COMMAND}}`   | Install command      | `npm install`, `composer install`, `dotnet restore` |
 | `{{DEV_COMMAND}}`     | Run dev server       | `npm run dev`, `php artisan serve`, `dotnet watch`  |
 | `{{BUILD_COMMAND}}`   | Build for production | `npm run build`, `dotnet publish`                   |
 | `{{TEST_COMMAND}}`    | Run tests            | `npm test`, `./vendor/bin/phpunit`, `dotnet test`   |
@@ -291,6 +298,17 @@ Templates use `{{PLACEHOLDER}}` syntax for values you need to customize. The boo
 | `{{APP_3}}`                 | Third app name             | `web`, `marketing`, `landing`                           |
 | `{{PROJECT_STRUCTURE}}`     | Full project structure     | (Generated tree diagram)                                |
 
+### Factory Placeholders
+
+Used by the opt-in factory (`.agents/skills/factory/SKILL.md` and `.claude/agents-snippets/factory-*.md`).
+
+| Placeholder                 | Description                                                                                 | Example                  |
+| --------------------------- | ------------------------------------------------------------------------------------------- | ------------------------ |
+| `{{DEFAULT_BRANCH}}`        | Branch factory jobs start from and merge into                                               | `main`, `master`         |
+| `{{FACTORY_PORT_BASE}}`     | Base dev-server port. Job `n` uses `base + 10n` for the builder, `+1` for ux, and `+2` for ui | `5100`                   |
+| `{{APPROVAL_MODE}}`         | `human` stops at `awaiting-human`; `auto` merges on approval                                | `human`, `auto`          |
+| `{{FACTORY_REVIEW_LENSES}}` | Review lenses to run. `ux` and `ui` need browser tooling                                    | `code, security`         |
+
 ## Supported Ecosystems
 
 The bootstrap command supports the following language ecosystems:
@@ -616,6 +634,43 @@ The bundled skills complement custom agents:
 - **`writing-plans`** — Creating the plans that Feature Builder and TDD agents execute
 - **`test-driven-development`** — The TDD methodology that Red/Green/Refactor agents implement
 
+## Factory (opt-in, v5)
+
+The factory is an opt-in pipeline for feature-sized work. One orchestrator takes a feature through spec → plan gate → build → review → approve → merge. Each job belongs to a feature folder, `docs/features/<KEY>-<slug>/` (or `docs/features/<slug>/` before a ticket exists), which holds `spec.md` and, for large work, a slim `tasks.md`. Job state lives under `factory/jobs/<NNN-slug>/`, and each job builds in its own git worktree on branch `factory/<id>` (or in place on the job's branch, when you ask for `--in-place`).
+
+It runs alongside Feature Builder and TDD and does not replace them. Nothing runs until you invoke `/factory`. Quick fixes stay direct.
+
+- **Agents:** `factory-spec-writer`, `factory-builder`, `factory-reviewer-code`, `factory-reviewer-security`, `factory-reviewer-ux`, `factory-reviewer-ui`, and `factory-approver`. Wrappers ship for Claude Code, GitHub Copilot, Cursor, and OpenCode. Codex uses the orchestrator skill only.
+- **Setup and reference:** [`src/repo/factory/README.md`](src/repo/factory/README.md) (the monorepo copy is in `src/monorepo/factory/`). The installer copies `factory/` into your project.
+
+| Command | What it does |
+| --- | --- |
+| `/factory <feature request>` | Intake: reads the project and the features it touches, asks only the glaring questions, then asks you to continue or change the answers. Nothing is created before you continue |
+| `/factory start <KEY \| slug \| job-id>` | Pick up an existing feature folder by ticket key or slug, or resume its open job (for example one waiting at a gate). Add `--in-place` only for a new job |
+| `/factory approve <job-id>` | Merge a job waiting for you (`awaiting-human` or `needs-human`); on a `merged` job, move its tickets to Done |
+| `/factory rework <job-id> <note>` | Restart the builder with your note and a fresh retry budget |
+| `/factory status [--all]` | Summarize open jobs (read-only). Closed jobs are hidden unless `--all` |
+| `/factory watch [--all]` | Show the status table here, then print the command to run the live view in your terminal (read-only). Closed jobs are hidden unless `--all` |
+| `/factory archive [--all] [--dry-run]` | Move closed jobs (`merged` or `abandoned`) from `factory/jobs/` to `factory/archive/`. By default only jobs not updated for 7 days move. `--dry-run` moves nothing. Open jobs never move |
+| `/factory prune [--all] [--abandoned] [--dry-run]` | Permanently delete closed jobs from `factory/jobs/` and `factory/archive/`, after one confirmation. By default only `merged` jobs (same 7-day age rule as archive; `--all` drops the age limit). `--abandoned` also deletes `abandoned` jobs. Open jobs and `docs/features/` are never touched |
+
+**Two gates are mandatory.** Every job stops at `awaiting-spec` after the spec, and at `awaiting-plan` after the plan. At the spec gate you confirm the spec or request changes. At the plan gate you review the tasks, the size, the tracking proposal, and the build mode, then confirm or request changes. Leave either gate for later with `/factory start <job-id>`. Nothing is ticketed or built before you confirm the plan.
+
+**The builder also writes `qa.md`.** It lists how to run the feature, numbered manual checks tied to the acceptance criteria, and what the automated tests do not cover. The orchestrator shows it before approval as suggested checks. It is not a gate.
+
+**The approval gate is on by default.** With `{{APPROVAL_MODE}}` set to `human`, an approved job stops at `awaiting-human` until you run `/factory approve <job-id>`. Set `{{APPROVAL_MODE}}` to `auto` to merge on approval instead. The approver still escalates changes to auth, payments, migrations, and similar high-risk areas. Merges are local, and the factory never pushes.
+
+Check jobs from a terminal:
+
+```bash
+npx nitm-ai-dev-toolkit factory status [--all]        # one-shot table of open jobs (--all: closed too)
+npx nitm-ai-dev-toolkit factory watch [--all]         # live view: ↑/↓ to select, Enter to open, q to quit
+npx nitm-ai-dev-toolkit factory archive [--all] [--dry-run]   # move closed jobs to factory/archive/
+npx nitm-ai-dev-toolkit factory prune [--all] [--abandoned] [--dry-run]   # list merged jobs to delete; add --yes to delete them
+```
+
+`status` and `watch` read `factory/jobs/*/job.json`, write nothing, and hide closed jobs unless `--all` is passed. `archive` moves closed jobs and touches no git state. `prune` permanently deletes merged jobs from both folders, after you confirm. Pass `--abandoned` to delete abandoned jobs too. Neither touches open jobs or `docs/features/`. The factory's placeholders are listed under [Factory Placeholders](#factory-placeholders).
+
 ## AI Agent Skills
 
 Enhance your AI agents with specialized capabilities using the **Agent Skills** open format. Skills are folders of instructions, scripts, and resources that agents can discover and use to perform tasks more accurately and efficiently.
@@ -693,7 +748,7 @@ Skills are installed to `{.cursor|.agents|.github}/skills/` and automatically av
 
 ### Bundled Universal Skills
 
-This toolkit includes **32 pre-installed universal skills** in the `.agents/skills/` folder. These skills are copied automatically when you set up your project and require **no additional installation**.
+This toolkit includes **33 pre-installed universal skills** in the `.agents/skills/` folder. These skills are copied automatically when you set up your project and require **no additional installation**.
 
 | Skill                              | Description                                                                                          |
 | ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
@@ -702,6 +757,7 @@ This toolkit includes **32 pre-installed universal skills** in the `.agents/skil
 | **verification-before-completion** | Quality checks before claiming work is done. Evidence before assertions, always.                     |
 | **writing-plans**                  | Creating clear implementation plans before coding.                                                   |
 | **executing-plans**                | Following through on implementation plans systematically.                                            |
+| **factory**                        | Opt-in spec-to-merge feature pipeline with review lenses and an approval gate.                       |
 | **requesting-code-review**         | Best practices for requesting code reviews from teammates.                                           |
 | **receiving-code-review**          | Responding constructively to review feedback.                                                        |
 | **brainstorming**                  | Structured ideation and problem-solving sessions.                                                    |
@@ -893,7 +949,7 @@ After copying templates and installing additional skills, your project will have
     │   └── SKILL.md
     ├── verification-before-completion/
     │   └── SKILL.md
-    └── ... (32 skills total)
+    └── ... (33 skills total)
 
 .cursor/                  # or .github/ for GitHub Copilot
 ├── rules/                # IDE behavior rules (from this toolkit)

package/bin/cli.js

@@ -9,6 +9,9 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync, spawnSync } = require('child_process');
+const factory = require('./factory-watch.js');
+const factoryArchive = require('./factory-archive.js');
+const factoryPrune = require('./factory-prune.js');
 
 const PKG_ROOT = path.join(__dirname, '..');
 const SRC_DIR = path.join(PKG_ROOT, 'src');
@@ -16,13 +19,13 @@ const SRC_DIR = path.join(PKG_ROOT, 'src');
 // Platform config dirs per harness. Claude and Codex share `.agents` (universal skills).
 const ENV_DIRS = {
   claude: ['.claude', '.agents'],
-  codex: ['.codex', '.agents', path.join('.github', 'instructions'), path.join('.claude', 'rules-snippets')],
+  codex: ['.codex', '.agents', path.join('.github', 'instructions')],
   copilot: ['.github', '.vscode'],
   cursor: ['.cursor'],
   // Shared reference sources, not other harnesses' active config/agent wrappers.
   opencode: ['.opencode', path.join('.agents', 'skills'),
     path.join('.claude', 'agents-snippets'), path.join('.claude', 'prompt-snippets'),
-    path.join('.claude', 'rules-snippets'), path.join('.github', 'instructions')],
+    path.join('.github', 'instructions')],
 };
 const ENV_INFO = {
   claude: { name: 'Claude Code', command: '/bootstrap (Claude Code command in .claude/commands/)' },
@@ -33,8 +36,17 @@ const ENV_INFO = {
 };
 // Files/dirs copied for every environment (shared across harnesses).
 const SHARED_ROOT = ['AGENTS.md', 'README.md', 'CLAUDE.md', '.mcp.json'];
-const SHARED_DIRS = ['docs', 'templates', 'hooks'];
-
+// `factory` is the job queue every harness reads and writes, so it is shared.
+// Agent/skill bodies and prompt snippets are referenced by wrappers in every harness
+// (e.g. `.claude/agents-snippets/*` from Cursor and Copilot agents), so they are shared too.
+// `.claude/rules-snippets` is linked the same way from every harness's rules and instructions.
+// Only `.agents/skills` is shared: `.agents/rules` is Claude/Codex ambient config.
+const SHARED_DIRS = ['docs', 'templates', 'hooks', 'factory', path.join('.agents', 'skills'),
+  path.join('.claude', 'agents-snippets'), path.join('.claude', 'prompt-snippets'),
+  path.join('.claude', 'rules-snippets')];
+// npm drops `.gitignore` files from packages, so templates ship them as `_gitignore`
+// and install them under the real name.
+const TEMPLATE_RENAMES = { '_gitignore': '.gitignore' };
 const C = {
   reset: '\x1b[0m',
   cyan: '\x1b[36m',
@@ -85,6 +97,12 @@ function templateFiles(type) {
   return files;
 }
 
+// Path a template file is installed to (see TEMPLATE_RENAMES).
+function installName(rel) {
+  const renamed = TEMPLATE_RENAMES[path.basename(rel)];
+  return renamed ? path.join(path.dirname(rel), renamed) : rel;
+}
+
 // Restrict the file set to the chosen environment (shared + that env's dirs).
 function scopeFiles(files, env) {
   if (!env || !ENV_DIRS[env]) return files;
@@ -105,7 +123,8 @@ function copyMissing(type, cwd, force, env) {
   let skipped = 0;
   for (const rel of files) {
     const from = path.join(src, rel);
-    const to = path.join(cwd, rel);
+    const dest = installName(rel);
+    const to = path.join(cwd, dest);
     if (fs.existsSync(to) && !force) {
       skipped++;
       continue;
@@ -130,7 +149,8 @@ function conflicts(type, cwd, env) {
   const files = scopeFiles(templateFiles(type), env);
   const out = [];
   for (const rel of files) {
-    if (fs.existsSync(path.join(cwd, rel))) out.push(rel);
+    const dest = installName(rel);
+    if (fs.existsSync(path.join(cwd, dest))) out.push(dest);
   }
   return out;
 }
@@ -219,14 +239,25 @@ function cmdPatch(cwd, flags) {
   return { copied, skipped };
 }
 
+// Placeholders the agent fills per task or feature at runtime, so they are not bootstrap leftovers.
+const RUNTIME_PLACEHOLDERS = new Set(['ISSUE_ID', 'ISSUE_KEY', 'FEATURE_NAME', 'NAME']);
+// `templates/` ships blank forms whose placeholders are meant to stay until a feature is written.
+const PLACEHOLDER_EXEMPT_DIR = 'templates';
+
+function hasUnresolvedPlaceholder(content) {
+  const names = content.match(/\{\{[A-Z][A-Z0-9_]*\}\}/g) || [];
+  return names.some((name) => !RUNTIME_PLACEHOLDERS.has(name.slice(2, -2)));
+}
+
 function scanPlaceholders(cwd, relFiles) {
   const found = [];
   for (const rel of relFiles) {
+    if (path.normalize(rel).split(path.sep)[0] === PLACEHOLDER_EXEMPT_DIR) continue;
     const p = path.join(cwd, rel);
     if (!fs.existsSync(p)) continue;
     try {
       const content = fs.readFileSync(p, 'utf8');
-      if (/\{\{[A-Z_]+\}\}/.test(content)) found.push(rel);
+      if (hasUnresolvedPlaceholder(content)) found.push(rel);
     } catch (_) { /* ignore */ }
   }
   return found;
@@ -234,7 +265,7 @@ function scanPlaceholders(cwd, relFiles) {
 
 function cmdDoctor(cwd, flags) {
   const type = detectType(cwd, flags);
-  const files = scopeFiles(templateFiles(type), flags.env);
+  const files = scopeFiles(templateFiles(type), flags.env).map(installName);
   const missingFiles = [];
   let present = 0;
   for (const rel of files) {
@@ -261,6 +292,16 @@ function cmdDoctor(cwd, flags) {
   return result;
 }
 
+// Upgrade runs the latest package in patch mode: missing files are added and existing
+// (possibly customised) files are kept. Only an explicit --force reaches `install --force`.
+function upgradeArgs(flags) {
+  const force = Boolean(flags && flags.force);
+  const args = ['--yes', 'nitm-ai-dev-toolkit@latest', force ? 'install' : 'patch'];
+  if (force) args.push('--force');
+  if (flags && flags.env) args.push('--env', flags.env);
+  return args;
+}
+
 function cmdUpgrade(cwd, flags) {
   let latest;
   try {
@@ -275,17 +316,17 @@ function cmdUpgrade(cwd, flags) {
   } catch (_) {
     cur = 'unknown';
   }
-  if (latest === cur) {
-    ok(`Already on latest version (${cur}).`);
-    return;
+  if (latest === cur) info(`Already on latest version (${cur}); refreshing missing files and the handoff.`);
+  else info(`New version available: ${latest} (current ${cur}).`);
+  if (flags && flags.force) {
+    warn('--force: existing files will be overwritten with the latest templates. Back up your customisations first.');
+  } else {
+    info('Adding missing files only; your existing files are kept. Pass --force to overwrite them.');
   }
-  info(`New version available: ${latest} (current ${cur}).`);
   info('Upgrading via latest package...');
-  const args = ['--yes', 'nitm-ai-dev-toolkit@latest', 'install', '--force'];
-  if (flags && flags.env) args.push('--env', flags.env);
-  const r = spawnSync('npx', args, { cwd, stdio: 'inherit', timeout: 120000 });
+  const r = spawnSync('npx', upgradeArgs(flags), { cwd, stdio: 'inherit', timeout: 120000 });
   if (r.error) { err('Upgrade failed: ' + r.error.message); return; }
-  if (r.status === 0) ok('Upgrade complete.');
+  if (r.status === 0) ok('Upgrade complete. Hand off to your AI agent with .nitm/BOOTSTRAP.md to finish setup.');
   else err('Upgrade failed.');
 }
 
@@ -306,6 +347,38 @@ function cmdOmoStarter(cwd, flags) {
   }
 }
 
+const FACTORY_USAGE = 'Usage: nitm-ai-dev-toolkit factory <status|watch|archive|prune> [--dir <path>] [--all] [--abandoned] [--interval <ms>] [--dry-run] [--yes]';
+const FACTORY_SUB_USAGE = {
+  archive: 'Usage: nitm-ai-dev-toolkit factory archive [--dir <path>] [--all] [--dry-run]',
+  prune: 'Usage: nitm-ai-dev-toolkit factory prune [--dir <path>] [--all] [--abandoned] [--dry-run] [--yes]',
+};
+
+function cmdFactory(cwd, flags) {
+  const sub = flags._[1];
+  // --abandoned changes what prune deletes; elsewhere it would be a silent no-op, so refuse it.
+  if (flags.abandoned && sub !== 'prune') {
+    err('--abandoned is only for factory prune');
+    process.exitCode = 1;
+    return;
+  }
+  if (sub === 'status') return factory.cmdFactoryStatus(cwd, flags);
+  if (sub === 'watch') return factory.cmdFactoryWatch(cwd, flags);
+  if (sub === 'archive' || sub === 'prune') {
+    const extra = flags._.slice(2);
+    if (extra.length) {
+      err(`Unknown option for factory ${sub}: ${extra[0]}`);
+      err(FACTORY_SUB_USAGE[sub]);
+      process.exitCode = 1;
+      return;
+    }
+    return sub === 'archive'
+      ? factoryArchive.cmdFactoryArchive(cwd, flags)
+      : factoryPrune.cmdFactoryPrune(cwd, flags);
+  }
+  err(FACTORY_USAGE);
+  process.exitCode = 1;
+}
+
 function parseFlags(argv) {
   const flags = { _: [] };
   for (let i = 0; i < argv.length; i++) {
@@ -313,7 +386,21 @@ function parseFlags(argv) {
     if (a === '--monorepo') flags.monorepo = true;
     else if (a === '--repo') flags.repo = true;
     else if (a === '--force' || a === '-f') flags.force = true;
+    else if (a === '--all') flags.all = true;
+    else if (a === '--dry-run') flags.dryRun = true;
+    else if (a === '--yes') flags.yes = true;
+    else if (a === '--abandoned') flags.abandoned = true;
     else if (a === '--help' || a === '-h') flags.help = true;
+    else if (a === '--dir' || a === '--interval') {
+      const v = argv[++i];
+      if (v === undefined || v.startsWith('--')) throw new Error(`${a} requires a value`);
+      flags[a.slice(2)] = v;
+    } else if (a.startsWith('--dir=') || a.startsWith('--interval=')) {
+      const eq = a.indexOf('=');
+      const v = a.slice(eq + 1);
+      if (!v) throw new Error(`${a.slice(0, eq)}= requires a value`);
+      flags[a.slice(2, eq)] = v;
+    }
     else if (a === '--env') {
       const v = argv[++i];
       if (v === undefined || v.startsWith('--')) throw new Error('--env requires a value (e.g. --env claude)');
@@ -341,8 +428,10 @@ Usage:
       Add only missing template files (never overwrites existing ones), then
       re-emit the bootstrap handoff so your AI agent can finish configuration.
 
-  npx nitm-ai-dev-toolkit upgrade
-      Upgrade to the latest published version (re-scaffolds via @latest).
+  npx nitm-ai-dev-toolkit upgrade [--env <env>] [--force]
+      Upgrade to the latest published version. Like \`patch\`, adds missing files and
+      keeps your existing ones, then re-emits the bootstrap handoff. --force also
+      overwrites existing files with the latest templates (back up customisations first).
 
   npx nitm-ai-dev-toolkit doctor [--monorepo|--repo] [--env <env>]
       Inspect the current install: missing files, unresolved {{PLACEHOLDER}}
@@ -352,6 +441,31 @@ Usage:
       Run \`npx nitm-opencode-starter install\` to scaffold the oh-my-opencode-slim
       starter (published to npm). Falls back to printing the command if unavailable.
 
+  npx nitm-ai-dev-toolkit factory status [--dir <path>] [--all]
+      Print one table of factory jobs (factory/jobs/<NNN-slug>/job.json), then exit.
+      Closed jobs (merged, abandoned) are hidden and counted; --all shows them,
+      plus archived jobs from factory/archive/ (marked [archived]).
+      Read-only. Run /factory <feature> in your agent to create jobs.
+
+  npx nitm-ai-dev-toolkit factory watch [--dir <path>] [--interval <ms>] [--all]
+      Live terminal view of factory jobs. ↑/↓ or j/k select, Enter opens a job's
+      markdown files, q quits. Closed jobs are hidden unless --all.
+      Not a TTY? Behaves like \`factory status\`.
+
+  npx nitm-ai-dev-toolkit factory archive [--dir <path>] [--all] [--dry-run]
+      Move closed jobs (merged, abandoned) from factory/jobs/ to factory/archive/.
+      Default: only jobs closed more than 7 days ago. --all: every closed job.
+      --dry-run: list what would move, move nothing. Open jobs are never touched.
+      Does not touch git or branches (/factory archive and /factory prune handle those).
+
+  npx nitm-ai-dev-toolkit factory prune [--dir <path>] [--all] [--abandoned] [--dry-run] [--yes]
+      PERMANENTLY delete closed jobs from factory/jobs/ and factory/archive/.
+      Default: only merged jobs closed more than 7 days ago. --all: every merged job
+      (no age limit). --abandoned: also delete abandoned jobs (same age rule).
+      Without --yes it only lists what would be deleted. --dry-run always only
+      lists, even with --yes. Open jobs are never touched. Deletes job folders only;
+      git, docs and branches are not touched.
+
 Options:
   --env <env>  Optional. Limit the scaffold to ONE harness:
                claude | codex | copilot | cursor | opencode
@@ -361,26 +475,36 @@ Options:
                file directly (no native /bootstrap command is provided).
   --monorepo   Force monorepo template
   --repo       Force single-repo template
-  --force      Overwrite existing files
+  --force      Overwrite existing files (install, upgrade). patch never overwrites
+  --dir <path> factory: jobs directory (default: ./factory/jobs)
+  --interval <ms>
+               factory watch: refresh interval (default: 2000, minimum: 100)
+  --all        factory status/watch: include closed and archived jobs
+               factory archive: include every closed job, not just those older than 7 days
+               factory prune: include every merged job, not just those older than 7 days
+  --abandoned  factory prune: also delete abandoned jobs (default: merged only)
+  --dry-run    factory archive/prune: list only, change nothing
+  --yes        factory prune: actually delete (without it, prune only lists)
   -h, --help   Show this help
 `);
 }
 
 function main() {
-  const flags = parseFlags(process.argv.slice(2));
-  if (flags.help) {
-    usage();
-    return;
-  }
-  const cmd = flags._[0];
   const cwd = process.cwd();
   try {
+    const flags = parseFlags(process.argv.slice(2));
+    if (flags.help) {
+      usage();
+      return;
+    }
+    const cmd = flags._[0];
     switch (cmd) {
       case 'install': return cmdInstall(cwd, flags);
       case 'patch': return cmdPatch(cwd, flags);
       case 'upgrade': return cmdUpgrade(cwd, flags);
       case 'doctor': return cmdDoctor(cwd, flags);
       case 'omo-slim-starter': return cmdOmoStarter(cwd, flags);
+      case 'factory': return cmdFactory(cwd, flags);
       default:
         if (cmd) err(`Unknown command: ${cmd}`);
         usage();
@@ -397,6 +521,7 @@ module.exports = {
   detectType,
   scopeFiles,
   templateFiles,
+  installName,
   copyMissing,
   scanPlaceholders,
   envHeader,
@@ -406,7 +531,9 @@ module.exports = {
   cmdPatch,
   cmdDoctor,
   cmdUpgrade,
+  upgradeArgs,
   cmdOmoStarter,
+  cmdFactory,
   ENV_DIRS,
   SHARED_ROOT,
   SHARED_DIRS,

package/bin/factory-archive.js

@@ -0,0 +1,71 @@
+'use strict';
+
+// `factory archive`: moves closed jobs (merged, abandoned) from factory/jobs/<id>/
+// to factory/archive/<id>/. Default only archives jobs closed more than 7 days ago;
+// --all archives every closed job. Open jobs are never touched. Stdlib only.
+// Selection is shared with `factory prune` (factory.selectClosedJobs).
+// Never touches git or branches: those are left to /factory archive and /factory prune.
+
+const fs = require('fs');
+const path = require('path');
+const factory = require('./factory-watch.js');
+
+function cmdFactoryArchive(cwd, flags = {}, opts = {}) {
+  const stdout = opts.stdout || process.stdout;
+  const now = opts.now === undefined ? Date.now() : opts.now;
+  const all = Boolean(flags.all);
+  const dryRun = Boolean(flags.dryRun);
+  const jobsDir = factory.resolveDir(cwd, flags);
+  const archiveDir = factory.archiveDirOf(jobsDir);
+  const line = (text) => stdout.write(text + '\n');
+  const result = {
+    dir: jobsDir, archiveDir, dryRun, exists: true,
+    moved: [], skippedOpen: 0, kept: 0, skippedInvalid: [], skippedArchived: [],
+  };
+
+  const sel = factory.selectClosedJobs(jobsDir, { all, now });
+  if (!sel.exists) {
+    result.exists = false;
+    line(`• No jobs directory at ${jobsDir} — nothing to archive.`);
+    return result;
+  }
+  result.skippedOpen = sel.skippedOpen;
+  result.kept = sel.kept;
+  result.skippedInvalid = sel.skippedInvalid;
+
+  for (const c of sel.candidates) {
+    const target = path.join(archiveDir, c.id);
+    if (fs.existsSync(target)) {
+      result.skippedArchived.push(c.id);
+      continue;
+    }
+    if (!dryRun) {
+      fs.mkdirSync(archiveDir, { recursive: true });
+      fs.renameSync(c.dir, target);
+    }
+    result.moved.push({ id: c.id, stage: c.stage });
+  }
+
+  const verb = dryRun ? 'Would move' : 'Moved';
+  if (result.moved.length) {
+    line(`${verb} ${result.moved.length} closed job(s) to ${archiveDir}:`);
+    for (const { id, stage } of result.moved) line(`  ${id}  ${stage}`);
+  } else {
+    line('No closed jobs to move.');
+  }
+  line(`Skipped ${result.skippedOpen} open job(s).`);
+  if (result.skippedInvalid.length) {
+    line(`Skipped ${result.skippedInvalid.length} invalid (not moved):`);
+    for (const { id, reason } of result.skippedInvalid) line(`  ${id}  ${reason}`);
+  }
+  if (result.skippedArchived.length) {
+    line(`Skipped ${result.skippedArchived.length} already in archive (not overwritten):`);
+    for (const id of result.skippedArchived) line(`  ${id}`);
+  }
+  if (!all && result.kept) {
+    line(`Kept ${result.kept} closed job(s) newer than ${factory.DEFAULT_AGE_DAYS} days (--all moves them too).`);
+  }
+  return result;
+}
+
+module.exports = { cmdFactoryArchive };