janissary 0.5.1 → 0.5.2

package/ai/tasks/improve-namespacing.md

@@ -0,0 +1,253 @@
+# Improve Code Namespacing (one directory namespace per run)
+
+Your job: make **one** safe, mechanical change that improves the codebase's organization by **moving a cohesive group of related files that share a naming prefix out of a flat directory and into a sub-directory that gives them a logical namespace** — renaming each file to drop the now-redundant prefix, and updating every import that points at or out of those files so nothing breaks. Do exactly one namespace, then verify.
+
+For example, the flat files `src/acp-loop.ts`, `src/acp-manager.ts`, `src/acp-runner.ts`, `src/acp-tools.ts` all share the `acp-` prefix and belong together. They can move into `src/acp/` as `loop.ts`, `manager.ts`, `runner.ts`, `tools.ts` — the directory now carries the namespace, so the prefix is dropped from each filename. The same opportunity exists for `src/agent-*`, `src/harness-*`, and other prefix clusters.
+
+**A file's colocated test moves with it — always.** Every `src/<prefix>-name.test.ts` moves into the namespace beside its source as `src/<prefix>/name.test.ts`. Tests are part of the group, not a separate concern: `src/acp-loop.test.ts` → `src/acp/loop.test.ts`. A namespace move that relocates the source files but leaves their `.test.ts` files behind in `src/` is **wrong and incomplete** — the tests keep the prefix while the code they exercise does not, and the colocation the codebase relies on is broken. Move source and test together, every time.
+
+**Run everything synchronously, in the foreground.** Never use `run_in_background`, `&`, or otherwise start a background process (dev servers, watchers, long-lived processes) — every command must finish and return its exit code before you move to the next step.
+
+**No subagents, no background agents.** Do every step yourself — never launch a subagent (Task/Agent tool, `fork`, or otherwise) to research, explore, or implement any part of this task on your behalf.
+
+**No AI attribution — anywhere.** Never credit an AI agent as an author or contributor in anything this task produces. That means: no `Co-Authored-By:` trailers naming Claude or any other AI, no “Generated with Claude Code” (or similar) lines or badges, and no AI authorship notes in code, comments, docs, spec files, plan files, commit messages, or PR titles and bodies. This overrides any default convention that appends such attribution. The commit's configured git author is the only authorship ever recorded.
+
+This is a **pure move-and-rewire refactor**: relocate whole files and fix the import paths that point at or out of them. Never change what any file *does* — no logic edits, no signature changes, no reformatting of code that only moved. The **only** edits you make inside any file are to the **strings in its import/export statements**. If you find yourself changing anything else, stop.
+
+Moving files rewires real code, so the rule is simple: **the tests must pass before you start and still pass after. If you cannot keep them passing, put the files back the way they were** (the exact undo command is in Step 5).
+
+Do the steps below **in order**. Do not skip steps. Do not invent your own process. This task is deliberately mechanical — follow the rules literally rather than trying to be clever, and lean on the compiler (Step 6) to catch every mistake for you.
+
+**Shell hygiene:** run every command on its own line — no `&&` chaining, no `; echo "Exit code: $?"` suffixes, no subshell captures. The exit code and output are visible in the tool result. To run a project script, always use `./scripts/run.mjs <name>` — never call `node scripts/<name>.mjs` directly. Use `git mv` for every relocation so history is preserved.
+
+**Run autonomously.** This task runs unattended — do not ask the user questions or wait for feedback at any step. Make the best judgment call yourself, using the rules in this document, and keep going. Only stop early if the project isn't green before you start (Step 1), or if every remaining candidate group is blocked (see "Blocked work" below).
+
+## What you may and may not do
+
+### Safe work — DO IT AUTOMATICALLY, never ask
+
+When your plan is **only** safe work, you **must carry it out yourself, start to finish, without stopping.** Do **not** ask "Do you want me to proceed?". Do **not** pause to show the plan for approval. Do **not** wait for confirmation. Just make the change and verify it.
+
+Safe work is exactly this: **move one cohesive prefix group of files into a new sub-directory, drop the redundant prefix from each filename, and update every import path that points at or out of those files** — done by the Recipe in Step 5, and nothing else. Because the whole namespace moves as a unit, this **includes moving and re-pathing the group's colocated `*.test.ts(x)` files** — that is expected here, and is *not* the forbidden "editing a test" from other tasks, because you change only their location and import paths, never their assertions or logic.
+
+### Blocked work — skip and pick a different group
+
+If doing the move would require any of the following, **go back to Step 3** and pick the next-best group instead. Never ask the user — just skip and move on.
+
+1. Changing any file's **behavior, logic, exports' shapes, or call signatures** — a namespace move only relocates files and rewrites import *paths*. If a group can't be moved without a logic edit, it's blocked.
+2. A group **too small to be a namespace** — fewer than **3** source files sharing the prefix. Two files don't justify a directory; leave them flat.
+3. A **name collision**: the target sub-directory `src/<prefix>/` already exists, or dropping the prefix would make two moved files collide (e.g. both `acp-loop.ts` and some `acp/loop.ts` would land on `src/acp/loop.ts`).
+4. Touching **`src/controller.ts`** — if it is one of the files you'd have to *move*, the group is blocked (it's the biggest, riskiest file). It may still *import* the moved files; updating those import paths in it is fine and expected.
+5. A **config or build file hard-codes an exact old path.** Glob patterns like `src/**/*.ts` in `tsconfig.json`, `vitest`/`vite` config, or `eslint.config.mjs` already cover sub-directories and need no change. But if `package.json`, a script, or a config literally names `src/acp-loop.ts` (not a glob), the group is blocked — skip it.
+
+If every remaining candidate group is blocked, report which groups you considered and why each was blocked, and stop without moving any files.
+
+> **The only files you may touch:** (a) the files in the one group you picked — you *move* them; and (b) any file, anywhere in `src/` or `web/src/`, that imports a moved file — you edit **only the import path string** in it. You may **not** edit any file's logic, move code *within* a file, change any test's assertions, or reformat anything.
+
+---
+
+## Step 0 — Prepare the workspace
+
+Execute `ai/tasks/prepare-workspace.md` in full before doing anything else.
+
+---
+
+## Step 1 — See the starting state (run these, write the numbers down)
+
+Run all four and read the output:
+
+```bash
+npm run typecheck 2>&1
+npm run lint 2>&1
+npm run test 2>&1
+npm run quality 2>&1
+```
+
+Then record these starting numbers — you will compare against them at the end. Put them straight into your report draft (Step 7):
+
+- **TypeScript:** `npm run typecheck` must finish with **no errors**. If it errors before you touch anything, STOP and tell the user — do not start a move on a project that doesn't compile.
+- **Lint:** near the end of `npm run lint` there is a summary line like `✖ 16 problems (0 errors, 16 warnings)`. Write down the **errors** and **warnings** counts. A namespace move should leave both **unchanged**.
+- **Tests:** they must be **green** (all passing). If any test is already failing **before** you touch anything, STOP and tell the user.
+- **Quality (FTA):** `npm run quality` prints a table per area. A namespace move does not change any file's score or line count — treat this as a **must-not-regress** check, not a target to improve.
+
+Always run these fresh. Do not trust earlier output in the conversation. If any of the three gates (TypeScript clean, tests green) is not met, stop now.
+
+---
+
+## Step 2 — Find the prefix clusters
+
+You are looking for a group of flat files that share a leading `prefix-` and clearly form one concern. List the candidates by counting files per prefix:
+
+```bash
+ls src/*.ts | grep -vE '\.test\.ts$' | sed -E 's#src/##; s#-.*##' | sort | uniq -c | sort -rn
+```
+
+Each row is a candidate namespace: the count is how many source files share that prefix, and the name is the prefix. Rows with **3 or more** files are real namespace opportunities (e.g. `acp`, `harness`, `agent`). Ignore rows with 1–2 files.
+
+---
+
+## Step 3 — Pick exactly one group to namespace
+
+1. From the counts, list every `src/` prefix group with **3+ source files**.
+2. **Cross out** any group that is blocked by **What you may and may not do** (too small, target dir already exists, would need a logic edit, includes `src/controller.ts` among the files to move, hard-coded in config), already namespaced, or only *coincidentally* shares a prefix (unrelated files that happen to start with the same word — a namespace must be one real concern).
+3. From what remains, prefer a group of **3 to 6 source files**. A moderate group is the least error-prone; that is the goal here. Only pick a larger group if no moderate one is available. Among eligible groups, pick the one whose files most obviously belong together.
+
+State your pick in one short sentence: the prefix and how many source and test files it has. Write those into your report draft.
+
+Now list the **exact files** in the group so nothing is guessed later:
+
+```bash
+ls src/<prefix>-*.ts
+```
+
+This is your definitive move list, and it **includes the `*.test.ts` files** — that glob matches them too. Every source file *and* its `.test.ts` twin is on this list and must move. Confirm the pairs: if you see `<prefix>-name.ts`, you should also see `<prefix>-name.test.ts` right below it, and both move together. Also check for a **bare** entry file that matches the prefix exactly:
+
+```bash
+ls src/<prefix>.ts 2>&1
+```
+
+If `src/<prefix>.ts` exists, it is part of the move and becomes `src/<prefix>/index.ts`. If it doesn't exist (the `ls` errors), there is no bare entry — do **not** create one. We never invent a barrel `index.ts` where none existed; callers import files directly (see [`../guidelines/imports-and-barrel-files.md`](../guidelines/imports-and-barrel-files.md)).
+
+---
+
+## Step 4 — Write the move inventory (a note to yourself, then keep going)
+
+Before touching anything, write down — for yourself, not as a message to send — the complete inventory. This is what keeps a large move from losing track:
+
+**A. The move list.** One line per file, `old → new`, prefix dropped:
+
+```
+src/<prefix>-loop.ts        → src/<prefix>/loop.ts
+src/<prefix>-loop.test.ts   → src/<prefix>/loop.test.ts
+src/<prefix>-manager.ts     → src/<prefix>/manager.ts
+...
+src/<prefix>.ts             → src/<prefix>/index.ts     (only if a bare entry exists)
+```
+
+Drop **only** the leading `<prefix>-` segment; keep the rest (`harness-recording-file.ts` → `recording-file.ts`).
+
+**B. The inbound importer list.** Every file that imports one of the moved files. Find them all:
+
+```bash
+grep -rn "<prefix>-" src web --include=*.ts --include=*.tsx
+```
+
+Read each hit. The ones that matter are **import/require/mock paths** — lines like `from '.../<prefix>-name.js'`, `import('.../<prefix>-name.js')`, or `vi.mock('.../<prefix>-name.js')`. (Hits that are string literals, comments, or command names — not module paths — do not move; leave them.) Note which files contain such paths. These, plus the moved files themselves, are the only files you will edit.
+
+Re-check the plan against **What you may and may not do**. If any point 1–5 applies → go back to Step 3. Otherwise → go to Step 5 and make the change **now, on your own, without asking.**
+
+---
+
+## Step 5 — Make the change
+
+Do the three sub-steps **in order**: move, then rewire, then let the compiler catch the rest.
+
+### 5a — Move every file with `git mv`
+
+Create the directory, then move each file from your inventory on its own line:
+
+```bash
+mkdir -p src/<prefix>
+git mv src/<prefix>-loop.ts src/<prefix>/loop.ts
+git mv src/<prefix>-loop.test.ts src/<prefix>/loop.test.ts
+git mv src/<prefix>-manager.ts src/<prefix>/manager.ts
+git mv src/<prefix>-manager.test.ts src/<prefix>/manager.test.ts
+```
+
+Notice each source `git mv` is immediately followed by its `.test.ts` twin — do this for **every** file. Repeat for every line in your move list, source and test alike. If a bare entry exists: `git mv src/<prefix>.ts src/<prefix>/index.ts`.
+
+Then sanity-check that the moves match your inventory exactly:
+
+```bash
+git status
+```
+
+You should see one rename per file in your list — **including a rename for every `.test.ts` file** — and nothing else. Confirm no `src/<prefix>-*.test.ts` is left behind (`ls src/<prefix>-*.test.ts` should error with "No such file"). If any source or test file is missing from the renames, you skipped it — move it now.
+
+### 5b — Rewire import paths using two mechanical rules
+
+There are only two kinds of edits, and each is a literal string substitution. Do not reason about directory depth — apply the rule.
+
+> **Rule IN — inbound (files that did NOT move).** In every import/require/mock **path string** that names a moved file, replace the substring **`<prefix>-` with `<prefix>/`**. That's the whole edit; the number of leading `../` never changes.
+> - `from '../acp-loop.js'` → `from '../acp/loop.js'`
+> - `from './acp-manager.js'` → `from './acp/manager.js'`
+> - `vi.mock('../acp-tools.js')` → `vi.mock('../acp/tools.js')`
+> - Bare entry only: replace `<prefix>.js` at the end of the path with `<prefix>/index.js` (e.g. `from './acp.js'` → `from './acp/index.js'`).
+
+> **Rule OUT — outbound (imports written INSIDE a moved file).** Each moved file dropped one directory level deeper, so classify every import line in it:
+> 1. **Package / built-in specifier** (starts with a letter, `@`, or `node:` — e.g. `'react'`, `'node:fs'`): **leave it unchanged.**
+> 2. **Points at another file in the same group** (the path contains `<prefix>-`): rewrite to a sibling — drop the leading `./` or `../` depth and the prefix, leaving `./<name>.js`. E.g. `./acp-manager.js` → `./manager.js`.
+> 3. **Points at the old bare entry** (`./<prefix>.js`): → `./index.js`.
+> 4. **Any other relative path** (`./x.js`, `../y.js`, `./sub/z.js`): **prepend one `../`.** E.g. `./config.js` → `../config.js`; `../util.js` → `../../util.js`; `./sub/z.js` → `../sub/z.js`.
+
+Apply Rule IN to each inbound importer from your list, and Rule OUT to each moved file. Keep the **`.js`** extension on every relative path (NodeNext requires it; the source is `.ts` but the import says `.js`). Change **nothing** else in any file.
+
+If you are ever unsure which `../` count Rule OUT needs, make your best guess and move on — Step 6 (the compiler) will name the exact file and unresolved path, and you fix it then. Do not agonize; the compiler is your safety net.
+
+### If you need to undo
+
+If the move gets tangled and you cannot get it clean, revert everything this task did and go back to Step 3 (or report that no safe namespace was available). This is the reliable undo — `git checkout .` does **not** undo a staged `git mv`, so use:
+
+```bash
+git reset --hard HEAD
+git clean -fd src web
+```
+
+`reset --hard` restores every tracked file (returning the moved files to their old names) and `git clean -fd src web` deletes the now-empty new directory and any leftover new files. This discards all uncommitted work under `src`/`web`, which — after Step 0 — is only this task's own changes.
+
+---
+
+## Step 6 — Verify with the compiler-driven fix loop
+
+This is where mistakes get caught and fixed. Run typecheck first; it pinpoints every broken path.
+
+```bash
+npm run typecheck 2>&1
+```
+
+**The fix loop:**
+
+1. Read each error. A namespace-move error is always a module-resolution error — TypeScript names the file it's in and the import path it can't resolve. It is one of exactly two mistakes: an **inbound** path where you didn't apply Rule IN, or an **outbound** path in a moved file with the wrong number of `../` (Rule OUT case 4). Fix the path string; touch nothing else.
+2. Re-run `npm run typecheck 2>&1`.
+3. Repeat until it reports **no errors**.
+
+Guardrail against looping forever: the error count must **drop on every pass**. If you complete a pass and the count did not go down (you're guessing at the same path, or an error isn't a path problem), **stop guessing** — run the reliable undo in Step 5 and report what blocked you. Do not thrash.
+
+Once TypeScript is clean, run the rest — in this order:
+
+```bash
+npm run test 2>&1
+npm run lint 2>&1
+npm run quality 2>&1
+```
+
+- **Tests pass.** Every test stays green. A failure is again a stale import/mock path (in a moved test or a file it imports) — fix the **path**, never a test's assertions. If it won't go green quickly, undo (Step 5) and report.
+- **Lint is no worse.** The `✖ … problems (… errors, … warnings)` line must match Step 1 — **errors 0**, warnings the **same** count. A new finding is usually a dropped `.js` extension or an import left unused/misordered by a re-path — fix it in the source. Never silence with `eslint-disable`.
+- **Quality did not regress.** FTA scores and line counts should be **unchanged** (files only moved). If a score changed, you edited more than a path — find and revert that stray edit.
+
+Finally, confirm no old path survives. For **each** old filename stem in your move list, grep and inspect:
+
+```bash
+grep -rn "<prefix>-loop" src web --include=*.ts --include=*.tsx
+```
+
+(substitute each stem: `<prefix>-manager`, `<prefix>-runner`, …). Any hit that is an **import/require/mock path** is a straggler — fix it with Rule IN and re-run typecheck. Hits that are plain strings, comments, or unrelated identifiers are fine; leave them.
+
+---
+
+## Step 7 — Report
+
+Give the user a short report in this exact shape:
+
+```
+Namespace:        src/<prefix>/   (from src/<prefix>-*)
+Files moved:      <n> source + <n> test   (old -> new, one per line)
+Bare entry:       src/<prefix>.ts -> src/<prefix>/index.ts   (or: none)
+Imports rewired:  <n> inbound files, <n> moved files re-pathed
+Typecheck loop:   clean after <n> pass(es)
+Tests:            all pass / <what failed>
+Lint problems:    <before> -> <after>   (must be unchanged)
+Quality (FTA):    unchanged / <what moved>
+```
+
+Keep it brief. Done.

