janissary 0.5.1 → 0.5.2

package/ai/tasks/fix-a-small-issue.md

@@ -0,0 +1,138 @@
+# Fix a Small Issue
+
+Your job: pick the simplest issue from `product/backlog/issues.md`, develop a plan to resolve it, implement the fix, update functional specs, record the plan in `product/plans/complete/`, remove the issue from the issues file, and merge the change to master. You change source code, tests, spec files, the issues file, and the plan file's location — nothing else.
+
+**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, no `for`/`while` loops, no variable expansion (`$var`, `$(...)`), no redirects (`2>/dev/null`, `>file`, `>>file`), no pipes (`|`). Commands with control-flow, expansion, redirects, or pipes require manual approval and will stall an unattended run. 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.
+
+This overrides CLAUDE.md's "Capturing command output" guidance (write the output to a file under `./temp/`, then `grep` it repeatedly) for this task: the follow-up `grep`/`tail` filter commands stall an unattended run. Instead, run the command plain and read the full tool output directly — filter it yourself while reading, don't shell out to `grep`.
+
+**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.
+
+**Stay within the project directory.** The current working directory is the project directory for this session. Do not read or write any file outside it — no absolute paths escaping the project root, no `..` traversal above it, no touching files elsewhere on the machine (home directory config, other repos, system paths).
+
+## What you may and may not do
+
+### Allowed — do it automatically, never ask
+
+Read any file in the repo. Edit source, tests, CSS, and spec files as the fix requires. Write a plan file to `product/plans/complete/`. Remove the fixed issue from `product/backlog/issues.md`. Run `./scripts/run.mjs check-diff` after each change. Execute the full merge workflow via `ai/tasks/merge-change-to-master.md` when implementation is done.
+
+### Forbidden — no exceptions
+
+1. **Editing files the fix does not touch.** Stay in scope. If you discover a fix requires changes beyond what you planned, update the plan first — do not silently expand scope.
+2. **Running `npm run check`.** That is the human's end-of-work gate. Use `./scripts/run.mjs check-diff` during development.
+3. **Skipping tests.** Every fix needs tests that cover the changed behavior. Verify with `./scripts/run.mjs check-diff`.
+4. **Choosing an issue that requires significant new architecture.** If an issue would require high complexity error or prone work, pick a simpler issue instead and report why.
+5. **Editing `product/backlog/issues.md` beyond removing the fixed entry.** Only remove the line for the issue you fixed — do not reorder, rephrase, or otherwise modify the remaining entries.
+6. **Merging before all checks pass.** The `ai/tasks/merge-change-to-master.md` workflow handles merge; do not bypass it.
+
+---
+
+## Step 0 — Prepare the workspace
+
+Execute `ai/tasks/prepare-workspace.md` in full before doing anything else.
+
+---
+
+## Step 1 — List small fixes and pick the first available
+
+1. Read `product/backlog/issues.md` and list every issue.
+2. For each issue, assess the complexity by reviewing the codebase to understand what areas it touches. Do not use a shell loop for this.
+3. If no issues exist, report "No issues in `product/backlog/issues.md`" and stop.
+4. If every issue requires significant new architecture (rating 7+), report the list with assessments and stop — do not pick one.
+5. Otherwise, pick the **first** issue listed in the file (top of the list). State your pick and why.
+
+---
+
+## Step 2 — Develop a plan
+
+1. Read the project constraints in [`CLAUDE.md`](../../CLAUDE.md): ESLint rules (200-line `max-lines`, `.js` import extensions in `src/`, type-aware rules), test conventions (`src/**/*.test.ts`, `web/src/**/*.test.tsx`).
+2. Read every file relevant to the fix to understand the code involved.
+3. Write a plan file following the format of existing plans in `product/plans/complete/` — include a complexity rating, goal, approach, implementation steps, tests, and out-of-scope items. Write it to `product/plans/draft/<fix-name>.md`.
+4. After the plan is written, move it from `product/plans/draft/` to `product/plans/ready/`:
+   ```bash
+   git mv product/plans/draft/<fix-name>.md product/plans/ready/<fix-name>.md
+   ```
+
+---
+
+## Step 3 — Implement the fix
+
+Follow the plan's implementation steps **in order**. After each step:
+
+1. Run `./scripts/run.mjs check-diff` to catch lint, typecheck, and test failures immediately.
+2. Fix any failures before moving to the next step.
+3. If a step produces a file over the 200-line limit, extract into a new module per `ai/guidelines/code-guidelines.md` — do not compact code, strip comments, or delete spacing.
+
+Key rules during implementation:
+
+- **Match existing conventions.** Use the same libraries, patterns, and naming the surrounding code uses. Check `package.json` or the file's existing imports before assuming a library is available.
+- **Import extensions.** Relative imports in `src/` must carry `.js` (NodeNext). Relative imports in `web/src/` stay extensionless.
+- **No comments unless the plan specifies them.** Write clean code; let it speak for itself.
+
+---
+
+## Step 4 — Write the tests
+
+If the plan has a Tests section, implement every test case listed. Mirror the test style of the referenced test files (imports, helper patterns, assertion style).
+
+Run `./scripts/run.mjs check-diff` after writing tests. All tests must pass.
+
+---
+
+## Step 5 — Update or create spec files
+
+Every fix must be reflected in the functional specs under `product/specs/`. After implementation and tests:
+
+1. **Check the plan.** If the plan names specific spec files to update or create, do exactly that.
+2. **Otherwise, find the right spec.** Read the existing specs in `product/specs/` and identify which one(s) the fix relates to. Most fixes extend an existing spec. If no existing spec covers the area, create a new one.
+3. **Write or update the spec.** Follow the existing conventions: `# Title` at the top, `### Subsection` for each aspect, prose describing user-visible behavior only — no code, no implementation details, no file paths. The spec is what the fix *does*, not how it is built. Keep additions concise and factual.
+
+Spec files are markdown and do not affect `check-diff`, so no verification run is needed after this step.
+
+---
+
+## Step 6 — Promote the plan and remove the issue
+
+1. Move the plan file from `product/plans/ready/` to `product/plans/complete/`:
+   ```bash
+   git mv product/plans/ready/<fix-name>.md product/plans/complete/<fix-name>.md
+   ```
+2. Remove the fixed issue's line from `product/backlog/issues.md`. Only remove that single line — do not modify any other content in the file.
+
+---
+
+## Step 7 — Final verification
+
+1. Run `./scripts/run.mjs check-diff` one last time. It must pass clean.
+2. Manually verify the behavior if the plan's Verification section describes manual steps. If manual verification is not possible in this environment, note that in the report.
+
+---
+
+## Step 8 — Merge the change to master
+
+Execute `ai/tasks/merge-change-to-master.md` in full. That document owns the merge workflow — follow its steps without deviation.
+
+---
+
+## Step 9 — Report
+
+Give the user a short report in this exact shape:
+
+```
+Issue:          <the issue text from product/backlog/issues.md>
+Plan:           product/plans/ready/<file> → product/plans/complete/<file>
+Complexity:     N/10
+Implementation: <one-line summary of the fix>
+Tests:          <count> new tests across <files>
+Spec:           <spec file(s) created or updated, with one-line description of change>
+PR:             <url> (#<number>)
+Status:         merged
+```
+
+Keep it brief. Done.

