janissary 0.5.5 → 0.6.0

package/README.md

@@ -4,7 +4,7 @@ Janissary is an **Agentic Working Environment**. In other words, it is an applic
 
 A [Janissary](https://en.wikipedia.org/wiki/Janissary) was an elite infantry soldier in the Ottoman Empire — a servant of the gate, loyal, and ever-ready. 
 
-See the [User Docs](https://thirtysixthspan.github.io/janissary/user-documentation/getting-started/application) for the full command reference, tab types, and automation/advanced-agent guides.
+See the [Documentation](https://thirtysixthspan.github.io/janissary/) for the full command reference, tab types, and automation/advanced-agent guides.
 
-See the [Developer Docs](https://thirtysixthspan.github.io/janissary/developer-documentation/) for advanced usage, coding, linting and testing practices.  
+See the [Developer Documentation](https://thirtysixthspan.github.io/janissary/developer-documentation/) for advanced usage, coding, linting and testing practices.  
 

package/ai/tasks/build-a-feature.md

@@ -1,6 +1,8 @@
 # Build a Feature
 
-Your job: pick the simplest available plan from `product/plans/ready/`, implement it end to end, update the functional specs, promote the plan to `product/plans/complete/`, and open a pull request. You change source code, tests, spec files, and the plan file's location — nothing else.
+Your job: pick the simplest available plan from `./product/plans/ready/`, implement it end to end, update the functional specs, promote the plan to `./product/plans/complete/`, and open a pull request. You change source code, tests, spec files, and the plan file's location — nothing else.
+
+**Project `./product/` directory.** Every `./product/...` path in this task refers to the product directory in the current working directory — the project being worked on — never to the Janissary codebase's own `product/` directory, even when this task file was launched from an absolute path inside the Janissary installation.
 
 **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.
 
@@ -8,8 +10,6 @@ Your job: pick the simplest available plan from `product/plans/ready/`, implemen
 
 **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.
-
 **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 (e.g. no plans available, only 7+ complexity plans, discovering out-of-scope file edits).
 
 **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).
@@ -18,14 +18,14 @@ Your job: pick the simplest available plan from `product/plans/ready/`, implemen
 
 ### Allowed — do it automatically, never ask
 
-Read any file in the repo. Edit source, tests, CSS, and spec files as the plan directs. Move the chosen plan file from `product/plans/ready/` to `product/plans/complete/`. Run `./scripts/run.mjs check-diff` after each change. Run the full PR workflow via `ai/tasks/open-feature-pull-request.md` when implementation is done.
+Read any file in the repo. Edit source, tests, CSS, and spec files as the plan directs. Move the chosen plan file from `./product/plans/ready/` to `./product/plans/complete/`. Run `./scripts/run.mjs check-diff` after each change. Run the full PR workflow via `ai/tasks/open-feature-pull-request.md` when implementation is done.
 
 ### Forbidden — no exceptions
 
 1. **Editing files the plan does not touch.** Stay inside the plan's scope. If you discover the plan missed a file, stop and report — 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.** If the plan specifies tests, write them. If it does not, still verify with `./scripts/run.mjs check-diff`.
-4. **Choosing a plan at complexity 7 or above.** If every plan in `product/plans/ready/` is rated 7+, stop and report — do not pick one anyway.
+4. **Choosing a plan at complexity 7 or above.** If every plan in `./product/plans/ready/` is rated 7+, stop and report — do not pick one anyway.
 5. **Merging the PR.** `ai/tasks/open-feature-pull-request.md` opens it; merging is the human's decision.
 
 ---
@@ -38,9 +38,9 @@ Execute `ai/tasks/prepare-workspace.md` in full before doing anything else.
 
 ## Step 1 — List ready plans and pick the simplest
 
-1. List every `.md` file in `product/plans/ready/`.
+1. List every `.md` file in `./product/plans/ready/`.
 2. For each file, use the `Read` tool to read the first few lines and find the complexity rating line: `**Complexity: N/10**`. Do not use a shell loop to do this.
-3. If no plans exist, report "No plans in `product/plans/ready/`" and stop.
+3. If no plans exist, report "No plans in `./product/plans/ready/`" and stop.
 4. If the lowest complexity found is **7 or above**, report the list with ratings and stop — do not pick one.
 5. Otherwise, pick the plan with the **lowest** complexity number. On a tie, pick whichever plan name comes first alphabetically.
 
@@ -83,10 +83,10 @@ Run `./scripts/run.mjs check-diff` after writing tests. All tests must pass.
 
 ## Step 5 — Update or create spec files
 
-Every feature must be reflected in the functional specs under `product/specs/`. After implementation and tests:
+Every feature 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 feature belongs to. Most features extend an existing spec (e.g. a new keyboard shortcut belongs in `product/specs/keyboard-navigation.md`, a new tab behavior belongs in `product/specs/tabs.md`). If no existing spec covers the area, create a new one.
+2. **Otherwise, find the right spec.** Read the existing specs in `./product/specs/` and identify which one(s) the feature belongs to. Most features extend an existing spec (e.g. a new keyboard shortcut belongs in `./product/specs/keyboard-navigation.md`, a new tab behavior belongs in `./product/specs/tabs.md`). 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 feature *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.
@@ -102,10 +102,10 @@ Spec files are markdown and do not affect `check-diff`, so no verification run i
 
 ## Step 7 — Promote the plan
 
-Move the plan file from `product/plans/ready/` to `product/plans/complete/`:
+Move the plan file from `./product/plans/ready/` to `./product/plans/complete/`:
 
 ```bash
-git mv product/plans/ready/<plan-file> product/plans/complete/<plan-file>
+git mv ./product/plans/ready/<plan-file> ./product/plans/complete/<plan-file>
 ```
 
 ---
@@ -121,7 +121,7 @@ Execute `ai/tasks/open-feature-pull-request.md` in full. That document owns the
 Give the user a short report in this exact shape:
 
 ```
-Plan:           product/plans/ready/<file> → product/plans/complete/<file>
+Plan:           ./product/plans/ready/<file> → ./product/plans/complete/<file>
 Complexity:     N/10
 Implementation: <one-line summary of what was built>
 Tests:          <count> new tests across <files>

package/ai/tasks/fix-a-bug.md

@@ -0,0 +1,191 @@
+# Fix a Bug
+
+Your job: take a reported bug from `./product/backlog/bugs.md` — the first one listed under `## ready`, or the specific bug the user names when running this task — **replicate it** to confirm the faulty behavior, determine the **correct** behavior from the bug report together with the functional specs and the code, implement a fix, **verify** the fix resolves the replicated failure, add a **regression test** that would fail without the fix and passes with it, update functional specs and public documentation where the fix changes behavior they already document, record the plan in `./product/plans/complete/`, remove the bug from the bugs file, and open a pull request that documents the replication steps and leaves the fix for a human to merge. You change source code, tests, spec files, `help.md`, `documentation/user-documentation/`, the bugs file, and the plan file's location — nothing else.
+
+**Project `./product/` directory.** Every `./product/...` path in this task refers to the product directory in the current working directory — the project being worked on — never to the Janissary codebase's own `product/` directory, even when this task file was launched from an absolute path inside the Janissary installation.
+
+**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.
+
+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. Run read-only commands to replicate the reported bug. Edit source, tests, CSS, and spec files as the fix requires. Update `help.md` and files under `documentation/user-documentation/` when the fix changes behavior they already document. Write a plan file under `./product/plans/` and move it through `draft/` → `ready/` → `complete/`. Remove the fixed bug from `./product/backlog/bugs.md`. Run `./scripts/run.mjs check-diff` after each change. Run the full PR workflow via `ai/tasks/open-feature-pull-request.md` when implementation is done.
+
+### Forbidden — no exceptions
+
+1. **Fabricating a fix, a symptom, or a reproduction.** Never invent a failure you did not observe or a fix for a bug you could not reproduce. If the selected bug cannot be reproduced, stop and report (Step 1). If the specs and code leave the intended behavior genuinely ambiguous, stop and report (Step 2).
+2. **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.
+3. **Running `npm run check`.** That is the human's end-of-work gate. Use `./scripts/run.mjs check-diff` during development.
+4. **Skipping the regression test.** Every fix needs a test that fails without the fix and passes with it. Verify with `./scripts/run.mjs check-diff`.
+5. **Editing `./product/backlog/bugs.md` beyond removing the fixed entry.** Only remove the line for the bug you fixed — do not reorder, rephrase, or otherwise modify the remaining entries.
+6. **Merging the PR.** `ai/tasks/open-feature-pull-request.md` opens it; merging is the human's decision.
+
+---
+
+## Step 0 — Prepare the workspace
+
+Execute `ai/tasks/prepare-workspace.md` in full before doing anything else.
+
+---
+
+## Step 1 — Pick a bug and replicate it
+
+1. Read `./product/backlog/bugs.md`. Bugs are grouped under `## ready`, `## development`, and `## deferred`. Only consider bugs under `## ready`.
+2. If there are no bugs under `## ready`, report "No ready bugs in `./product/backlog/bugs.md`" and stop.
+3. Pick the bug to fix. Do **not** evaluate, rank, or compare the bugs for scope, tractability, or any other quality — the human who filed them decided they belong here:
+   - **If a specific bug is named in the task invocation** (e.g. `execute ai/tasks/fix-a-bug.md "<bug text>"`), fix that one. Find the entry in `./product/backlog/bugs.md` it refers to — the argument may be quoted text, a paraphrase, or a position such as "the second one". If no entry matches, report that no matching bug was found and stop.
+   - **Otherwise**, take the **first** bug listed under `## ready` (top of the list).
+
+   State which bug you selected in one sentence.
+4. **Replicate the reported failure** before writing any fix, so you can watch it fail:
+   - Prefer writing a failing automated test that exercises the reported scenario — this becomes the regression test in Step 4. Colocate it per the test conventions (`src/**/*.test.ts`, `web/src/**/*.test.tsx`).
+   - If a test cannot capture it, exercise the affected code path directly (a focused test, a `janus` CLI invocation, or a short throwaway script under `./temp/`) and observe the wrong behavior.
+   - Record exactly what you ran and the faulty behavior you saw — the wrong output, the error, or the missing result. You will reuse this in the plan (Step 3) and the PR (Step 10).
+5. Keep reproduction bounded: try at most two or three distinct approaches. If you still cannot reproduce the failure, do **not** fabricate a fix or invent a symptom, and do **not** switch to a different bug — report the selected bug, everything you tried, and stop.
+
+---
+
+## Step 2 — Determine the correct behavior
+
+Decide what the code *should* do, drawing on three sources in order:
+
+1. **The bug report** — what outcome does the reporter expect? Take it as the primary signal of intended behavior.
+2. **The functional specs** in `./product/specs/` — find the spec covering this area. If a spec describes the correct behavior, it is authoritative; the bug is the code diverging from the spec.
+3. **The code and its tests** — surrounding conventions, related passing tests, and adjacent behavior show what "correct" looks like when the spec is silent.
+
+State the correct behavior in one or two sentences before planning the fix. If the bug report, specs, and code genuinely conflict or leave the intended behavior ambiguous, stop and report the ambiguity rather than guessing.
+
+---
+
+## Step 3 — 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 and the root cause of the bug — fix the cause, not just the symptom.
+3. Choose a short, descriptive `kebab-case` name for the fix — call it `<bug-name>` (for example `orientation-reset-on-load`). Use this exact same name for the plan file at every stage below.
+4. Write a plan file following the format of existing plans in `./product/plans/complete/` — include a complexity rating, the root cause, the correct behavior (from Step 2), the reproduction (from Step 1), the approach, implementation steps, the regression test, and out-of-scope items. Write it to `./product/plans/draft/<bug-name>.md`.
+5. After the plan is written, move it from `./product/plans/draft/` to `./product/plans/ready/`. Use plain `mv` (not `git mv`) — the new plan file is not tracked by git yet, and `git mv` fails on an untracked file:
+   ```bash
+   mv ./product/plans/draft/<bug-name>.md ./product/plans/ready/<bug-name>.md
+   ```
+
+---
+
+## Step 4 — Implement the fix and its regression test
+
+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.
+
+The regression test is mandatory:
+
+- It must exercise the reported scenario from Step 1 and assert the correct behavior from Step 2.
+- **Prove it actually catches the bug.** The reliable path is the failing test you wrote in Step 1: you already watched it fail against the buggy code, so once the fix is in place, run it and confirm it now passes. If you did not write it test-first, add it now, confirm it passes with the fix, then prove it depends on the fix — either revert the fix, run the test to watch it fail, and re-apply the fix, or explain concretely why the assertion cannot hold without the fix.
+- Mirror the test style of the referenced test files (imports, helper patterns, assertion style).
+
+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 5 — Verify the fix
+
+1. Run `./scripts/run.mjs check-diff`. It must pass clean, including the new regression test.
+2. Re-run the reproduction from Step 1 and confirm the faulty behavior is gone — the scenario that used to fail now behaves correctly.
+3. If the plan's Verification section describes manual steps, perform them. If manual verification is not possible in this environment, note that in the report.
+
+---
+
+## Step 6 — Update or create spec files
+
+Every fix must be reflected in the functional specs under `./product/specs/`. After implementation and verification:
+
+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 correct behavior an existing spec already describes — align the spec with the now-correct behavior. 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 7 — Update help and public documentation if affected
+
+The fix only needs a documentation update if it changes behavior that `help.md` or `documentation/user-documentation/` already describes — a changed flag, a renamed command, a corrected default, a behavior that no longer matches what's written. Do not add new documentation for behavior that wasn't previously documented; that is out of scope for this task.
+
+1. Check `help.md` for any command, flag, or behavior description the fix changes. Update it in place if found.
+2. Check `documentation/user-documentation/` for any page describing the changed behavior. Update it in place if found.
+3. If neither documents the changed behavior, do nothing here — do not create new documentation.
+
+These files are markdown and do not affect `check-diff`, so no verification run is needed after this step.
+
+---
+
+## Step 8 — Promote the plan and remove the bug
+
+1. Move the plan file from `./product/plans/ready/` to `./product/plans/complete/`. Use plain `mv` (not `git mv`) — the plan file is still untracked until the PR workflow stages it:
+   ```bash
+   mv ./product/plans/ready/<bug-name>.md ./product/plans/complete/<bug-name>.md
+   ```
+2. Remove **only** the fixed bug's line from the `## ready` group in `./product/backlog/bugs.md`. Do not touch the `## development` or `## deferred` groups, the group headings, or any other bug entry.
+
+---
+
+## Step 9 — Final verification
+
+1. Run `./scripts/run.mjs check-diff` one last time. It must pass clean, including the regression test.
+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 10 — Open the pull request
+
+Execute `ai/tasks/open-feature-pull-request.md` in full — it owns the branch, commit, push, and PR-open workflow. Follow its steps as written, and additionally satisfy the two bug-specific requirements below.
+
+**Requirement 1 — use the `fix:` type.** The commit subject and PR title must use the `fix:` Conventional Commits type (that workflow's Step 3 and Step 6), for example `fix(web): reset image orientation on reload`.
+
+**Requirement 2 — document the replication in the PR body.** When you write the body (that workflow's "Behavior examples" and "How to verify" sections), include an explicit **Replication steps** account drawn from Step 1 and Step 2 of this task:
+
+- The exact steps to reproduce the original faulty behavior (commands, inputs, or user flow).
+- What the buggy behavior was — the wrong output, error, or missing result a reviewer would see without the fix.
+- What the correct behavior is now — what the same steps produce with the fix applied.
+- The name of the regression test that encodes this scenario and the file it lives in.
+
+Do not merge the PR — leave it open for a human.
+
+---
+
+## Step 11 — Report
+
+Give the user a short report in this exact shape:
+
+```
+Bug:            <the bug text from ./product/backlog/bugs.md>
+Reproduction:   <one-line summary of how you replicated the faulty behavior>
+Correct:        <one-line statement of the correct behavior>
+Root cause:     <one-line summary of the underlying cause>
+Plan:           ./product/plans/ready/<file> → ./product/plans/complete/<file>
+Complexity:     N/10
+Implementation: <one-line summary of the fix>
+Regression:     <the test that now guards this bug, and the file it lives in>
+Spec:           <spec file(s) created or updated, with one-line description of change>
+Docs:           <help.md/user-documentation file(s) updated, or "none needed">
+PR:             <url> (#<number>)
+Status:         open
+```
+
+Keep it brief. Done.

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

@@ -1,6 +1,8 @@
 # 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.
+Your job: pick the simplest issue from `./product/backlog/issues.md`, develop a plan to resolve it, implement the fix, update functional specs, update `help.md` and public documentation where the fix changes behavior they already document, 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, `help.md`, `documentation/user-documentation/`, the issues file, and the plan file's location — nothing else.
+
+**Project `./product/` directory.** Every `./product/...` path in this task refers to the product directory in the current working directory — the project being worked on — never to the Janissary codebase's own `product/` directory, even when this task file was launched from an absolute path inside the Janissary installation.
 
 **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.
 
@@ -8,8 +10,6 @@ Your job: pick the simplest issue from `product/backlog/issues.md`, develop a pl
 
 **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.
@@ -20,7 +20,7 @@ This overrides CLAUDE.md's "Capturing command output" guidance (write the output
 
 ### 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.
+Read any file in the repo. Edit source, tests, CSS, and spec files as the fix requires. Update `help.md` and files under `documentation/user-documentation/` when the fix changes behavior they already document. 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
 
@@ -28,7 +28,7 @@ Read any file in the repo. Edit source, tests, CSS, and spec files as the fix re
 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.
+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.
 
 ---
@@ -41,9 +41,9 @@ 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.
+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.
+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.
 
@@ -53,10 +53,10 @@ Execute `ai/tasks/prepare-workspace.md` in full before doing anything else.
 
 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/`:
+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
+   git mv ./product/plans/draft/<fix-name>.md ./product/plans/ready/<fix-name>.md
    ```
 
 ---
@@ -87,50 +87,63 @@ 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:
+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.
+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
+## Step 6 — Update help and public documentation if affected
+
+The fix only needs a documentation update if it changes behavior that `help.md` or `documentation/user-documentation/` already describes — a changed flag, a renamed command, a corrected default, a behavior that no longer matches what's written. Do not add new documentation for behavior that wasn't previously documented; that is out of scope for this task.
+
+1. Check `help.md` for any command, flag, or behavior description the fix changes. Update it in place if found.
+2. Check `documentation/user-documentation/` for any page describing the changed behavior. Update it in place if found.
+3. If neither documents the changed behavior, do nothing here — do not create new documentation.
+
+These files are markdown and do not affect `check-diff`, so no verification run is needed after this step.
+
+---
+
+## Step 7 — Promote the plan and remove the issue
 
-1. Move the plan file from `product/plans/ready/` to `product/plans/complete/`:
+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
+   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.
+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
+## Step 8 — 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
+## Step 9 — 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
+## Step 10 — 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>
+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>
+Docs:           <help.md/user-documentation file(s) updated, or "none needed">
 PR:             <url> (#<number>)
 Status:         merged
 ```

package/ai/tasks/improve-codebase.md

@@ -1,6 +1,6 @@
 # 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.
+Your job: act as a **supervisor** that continuously improves this codebase by running a loop. Each cycle you **inspect** the code, **select** the single most valuable improvement, **execute** the matching task playbook, **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:
 
@@ -20,8 +20,6 @@ The improvement work itself follows one of these existing single-purpose task pl
 
 **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.
@@ -82,7 +80,7 @@ State your pick in one sentence: the task playbook, the target file/function, an
 
 ### 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:
+Follow [`ai/tasks/<task>.md`](.) for the task you picked in Step 2, in full. 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.
@@ -126,7 +124,7 @@ git clean -fd
 
 ### 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.
+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** — follow every step of that playbook in order, same as you did for the improvement playbook in Step 3. 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).
 

package/ai/tasks/improve-modularity.md

@@ -6,8 +6,6 @@ Your job: make **one** small, safe change that lowers the complexity of **one**
 
 **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.**

package/ai/tasks/improve-namespacing.md

@@ -8,8 +8,6 @@ For example, the flat files `src/acp-loop.ts`, `src/acp-manager.ts`, `src/acp-ru
 
 **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.

package/ai/tasks/improve-plan.md

@@ -1,6 +1,8 @@
 # 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.
+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.
+
+**Project `./product/` directory.** Every `./product/...` path in this task refers to the product directory in the current working directory — the project being worked on — never to the Janissary codebase's own `product/` directory, even when this task file was launched from an absolute path inside the Janissary installation.
 
 **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.
 
@@ -8,8 +10,6 @@ This is a **planning** task, not pre-implementation. A good plan decides *what*
 
 **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.
@@ -26,7 +26,7 @@ Edit the **one plan file** you picked: correct it, disambiguate it, restructure
 
 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)).
+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.
 
 ---
@@ -40,7 +40,7 @@ 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.
+- 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.
 
@@ -51,7 +51,7 @@ State your pick in one sentence.
 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.
+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.
 
 ---
 
@@ -86,7 +86,7 @@ Edit the plan file to remove everything you found. Rules of thumb:
 
 ## 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/`:
+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.)
@@ -112,7 +112,7 @@ If the plan already has a complexity line, update it — after your improvements
 Then give the user a short report in this exact shape:
 
 ```
-Plan:        product/plans/draft/<file>
+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">

package/ai/tasks/improve-security.md

@@ -8,8 +8,6 @@ Your job: run the security tools, list **every** finding, automatically apply th
 
 **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.

package/ai/tasks/improve-style.md

@@ -6,8 +6,6 @@ Your job: run the CSS linter, pick the single most valuable fix, assess its risk
 
 **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. 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.

package/ai/tasks/improve-test-coverage.md

@@ -6,8 +6,6 @@ Your job: add tests that raise this project's test coverage. Do exactly **one fi
 
 **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. 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.

package/ai/tasks/merge-change-to-master.md

@@ -10,8 +10,6 @@ Every step is a script in `scripts/pr-*.sh`, invoked through the script runner.
 
 **Always run scripts in the foreground.** Never use `run_in_background` — each script must complete and return its exit code before the next step begins.
 
-**No subagents, no background agents.** Do every step yourself — never launch a subagent (Task/Agent tool, `fork`, or otherwise) to do any part of this task on your behalf.
-
 **Do not ask the user for input at any point.** Make all decisions autonomously — branch names, commit messages, PR titles and bodies. The only valid reason to stop is an unresolvable error.
 
 ---