package/ai/tasks/improve-plan.md

@@ -0,0 +1,121 @@
+# Improve a Draft Plan (one plan per run)
+
+Your job: take **one** plan from `product/plans/draft/`, check every claim it makes against the real codebase, and edit the plan so an implementer is less likely to go wrong — then assess its complexity and record it at the top of the plan. You improve the **plan document only**; you change no source code.
+
+**No AI attribution — anywhere.** Never credit an AI agent as an author or contributor in anything this task produces. That means: no `Co-Authored-By:` trailers naming Claude or any other AI, no “Generated with Claude Code” (or similar) lines or badges, and no AI authorship notes in code, comments, docs, spec files, plan files, commit messages, or PR titles and bodies. This overrides any default convention that appends such attribution. The commit's configured git author is the only authorship ever recorded.
+
+This is a **planning** task, not pre-implementation. A good plan decides *what* to build, *where* it goes, and *which existing code to reuse* — it does not write the code. The implementer writes the code.
+
+**Run everything synchronously, in the foreground.** Never use `run_in_background`, `&`, or otherwise start a background process (dev servers, watchers, long-lived processes) — every command must finish and return its exit code before you move to the next step.
+
+**No subagents, no background agents.** Do every step yourself — never launch a subagent (Task/Agent tool, `fork`, or otherwise) to research, explore, or implement any part of this task on your behalf.
+
+Do the steps below **in order**. Do not skip steps. Do not invent your own process.
+
+**Shell hygiene:** run every command on its own line — no `&&` chaining, no `; echo "Exit code: $?"` suffixes, no subshell captures. To run a project script, always use `./scripts/run.mjs <name>` — never call `node scripts/<name>.mjs` directly.
+
+**Run autonomously.** This task runs unattended — do not ask the user questions or wait for feedback at any step. Make the best judgment call yourself, using the rules in this document, and keep going. Only stop early for the conditions explicitly listed under "Forbidden" below.
+
+## What you may and may not do
+
+### Allowed — do it automatically, never ask
+
+Edit the **one plan file** you picked: correct it, disambiguate it, restructure it, and add the complexity line. Read anything in the repo you need to verify the plan's claims. When the work is only this, carry it out start to finish without stopping — do **not** ask "Do you want me to proceed?", do **not** pause for approval.
+
+### Forbidden — no exceptions
+
+1. **Adding code to the plan.** Never add implementation code blocks — no function bodies, no method implementations, no JSX/CSS blocks, no "here's the code to write". Name the module, function, or type and describe its contract and behavior in prose instead. (Illustrative examples of *observable output* — a CLI transcript, an error message the user will see, an ASCII sketch of UI — are fine. A type or code the implementer would paste is not.) If the draft already contains implementation code, you may leave it, but do not extend it; if it contradicts what you verified in the repo, replace it with a prose description rather than corrected code.
+2. **Editing any file other than the chosen plan.** No source, no tests, no config, no other plans.
+3. **Moving the plan out of `product/plans/draft/`.** Promotion to `ready/` is the human's status decision (see the plan-storage section in [`CLAUDE.md`](../../CLAUDE.md)).
+4. **Deciding product scope.** If the plan's *goal* seems wrong or not worth doing, say so in your report — do not rewrite the goal.
+
+---
+
+## Step 0 — Prepare the workspace
+
+Execute `ai/tasks/prepare-workspace.md` in full before doing anything else.
+
+---
+
+## Step 1 — Pick the plan
+
+- If you were pointed at a specific plan file, use that one.
+- Otherwise list `product/plans/draft/`. Exactly one plan there → that is your target. More than one → report the list and stop (the human picks). None → report that and stop.
+
+State your pick in one sentence.
+
+---
+
+## Step 2 — Read the plan, then read the code it talks about
+
+1. Read the entire plan.
+2. For **every** file path, function, type, command, line anchor, and behavioral claim the plan makes, open the real thing and check it. Grep for symbols rather than trusting quoted line numbers — line anchors drift.
+3. Read the project constraints that shape any implementation here: the ESLint rules and file-size limit in [`CLAUDE.md`](../../CLAUDE.md) (200-line `max-lines`, `.js` import extensions in `src/`, type-aware rules), and the test conventions (`src/**/*.test.ts`, `web/src/**/*.test.tsx`).
+4. Skim one or two plans in `product/plans/ready/` to match the house style — they follow a shape like: Goal, Design decisions, "What already exists (reuse, don't rebuild)" table, Implementation steps, Tests, Verification, Out of scope.
+
+---
+
+## Step 3 — Find the ways an implementer could go wrong
+
+Judge the plan against each of these. Take notes; you will fix them in Step 4.
+
+- **Wrong or stale references.** Paths, symbols, or line anchors that don't match the repo. These silently derail an implementation.
+- **Missed call sites and paths.** The plan changes behavior at one site, but the behavior has other entry points the plan never mentions. Grep for every caller/consumer of what the plan touches and check the plan accounts for each.
+- **Ambiguity.** Any step a reasonable implementer could read two ways; vague verbs ("handle errors", "update the UI") with no stated behavior; names left unchosen.
+- **Undecided decisions.** Choices the implementer would be forced to make mid-flight — file placement, naming, edge-case behavior, error handling, what happens on the empty/duplicate/oversized input. Plans decide; implementers execute. Make the decision (grounded in how the codebase already does it) and write it into the plan as prose.
+- **Unstated dependencies and ordering.** Does it depend on another plan landing first? Must its steps land in a particular order to keep typecheck/tests green at each checkpoint? Say so explicitly.
+- **Constraint collisions.** Will a touched file blow the 200-line limit (plan an extraction, don't leave it to chance)? Do proposed imports follow the `.js`-extension rule? Would the approach trip a lint rule from `eslint.config.mjs`?
+- **Reuse blindness.** Does the plan rebuild something the repo already has? Every mechanism the plan needs that already exists should be named with its location — a "What already exists (reuse, don't rebuild)" table is the house pattern.
+- **Testing gaps.** Behavior the plan changes with no test that would catch a regression, or tests named without their location/convention.
+- **Missing boundaries.** No "Out of scope" section, or a goal that quietly grows mid-document.
+- **Missing verification.** The plan should end with how to verify: `./scripts/run.mjs check-diff` during development plus a concrete manual end-to-end check.
+
+---
+
+## Step 4 — Improve the plan
+
+Edit the plan file to remove everything you found. Rules of thumb:
+
+- Every sentence you add must close off a way to go wrong or record a decision that was open. If it does neither, don't add it.
+- Anchor references as `path:line` **plus** the quoted identifier or code fragment, so the reference survives line drift.
+- Prefer "do it like `<existing thing>` at `<location>`" over describing a mechanism from scratch — pointing at a working example in the repo is the strongest ambiguity-killer that adds no code.
+- Do not rewrite sections that are already precise; keep the author's structure and voice where it works. This is an edit pass, not a rewrite.
+- Use natural line breaks — never wrap lines at a fixed column (per `CLAUDE.md`).
+
+---
+
+## Step 5 — Assess and record complexity
+
+Rate the (now improved) plan **1–10** for implementation complexity. Calibration, consistent with the ratings on the plans in `product/plans/ready/`:
+
+- **1–2** — one small module or pure wiring; no new protocol/persistence/UI surface. (`cli-help-version`, `prompt-click-prefill` are 2s.)
+- **3–4** — small feature, but correctness depends on catching several call sites or coordinating with other plans; or it spans server and web with a new RPC or persistence field. (`unread-badge` is a 3, `tab-name-alias` a 4.)
+- **5–7** — a new subsystem or protocol surface, many touched files, real state-machine or concurrency reasoning.
+- **8–9** — a major feature: multiple new modules on both sides, novel interaction logic, first-of-its-kind surface in the app. (`editor-tab` is a 9.)
+- **10** — architecture-level overhaul touching most of the system.
+
+Record it directly under the plan's `#` title as a single line:
+
+```
+**Complexity: N/10** — <one-line rationale naming what drives the number>
+```
+
+If the plan already has a complexity line, update it — after your improvements the number may have changed.
+
+---
+
+## Step 6 — Verify and report
+
+1. `git status` / `git diff` — confirm the **only** modified file is the plan (untracked plan files: confirm nothing else changed).
+2. Re-read your edits once: no implementation code added, every decision you made is stated as a decision (not hedged with "maybe" or "either"), complexity line present and formatted as above.
+
+Then give the user a short report in this exact shape:
+
+```
+Plan:        product/plans/draft/<file>
+Complexity:  N/10 — <rationale>
+Fixed:       <short bullets — each wrong reference corrected, ambiguity resolved, decision made, gap filled>
+Open:        <anything only the human can decide, e.g. scope doubts — or "nothing">
+```
+
+Keep it brief. Done.

package/ai/tasks/improve-security.md

@@ -0,0 +1,144 @@
+# Improve Security (detect everything, fix only the safe case, report the rest)
+
+Your job: run the security tools, list **every** finding, automatically apply the **one** kind of fix that is safe and mechanical (a dependency patch), and **report all other findings for a human** — do not change that code yourself.
+
+**No AI attribution — anywhere.** Never credit an AI agent as an author or contributor in anything this task produces. That means: no `Co-Authored-By:` trailers naming Claude or any other AI, no “Generated with Claude Code” (or similar) lines or badges, and no AI authorship notes in code, comments, docs, spec files, plan files, commit messages, or PR titles and bodies. This overrides any default convention that appends such attribution. The commit's configured git author is the only authorship ever recorded.
+
+**Shell hygiene:** run every command on its own line — no `&&` chaining, no `; echo "Exit code: $?"` suffixes, no subshell captures. The exit code and output are visible in the tool result. To run a project script, always use `./scripts/run.mjs <name>` — never call `node scripts/<name>.mjs` directly.
+
+**Run everything synchronously, in the foreground.** Never use `run_in_background`, `&`, or otherwise start a background process (dev servers, watchers, long-lived processes) — every command must finish and return its exit code before you move to the next step.
+
+**No subagents, no background agents.** Do every step yourself — never launch a subagent (Task/Agent tool, `fork`, or otherwise) to research, explore, or implement any part of this task on your behalf.
+
+**Why security is different from other cleanups:** a wrong security "fix" still passes the tests. If you silence a warning, weaken a check, or delete a guard, `tsc`, the linter, and the tests all stay green — so they **cannot** tell you that you made the code less safe. Because nothing will catch a bad call, you must not make security judgment calls. Detect and report; let a human decide.
+
+Do the steps below **in order**. Do not skip steps. Do not invent your own process.
+
+**Run autonomously.** This task runs unattended — do not ask the user questions or wait for feedback at any step. Make the best judgment call yourself, using the rules in this document, and keep going. There is nothing to stop for: every finding either gets the one safe dependency-patch fix, or gets reported under "Never do on your own" below — you always finish by producing the Step 3 report, never by pausing to ask.
+
+## The one safety rule (read this first)
+
+### Safe to do on your own — the ONLY change you may make
+
+- **Apply dependency patches** with `npm audit fix` (this fixes known CVEs using compatible versions). Then verify the project is still green. That is the only fix you apply on your own.
+
+### Never do on your own — REPORT it, do not touch the code
+
+Leave every one of these to a human. List it in your report (Step 3); do **not** edit the code:
+
+- Add or change **input validation / sanitisation**.
+- Add an `eslint-disable` comment, or **silence / suppress** any security finding in any way.
+- Rewrite a **regex**, remove an **`eval`**, or change any **auth / crypto / token** code or `src/security.ts`.
+- **Remove a committed secret** or rewrite git history.
+- Run **`npm audit fix --force`** (it makes breaking changes).
+
+Each of those is a judgment call, and a wrong call hides a real problem that the tests will not catch. Never edit config files or test files by hand. (`npm audit fix` may edit `package.json` / `package-lock.json` — that is fine.)
+
+---
+
+## Step 0 — Prepare the workspace
+
+Execute `ai/tasks/prepare-workspace.md` in full before doing anything else.
+
+---
+
+## Step 1 — Run the security tools and list every finding
+
+Detection is always safe, so do it even if the project is not green right now.
+
+### 1a — ESLint security findings
+
+```bash
+npm run lint 2>&1
+```
+
+ESLint groups findings under each file: the **file path is printed on its own line**, and its findings are **indented below it**, like this:
+
+```
+/Users/you/janissary/src/agent-state.ts
+  33:8   warning  Found existsSync from package "node:fs" with non literal argument at index 0  security/detect-non-literal-fs-filename
+```
+
+A security finding is any indented line whose last column is a rule starting with **`security/`**. For each one, record: the **file** (the path line above it), the **line:column** (e.g. `33:8`), the **severity** (`error` or `warning`), and the **rule**. (Quick filter: `npm run lint 2>&1 | grep -E "security/|^/"` keeps the security lines and the file-path headers.)
+
+### 1b — Dependency CVEs
+
+```bash
+npm run security:deps 2>&1
+```
+
+If it lists vulnerabilities, record for each: the **package**, the **CVE/advisory**, the **severity** (`low`/`moderate`/`high`/`critical`), and whether a **fix is available**. If it says `found 0 vulnerabilities`, record "No dependency CVEs."
+
+### 1c — Secrets scan
+
+```bash
+npm run security:secrets 2>&1
+```
+
+If the output says the command is not found / not installed, record "Secrets not scanned (gitleaks not installed)" and move on — this is **not** a failure. Otherwise record every finding (file, line, what was detected).
+
+**If all three are clean, report "No security findings." and stop.** Otherwise continue.
+
+---
+
+## Step 2 — Apply the one safe fix: dependency patches (only if there are any)
+
+Do this step **only if Step 1b found a vulnerability with a fix available.** If there were no dependency CVEs, skip straight to Step 3.
+
+1. **Confirm the project is green first** (you are about to change code):
+   ```bash
+   npx tsc --noEmit 2>&1
+   npm test 2>&1
+   npm run lint 2>&1
+   ```
+   The compiler must have no errors, every test must pass, and lint must have no errors (warnings are fine). **If it is not green, do not fix anything** — report the CVE in Step 3 with the note "not auto-fixed: project was not green," and stop.
+
+2. **Back up the manifest and lock file:**
+   ```bash
+   cp package.json package.json.bak
+   cp package-lock.json package-lock.json.bak
+   ```
+
+3. **Apply the fix** (never use `--force`):
+   ```bash
+   npm audit fix
+   ```
+
+4. **Verify** — everything must be green and the CVE gone:
+   ```bash
+   npx tsc --noEmit 2>&1
+   npm test 2>&1
+   npm run lint 2>&1
+   npm run security:deps 2>&1
+   ```
+   If anything is no longer green, **restore the backups and report**:
+   ```bash
+   cp package.json.bak package.json && cp package-lock.json.bak package-lock.json && npm install
+   ```
+   If `npm audit` says the remaining vulnerabilities can only be fixed with `--force` (breaking changes), do **not** force them — list them in Step 3 for a human.
+
+When green, delete the backups: `rm package.json.bak package-lock.json.bak`.
+
+---
+
+## Step 3 — Report
+
+Give the user a short report in this exact shape. Group the ESLint findings by rule so the list stays short.
+
+```
+Fixed automatically:
+  Dependencies:  <packages patched + new versions, or "none">
+
+Needs a human — NOT auto-fixed:
+  ESLint security:
+    <rule>  (<error/warning>)  ×<count>  in: <file:line, file:line, ...>
+      → <one-line suggestion, e.g. "confirm each path is trusted, or add validation at the entry point">
+    ... (one block per rule)
+  Secrets:        <findings, or "none", or "not scanned — gitleaks not installed">
+  Dependency CVEs not fixed: <CVEs needing --force or with no fix, or "none">
+
+Scans skipped:    <e.g. "gitleaks not installed", "opengrep not installed", or "none">
+Verify (only if a fix was applied): compiler / tests / lint all green
+```
+
+For a deeper scan, a human can run `npm run security:sast` (requires opengrep). Keep the report brief. Done.