package/ai/tasks/improve-codebase.md

@@ -0,0 +1,187 @@
+# Improve code base
+
+Your job: act as a **supervisor** that continuously improves this codebase by running a loop, entirely by yourself — no subagents, no background agents. Each cycle you **inspect** the code, **select** the single most valuable improvement, **execute** the matching task playbook yourself, **verify** the result, **ship it to `master` through a full pull request**, and then **start the next cycle**. You own the judgment around it: what to work on, whether the result is genuinely good, and when to stop.
+
+The improvement work itself follows one of these existing single-purpose task playbooks — you pick the right one each cycle and execute it yourself, inline, in this same session:
+
+| Signal you see when inspecting | Task to execute |
+| --- | --- |
+| A `max-lines` error, or a high FTA score on a long file | [`improve-modularity.md`](improve-modularity.md) |
+| A `sonarjs/cognitive-complexity` warning on a function | [`reduce-complexity.md`](reduce-complexity.md) |
+| A flat cluster of files sharing a naming prefix (`src/acp-*`, `src/agent-*`, …) | [`improve-namespacing.md`](improve-namespacing.md) |
+| Knip reports unused files / exports / dependencies | [`remove-deadcode.md`](remove-deadcode.md) |
+| jscpd reports a duplicated block | [`remove-duplication.md`](remove-duplication.md) |
+| Coverage is below threshold on a testable file | [`improve-test-coverage.md`](improve-test-coverage.md) |
+| `npm audit` / security tooling reports a patchable advisory | [`improve-security.md`](improve-security.md) |
+| stylelint reports a CSS issue | [`improve-style.md`](improve-style.md) |
+| `npm outdated` lists a safe-looking package update | [`update-package.md`](update-package.md) |
+
+**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.
+
+**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. The only reasons to stop are the ones listed in "When to stop the loop" below.
+
+**No subagents, no background agents.** Do every step yourself, in this session — never launch a subagent (Task/Agent tool) to execute a playbook or any part of one, and never hand work off to a background agent. The playbooks referenced below are instructions for *you* to follow directly, not prompts to delegate.
+
+**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.
+
+**Ship every verified change to `master`.** After you verify a cycle's improvement (Step 4), you do not stop at a local commit — you hand the change off to [`merge-change-to-master.md`](merge-change-to-master.md), which commits it as a single-author Conventional Commits commit, opens a pull request against `master`, resolves any conflicts, waits for required checks, and squash-merges it into `master` on GitHub. Each cycle therefore lands as its own isolated, reviewed PR. If that task cannot land the change — conflicts it can't resolve after its retries, or a failing required check — it leaves the PR **open** for a human; treat that cycle as **not merged**, record it, and move on. Never force the merge or hand-edit `master` yourself.
+
+---
+
+## Step 0 — Prepare the workspace (once, before the loop)
+
+Execute [`prepare-workspace.md`](prepare-workspace.md) in full before doing anything else. Do this **once** to set up the workspace; the loop then reuses it. Because each cycle merges its change to `master` on GitHub (Step 5) and resyncs the workspace to the updated `master` (Step 6), re-pulling between cycles is safe and expected — there are no unmerged local commits to clobber.
+
+Then establish a clean starting point:
+
+```bash
+git status
+```
+
+The working tree **must be clean** before you start. If it is not, STOP and report — do not start a supervised loop on top of uncommitted changes you did not make.
+
+Decide how many cycles to run. If the user gave a number, use it. Otherwise default to **5 cycles**, and always honor the stopping conditions below — a smaller effective number is fine.
+
+---
+
+## The loop
+
+Repeat Steps 1–6 until a stopping condition is met. Keep a running **ledger** (a short table you maintain in your head and print in the final report): cycle number, task executed, target, before→after metric, PR number/URL, outcome.
+
+### Step 1 — Inspect the code (take a fresh snapshot)
+
+Run the diagnostics fresh every cycle — never trust numbers from an earlier cycle, since the previous commit changed the tree:
+
+```bash
+npm run typecheck 2>&1
+npm run lint 2>&1
+npm run quality 2>&1
+npm run duplication 2>&1
+npm run knip 2>&1
+npm run lint:css 2>&1
+npm outdated 2>&1
+```
+
+- **TypeScript / tests must be green to begin a cycle.** If `npm run typecheck` errors, STOP the loop and report — the tree is broken and no improvement should be layered on top. (Tests are validated per-task as you follow the chosen playbook, and re-checked in Step 4.)
+- Read the signals into the selection table at the top of this file: FTA scores and `max-lines` from `quality`/`lint`, `cognitive-complexity` warnings from `lint`, clones from `duplication`, unused code from `knip`, coverage gaps (run `npm run coverage 2>&1` when test-coverage is a candidate), CSS issues from `lint:css`, prefix clusters from the file layout under `src/`, and outdated packages from `npm outdated` (`npm outdated` exits non-zero when it lists anything — that's expected, not a broken tree).
+
+Record the specific number for whatever you're about to target (the FTA score, the complexity value, the clone count, etc.) — this is the **before** value you will compare against in Step 4.
+
+### Step 2 — Select exactly one improvement
+
+Choose the **single** highest-value improvement for this cycle:
+
+1. Rank the live signals by impact. A `max-lines` **error** (blocks the build gate) outranks a mere warning; a high-severity `npm audit` advisory outranks a cosmetic CSS nit; a large clone or a badly over-limit complexity function outranks a marginal one.
+2. **Skip anything a prior cycle already failed on.** If cycle N tried task T on target X and you had to revert it (Step 4), do not pick the same (task, target) again — pick the next-best signal.
+3. **Rotate to avoid starvation.** All else roughly equal, prefer a task type you have not run recently this session, so the codebase improves broadly rather than grinding one dimension.
+4. If **no** signal points to a worthwhile, safe improvement — every candidate is blocked, trivial, or already-failed — **stop the loop** (see "When to stop").
+
+State your pick in one sentence: the task playbook, the target file/function, and the before-number. Add a new row to your ledger.
+
+### Step 3 — Execute the chosen playbook yourself
+
+Follow [`ai/tasks/<task>.md`](.) for the task you picked in Step 2, in full, in this same session — you are the one carrying out every step of it, not a subagent. A few adjustments to how you run it here:
+
+1. **Skip that playbook's "Step 0 — Prepare the workspace"** — the workspace is already prepared and synced to `master`, and you must not run `git checkout`/`git pull` here (that would discard the working-tree change you're about to make this cycle). Start at the playbook's Step 1.
+2. **Stop after that playbook's own verification step — do not commit, push, or open a PR from within it.** Leave the single change sitting in the working tree. Committing and shipping is Step 5 below, handled once for the whole cycle.
+3. Keep honoring the **No AI attribution** and **Run autonomously** rules throughout (never pause to ask a question). For the playbooks that would otherwise ask a human or defer findings — [`improve-style.md`](improve-style.md) and [`improve-security.md`](improve-security.md) — apply **only** the safe, mechanical change yourself, and note anything requiring human judgment for the final report instead of blocking.
+4. Stay narrowed to the target you selected in Step 2 — don't re-derive a different pick mid-playbook.
+
+Track your own before→after numbers and which file(s) you touched as you go — you'll need them for the ledger and for Step 4.
+
+### Step 4 — Verify the result independently
+
+Even though you just made this change yourself, re-check it with fresh commands rather than trusting your own running impression — it's easy to miss a regression while focused on the one metric you were improving. Confirm the change is real, correct, and scoped:
+
+```bash
+git status
+git diff --stat
+npm run typecheck:diff 2>&1
+npm run test:diff 2>&1
+npm run lint:diff 2>&1
+npm run quality 2>&1
+```
+
+Check, in order — **any** failure means the change is rejected:
+
+1. **Scope is legal.** `git diff --stat` touches only files the chosen playbook permits. Reject if it touched a forbidden file (`src/controller.ts`, `src/main.ts`, PTY/shell/network/crypto files, `*.test.ts` where the task forbids it), a config file (`fta.json`, `eslint.config.mjs`, `package.json`, `tsconfig.json`) it shouldn't, or far more files than the task's cap allows.
+2. **No AI attribution** slipped into any changed file, comment, or (later) commit message.
+3. **TypeScript is clean** (`typecheck:diff` — no errors).
+4. **Tests pass** (`test:diff`).
+5. **Lint is no worse** — the `✖ … problems (errors, warnings)` line has **0 errors** and warnings **≤** your Step 1 snapshot.
+6. **The target metric actually improved** versus the before-number you recorded: the FTA score dropped, the complexity warning cleared, the clone is gone, the coverage rose, the knip finding disappeared, etc. A change that is green but did not move the metric is not worth keeping.
+
+**If all checks pass →** go to Step 5.
+
+**If any check fails →** revert this cycle's change so the tree returns to the last good commit, and record the cycle as **reverted** in the ledger:
+
+```bash
+git checkout -- .
+git clean -fd
+```
+
+(Use `git clean -fd` to also drop any new files you created.) Then continue to Step 6 — the loop goes on, but Step 2 will not re-pick this (task, target).
+
+### Step 5 — Ship this cycle to master
+
+The change is verified and sitting uncommitted in the working tree. **Ship it by executing [`merge-change-to-master.md`](merge-change-to-master.md) in full, yourself** — follow every step of that playbook in order, same as you did for the improvement playbook in Step 3; do not delegate this either. It commits the change as a single-author Conventional Commits commit — pick the type that fits the task (`refactor` for modularity/complexity/namespacing/duplication, `test` for coverage, `chore`/`fix` for deadcode, `fix`/`build` for security, `style` for CSS, `build` for a package update) — opens a PR against `master`, resolves any conflicts, waits for required checks, and squash-merges it. Do **not** hand-commit first: the merge task's own Step 0 picks up the working-tree change itself.
+
+Keep honoring the **No AI attribution** rule as you go — the commit, PR title, and PR body must carry no AI authorship — and the **Run autonomously** rule (never pause to ask a question).
+
+Follow the merge task through to its own final report shape, then fold the outcome into your ledger:
+
+- **Merged** → mark the cycle **merged** and capture the PR number/URL into the ledger row. Write a two-line summary of what this cycle achieved.
+- **Left open** (conflicts unresolved after its retries, or a required check failed) → the change did not land on `master`. Mark the cycle **open (not merged)** with the PR URL and the reason. Do not retry the merge. This counts the same as a non-successful cycle for the "two in a row" stopping condition in Step 6.
+
+### Step 6 — Resync master and decide whether to continue
+
+First return the workspace to a clean, up-to-date `master` so the next cycle inspects the true merged state rather than a leftover feature branch:
+
+```bash
+git checkout master
+git pull origin master
+```
+
+If this cycle was **reverted** in Step 4 you never left `master`, and if its PR was **left open** the change is not on `master` — in both cases the working tree is (or becomes) clean here, which is correct; an open PR lives on for a human. A **merged** cycle's change arrives on `master` via this pull.
+
+Then decide:
+
+- If you have completed the planned number of cycles → stop and go to the final report.
+- If a stopping condition below is met → stop and go to the final report.
+- Otherwise → return to **Step 1** for the next cycle. The tree is clean and `master` is current, so the next inspection sees an accurate picture.
+
+---
+
+## When to stop the loop
+
+Stop the loop (and write the final report) as soon as **any** of these is true:
+
+- You've run the planned number of cycles (default 5).
+- **No worthwhile, safe improvement remains** — Step 2 finds every candidate blocked, trivial, or already-failed this session.
+- The tree is **broken and you can't recover it** — a cycle left typecheck or tests red and reverting did not restore green. Report loudly; do not keep layering cycles on a broken tree.
+- **Two cycles in a row did not land** — reverted in Step 4, or their PR was left open (unresolved conflicts / failing check) in Step 5. The signals aren't yielding shippable wins right now; stop rather than spin.
+
+---
+
+## Final report
+
+Print the ledger and a short summary:
+
+```
+Supervised improvement run — <N> cycles
+
+Cycle  Task                  Target                         Metric (before -> after)   Outcome    PR
+1      reduce-complexity     src/foo.ts parseConfig()       cc 30 -> 12                merged     #123
+2      remove-duplication    src/bar.ts / src/baz.ts        1 clone -> 0               merged     #124
+3      improve-modularity    src/qux.ts                     score 78 -> 61, 243->150   reverted   —
+4      improve-security      npm advisory GHSA-xxxx         high -> patched            open       #125
+...
+
+Merged this run: <count>   Reverted: <count>   Open (not merged): <count>
+Net effect: <one or two sentences on what got better overall>
+Next: <anything a human should look at — PRs left open on a failing check or unresolved conflicts, deferred security/style findings, a target that keeps failing, or "all cycles merged, master is clean">
+```
+
+Merged cycles are already on `master`. Note in "Next" any PR that was **left open** (failing required check or unresolved conflicts) so a human can finish it. Keep the report brief. Done.

package/ai/tasks/improve-modularity.md

@@ -0,0 +1,188 @@
+# Improve Code Modularity (one safe extraction per run)
+
+Your job: make **one** small, safe change that lowers the complexity of **one** high-complexity file by **moving a cohesive group of its code out into a new, focused module file** — then prove you did not break anything. Do exactly one extraction, then verify.
+
+**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.
+
+**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.
+
+This is the **only** way we reduce a file's size and complexity here: extract a cohesive group of related code into a new file and import it back. Never compact code, strip comments, or delete blank lines to shrink a file — that hurts readability without improving the design (see [`code-guidelines.md`](../guidelines/code-guidelines.md)).
+
+Refactoring edits 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 code back the way it was.**
+
+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. 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 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 file 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: **extract one cohesive group of code from a high-complexity source file into one (or more) new module files you create, and import it back** — done by the Recipe in Step 5, and nothing else.
+
+### Blocked work — skip and pick a different file
+
+If doing the extraction would require any of the following, **go back to Step 3** and pick the next-best file instead. Never ask the user — just skip and move on.
+
+1. Changing the **public API** of a file other files depend on — i.e. you cannot keep every existing `import` working. (If you move an `export`ed symbol but **re-export it from the original file** so no other file changes, that is still safe.)
+2. Editing **more than 1 existing source file**, or changing import paths in more than 3 files (the new module file(s) you create do not count).
+3. Touching **`src/controller.ts`** (the biggest, riskiest file) — even though it has the highest score.
+4. Editing **any test file** (`*.test.ts`, `*.test.tsx`).
+5. Touching **security, password/crypto, shell-execution, PTY/terminal, or network** code.
+
+If every remaining candidate is blocked, report which files you considered and why each was blocked, and stop without changing any code.
+
+> You may edit **only** the one existing source file you picked, plus the **new module file(s)** you create to receive the extracted code. Never edit `fta.json`, `eslint.config.mjs`, `package.json`, `tsconfig.json`, or any other config or test file. Leave the `score_cap` in `fta.json` alone.
+
+---
+
+## 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.
+- **Lint:** near the end of `npm run lint` there is a summary line like `✖ 16 problems (0 errors, 16 warnings)`. Write down the **errors** count and the **warnings** count. Note especially any `max-lines` (file over 200 lines) and `sonarjs/cognitive-complexity` warnings — these point straight at extraction targets.
+- **Tests:** they must be **green** (all passing). If any test is already failing **before** you touch anything, STOP and tell the user — do not start a refactor on a broken suite.
+- **Quality (FTA):** `npm run quality` prints a table per area, sorted worst-first, with each file's **line count** and **FTA score** (lower = better). This is your **primary** signal for what to extract from. Write down the score and line count of the file you end up picking.
+
+Always run these fresh. Do not trust earlier output in the conversation.
+
+---
+
+## Step 2 — Read the signals
+
+You are looking for the file that most needs code moved out of it. Two places tell you:
+
+- The **FTA table** (`npm run quality`): the top rows are the worst files. A high score usually means the file is both long and complex — a prime candidate to split.
+- The **lint warnings** (`npm run lint`): a `max-lines` error means the file is over the 200-line limit and *must* shed code into a new module; a `sonarjs/cognitive-complexity` warning marks a function that has grown too tangled and often signals a cluster worth lifting out whole.
+
+A `max-lines` or `cognitive-complexity` finding looks like this in the lint output:
+
+```
+src/foo.ts
+  1:1   error    File has too many lines (243). Maximum allowed is 200  max-lines
+  42:11 warning  Refactor this function to reduce its Cognitive Complexity
+                 from 30 to the 15 allowed  sonarjs/cognitive-complexity
+```
+
+It tells you the **file** (and, for complexity, the **function line**) that is carrying too much.
+
+---
+
+## Step 3 — Pick exactly one file to extract from
+
+1. From the FTA table, list the worst `src/` files together with any that carry a `max-lines` or `cognitive-complexity` warning.
+2. **Cross out** any file that is:
+   - a `*.test.ts` / `*.test.tsx` file,
+   - `src/main.ts`,
+   - `src/controller.ts` (needs-permission — only with the user's go-ahead),
+   - `src/pty.ts`, `src/shell.ts`, or any file whose main job is spawning processes, running a terminal, doing network
+   - under `web/src/` (only consider these if no `src/` candidate is left),
+   - already small and simple (low score, comfortably under 200 lines).
+3. From what remains, pick the **one** file with the **highest FTA score** — that is the one most worth splitting. Prefer a file that is over (or near) the 200-line limit, since extraction there also clears a `max-lines` error.
+
+State your pick in one short sentence: the file, its current FTA score and line count, and the warning(s) it carries. Write those numbers into your report draft.
+
+---
+
+## Step 4 — Plan the extraction (a quick note to yourself, then keep going)
+
+Find **one cohesive group of code** to lift out whole — code that belongs together and reads naturally as its own module. Good clusters:
+
+- a set of related pure helpers (e.g. all the parsing/formatting functions for one concern),
+- the body and helpers of one over-complex function flagged by `cognitive-complexity`,
+- a group of related types/constants plus the small functions that operate on them.
+
+Jot a one- or two-line plan: **which** group of code you will move, the **name of the new file** (`kebab-case.ts`, focused on that concern), and **what the original file will import back** from it. This is a note for **you**, not a message to send — do **not** post it and wait for a reply.
+
+Check the plan against **What you may and may not do**:
+
+- If any of points 1–5 applies → go back to Step 3 and pick a different file.
+- Otherwise (all safe work) → go straight to Step 5 and make the change **now, on your own, without asking.**
+
+---
+
+## Step 5 — Make the change
+
+**First, back up the existing file you are about to edit**, so you can restore it exactly if anything goes wrong:
+
+```bash
+cp src/foo.ts src/foo.ts.bak
+```
+
+Then perform the extraction. Keep the diff focused — move the chosen group of code, and do not reformat or "tidy" unrelated lines.
+
+### Recipe — extract a cohesive group into a new module file
+
+1. **Create the new module file** next to the original, with a focused `kebab-case` name describing the concern (e.g. `src/foo-parsing.ts`). Keep it under 200 lines too — if the group you want to move is itself huge, move a smaller cohesive subset.
+2. **Move the chosen code** (functions, and the types/constants only they use) into the new file. Add whatever `import`s that code needs at the top of the new file.
+3. **Export** from the new file exactly the symbols the original file still needs.
+4. **In the original file**, delete the moved code and add an `import { … } from './foo-parsing.js';` for the symbols you now call.
+5. **Preserve the public API.** If any moved symbol was `export`ed and is imported by *other* files, **re-export it from the original file** (`export { thing } from './foo-parsing.js';`) so no other file has to change. If you cannot keep every existing import working without editing other files → STOP and ask (rule 1).
+6. Do **not** change behavior, call signatures, or what anything returns. Do **not** move code in a way that breaks ordering of side effects or shared module state.
+7. If you cannot find a clean, self-contained group to move like this, do **not** force it — restore your backup, go back to Step 3, and pick a different file (or report that no safe extraction was available).
+
+### Style
+
+- Match nearby naming: `camelCase` functions, `PascalCase` types, `kebab-case` filenames.
+- Relative imports use a **`.js`** extension even though the source is `.ts` (e.g. `import { x } from './foo.js'`). The new module file and the import that points to it must both follow this.
+- Add a comment only if the *why* is non-obvious; never a comment that just restates *what* the code does.
+
+---
+
+## Step 6 — Verify (run in this order; fix or put it back)
+
+```bash
+npm run typecheck:diff 2>&1
+npm run test:diff 2>&1
+npm run lint:diff 2>&1
+npm run quality 2>&1
+```
+
+Check each, in order:
+
+1. **TypeScript is clean.** `npm run typecheck:diff` must have no errors. A type error here almost always means a moved symbol's type is missing an import in the new file, or a re-export was forgotten — fix it in your source files. If you cannot make it clean quickly, restore your backup and report.
+2. **Tests pass.** If a test now fails: try a quick, obvious fix in your source files (do **not** edit the test). If it does not pass quickly, **restore your backup** (`cp src/foo.ts.bak src/foo.ts`, and delete the new module file(s) you added) and report what blocked you. Never edit a test to make it pass.
+3. **Lint is no worse.** Look at the `✖ … problems (… errors, … warnings)` line again. **Errors must be 0** (if you were clearing a `max-lines` error, it should now be gone). **Warnings must be the same or fewer** than Step 1, never higher. If a new warning or error appeared — often a missing `.js` import extension, a now-unused import, or complexity that rode along into the new file — fix it in your source files. Never silence a warning with an `eslint-disable` comment.
+4. **Quality improved.** The original file's FTA score and line count should be **lower** than Step 1. The new module file should land at a reasonable score and stay under 200 lines. If the original's score did not drop, the extraction was too small to matter — restore the backup and pick a more substantial group (or a different file).
+
+When all three pass, **delete the backup file**: `rm src/foo.ts.bak`.
+
+---
+
+## Step 7 — Report
+
+Give the user a short report in this exact shape:
+
+```
+Target file:      <path>
+New module:       <path of the file you created>
+Extraction:       <one sentence — e.g. "moved the 4 query-parsing helpers out of database.ts into database-parsing.ts">
+FTA score:        <before> -> <after>   (lines: <before> -> <after>)
+Lint problems:    <before> -> <after>   (errors: <before> -> <after>)
+TypeScript:       clean / <errors, if any>
+Tests:            all pass / <what failed>
+```
+
+Keep it brief. Done.