@gavin-hu/my-pi-agent 0.16.0 → 0.18.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.16.0",
-  "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, file-read, check, memory, context, wechat, and bytefly.",
+  "version": "0.18.0",
+  "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, file-read, check, memory, context, session-bus, wechat, and bytefly.",
   "keywords": [
     "pi-package",
     "pi",
@@ -101,6 +101,7 @@
       "./extensions/file-open/index.ts",
       "./extensions/memory/index.ts",
       "./extensions/context/index.ts",
+      "./extensions/session-bus/index.ts",
       "./extensions/wechat/index.ts",
       "./extensions/bytefly/index.ts"
     ],
@@ -127,6 +128,7 @@
     "compat:versions": "bun run scripts/peer-versions.ts",
     "bench:render": "bun run scripts/render-bench.ts",
     "screenshot:file-browse": "bun run scripts/file-browse-shot.ts",
+    "screenshot:plan-flow": "bun run scripts/plan-flow-shot.ts",
     "screenshot:plan": "bun run scripts/plan-review-shot.ts",
     "screenshot:tools": "bun run scripts/tool-renderings.ts gallery assets/tool-renderings.png",
     "screenshot:tool-pngs": "bun run scripts/tool-renderings.ts tools assets/tools",
@@ -158,6 +160,7 @@
     "@types/bun": "latest",
     "@types/qrcode": "^1.5.5",
     "get-east-asian-width": "^1.6.0",
+    "playwright-core": "^1.64.1",
     "typebox": "^1.3.27",
     "typescript": "^5.6.0"
   }

package/skills/changelog/SKILL.md

@@ -1,48 +1,37 @@
 ---
 name: changelog
-description: "Maintain a Keep a Changelog file: draft the candidate bullet before implementation, record one user-visible bullet in the same commit, audit commits since the last tag for missing or weak entries, and curate a release section from the project's own rules. Use when planning, writing, or auditing a changelog or preparing a release, not for ordinary code edits."
+description: "Maintain a Keep a Changelog file: record one user-visible bullet in the same commit, audit commits since the last tag for missing or weak entries, and curate a release section from the project's own rules. Use when writing, auditing, or releasing a changelog, not for ordinary code edits."
 ---
 
 # Maintain the changelog
 
 This is a procedure, not a second policy. Read the project's instructions first;
-where they disagree with this skill, the project wins. There are four modes:
-**draft** (before the code exists), **record** (the default once it does),
-**audit**, and **release**. `/skill:changelog draft`, `... audit`, and
-`... release` name the others; with no mode, infer draft versus record from
-whether the behavior already exists.
+where they disagree with this skill, the project wins. There are three modes:
+**record** (the default), **audit**, and **release**. `/skill:changelog` records;
+`... audit` and `... release` name the others.
 
 ## 1. Read the project profile
 
-Before editing, find:
+In this package the profile is written down; read it rather than rediscover it:
 
-- the changelog file and its preamble;
-- the category spelling and order;
-- the scope prefix, and whether one bullet per extension or module is required;
-- whether the entry belongs in the same commit as the change;
-- the release document, version bump, link refs, and tag/push/publish order;
-- the check command and any release-consistency test.
+- [`../../CHANGELOG.md`](../../CHANGELOG.md) — the preamble, the scope prefixes,
+  and the bullet shape in use;
+- [`../../AGENTS.md`](../../AGENTS.md) — the entry lands in the same commit as the
+  change, and a behavior change also updates the two entry READMEs and `docs/`;
+- [`../../docs/development.md#release`](../../docs/development.md#release) — the
+  normative release procedure: version bump, link refs, tag and push order;
+- [`../../test/release.test.ts`](../../test/release.test.ts) — the guard on
+  subsection names, order, emptiness, and the version pin.
+
+Everywhere else, find the same six things: the changelog and its preamble, the
+category spelling and order, the scope prefix and one-bullet-per-unit rule,
+whether the entry ships with the change, the release document with its bump and
+push order, and the check command with any release-consistency test.
 
 State the profile in one short paragraph. Do not invent a rule the project never
 stated; ask instead.
 
-## 2. Draft before implementing
-
-For a new feature, draft the bullet in the plan or a scratchpad, not in
-`CHANGELOG.md`.
-
-- Write one line in the project's shape: ``- `scope`: <what the user can now do>``.
-- If you cannot state the outcome, or need several unrelated bullets, the feature
-  is not scoped yet; split it or ask before coding.
-- Name the intended category and any migration, breaking change, or required
-  action now, while the scope is still open.
-- Use the draft as the acceptance criterion: implementation is done when the
-  behavior it describes is true and tested.
-- Keep it out of the changelog until the code lands; a draft is not a shipped
-  claim. Update it when the outcome changes, then move it into `[Unreleased]` in
-  the same commit as the code (**Record**).
-
-## 3. Classify the change
+## 2. Classify the change
 
 It qualifies when a user can observe it: behavior, a CLI/tool/command surface, a
 config default, packaging, security, or a documented promise that is now true or
@@ -57,7 +46,7 @@ be one bullet if users see one outcome; two observable changes are two bullets.
 Ask when the outcome is unclear. Never invent an entry to make an audit look
 complete.
 
-## 4. Record
+## 3. Record
 
 - Write the entry in the same commit as the change. If the change is already
   pushed without one, add a follow-up commit rather than rewriting history.
@@ -68,24 +57,40 @@ complete.
 - Exclude file names, internal helpers, test counts, commit hashes, and vague
   words such as "various" or "improvements".
 - Match the file's voice and tense. Do not add marketing.
+- A behavior change also updates its row in the catalog tables of
+  [`../../README.md`](../../README.md) and
+  [`../../README.zh-CN.md`](../../README.zh-CN.md) plus the `docs/` guide it
+  belongs to; the changelog is this skill's subject, not its only file. A skill's
+  change updates its `SKILL.md` and its README row together.
 - Re-read immediately before editing, append within the category, and preserve
   other bullets and concurrent edits. Never create a second category heading.
 
+Shape: one blank-line-separated bullet per outcome, wrapped near 80 columns, the
+scope in backticks followed by a colon. The scope is the extension or module name,
+spelled as this package spells it — `bytefly`, `plan`, `wechat`, `todo` — or
+`lib`, `docs`, `test`, `ci`, `skills`. A bullet with no scope, or with a name the
+package does not use, is a defect. A bullet may run several sentences — say what
+the user sees, what it replaced, and any required action. Brevity is not the
+goal; vagueness is the defect.
+
 Good:
 
 ```text
-- `billing`: invoices now show the tax line separately.
-- `config`: `oldKey` is no longer read; run `bun run config:migrate`.
+- `config`: the report now says what its percentages are shares of. A
+  `Composition · 11k estimate` header sits above the rows, and a disabled
+  compaction no longer prints a headroom figure for a threshold that will never
+  fire.
+- `cli`: `oldKey` is no longer read; run `bun run config:migrate`.
 ```
 
 Bad:
 
 ```text
-- `billing`: refactored invoice rendering and added tests.
+- `config`: refactored invoice rendering and added tests.
 - `misc`: improvements.
 ```
 
-## 5. Audit (read-only)
+## 4. Audit (read-only)
 
 1. Find the last tag: `git describe --tags --abbrev=0`, or the project's
    equivalent.
@@ -107,29 +112,36 @@ since the tag contain user-visible changes.
 Do not edit during the audit unless the user asks. If they do, return to
 **Record** and make only the entries the evidence supports.
 
-## 6. Release (only when asked)
+## 5. Release (only when asked)
 
-Follow the project's release document; it is normative. This is a checklist, not
-a replacement:
+The project's release document is normative — in this package
+[`../../docs/development.md#release`](../../docs/development.md#release), guarded
+by [`../../test/release.test.ts`](../../test/release.test.ts). This is a
+checklist, not a replacement:
 
 - Confirm the version and the SemVer reason with the user.
 - Move every `[Unreleased]` entry under `## [X.Y.Z] - YYYY-MM-DD`; leave an empty
   `[Unreleased]` heading.
-- Bump every manifest and update the compare and release link refs.
-- Run the project's release checks.
-- Tag, push, and publish only with explicit approval, in the project's order.
+- Bump every manifest and update the compare and release link refs, in the same
+  commit as the movable part; the version in the manifest and the newest dated
+  heading must agree or the release test fails.
+- Run the project's release checks, then `bun test test/release.test.ts` for the
+  version and subsection rules.
+- Tag, push, and publish only with explicit approval, in the project's order. The
+  order matters: push the tag with `main`, never after it.
 - Keep the release commit mechanical: no behavior, code, or unrelated docs.
-- Use that section as the release body; do not add extra prose.
+- Use that section as the release body (`bun run release:notes X.Y.Z` prints it);
+  do not add extra prose.
 
-## 7. Quality gate
+## 6. Quality gate
 
 - One bullet per user-visible change; every bullet starts with a scope and a user
-  outcome.
+  outcome, and may take several sentences to state it.
 - No internal-only or duplicate entries, and no empty category headings.
 - No entry for a change that shipped before its heading.
 - Links and versions agree; the project check passes.
 
-## 8. Report and stop
+## 7. Report and stop
 
 Say what was recorded, what the audit found, or what the release moved. List what
 was deliberately left out and why. When nothing qualifies, say so. Stop before

package/skills/init/SKILL.md

@@ -1,34 +1,37 @@
 ---
 name: init
-description: "Initialize or refresh AGENTS.md through a built-in interactive interview and a reviewed plan. Use when the user runs /skill:init or asks to set up project agent instructions."
+description: "Initialize or refresh a project's agent instructions (AGENTS.md, or AGENTS.override.md when it shadows AGENTS.md) through a built-in interactive interview and a reviewed plan. Run /skill:init to start it."
 disable-model-invocation: true
 ---
 
-# Initialize AGENTS.md
+# Initialize agent instructions
 
-Goal: create or update **`AGENTS.md` at the project root** by combining repository
+Goal: create or update the instruction file Pi reads at the **project root** —
+`AGENTS.md`, or `AGENTS.override.md` when one shadows it — by combining repository
 evidence with a short, built-in interview. The interview captures intent the code
 cannot show; the repository supplies every command, path, and convention that can
 be verified. Plan mode is the review gate: no write happens before approval.
 
 `/skill:init` loads this skill. If plan mode is not active, call
 `enter_plan_mode` and wait for confirmation. Keep the interview and the plan
-review in that order; do not write the file early to save a step.
+review in that order; do not write the file early to save a step. A declined plan
+mode ends the skill: stop and explain, rather than writing directly.
 
 ## Workflow
 
 ```text
 /skill:init
   └─> plan mode (read-only)
-        └─> recon: manifests, docs, CI, tests, existing instructions
-        └─> interview: one built-in question call (at most 4)
+        └─> recon: effective instruction file, sourced evidence, existing instructions
+        └─> interview: one built-in question call (at most 4), minus resolved facts
               ├─ answers ───────────────> reconcile with evidence
               └─ unavailable/cancelled ─> evidence + recorded assumptions
         └─> draft: new file, exact edits, or an honest no-op
         └─> quality gate
+        └─> plan outline with ## Steps and ## Verification
         └─> write_plan ──> exit_plan_mode
                              ├─ not approved ──> refine the same plan
-                             └─ approved ──────> write/edit AGENTS.md
+                             └─ approved ──────> write/edit the target
                                                  └─ read back + quality gate
 ```
 
@@ -37,35 +40,34 @@ before the interview. Read
 [`references/agents-md-quality.md`](./references/agents-md-quality.md) before
 drafting and again before writing the plan.
 
-## Repository states
+## Default question sets
 
-| State | Interview | Outcome |
-|---|---|---|
-| Existing project, no `AGENTS.md` | Purpose (only if unclear; otherwise Priorities), Verify, Rules, Isolation | New smallest-useful file. |
-| Existing `AGENTS.md` | Existing file, Preserve (only if sections are unclear), Priorities (only if stale), Rules | Exact edits that preserve correct instructions, or a no-op. |
-| Empty or near-empty repository | Stack, Commands, Purpose, Priorities | Honest minimal file from the answers and known facts only. |
-| Related instruction files exist | Swap Related docs in for Preserve or Rules | Describe the relationship; do not duplicate the other file. |
-| Git repository with no guidance | Isolation, Verify, Done, External changes | Prefer this set over a generic workflow question. |
-| No UI, inactive tool, or cancelled interview | Skip the call; record the gaps as assumptions | Evidence-based draft; the plan review remains the place to correct it. |
-
-The full bank, selectable alternatives, and option wording live in
-`references/interview-questions.md`. The table above is the default, not a menu to
-exhaust.
+The bank's deterministic default sets, in
+[`references/interview-questions.md`](./references/interview-questions.md), decide
+the first call for each repository state. They are the only copy; do not restate
+them here. Drop a question the evidence sheet already answers.
 
 ## 1. Recon
 
-- Read existing instruction files first: `AGENTS.md`, `AGENTS.override.md`,
-  `CLAUDE.md`, and nested `AGENTS.md` files. Note how they relate; do not silently
-  absorb or replace one.
+- Resolve the instruction file Pi reads in this directory first. A root
+  `AGENTS.override.md` replaces `AGENTS.md` and `CLAUDE.md` in the same directory —
+  it still applies below — so it is the target; a new `AGENTS.md` beside it would
+  be dead text. Report an override above the project root or in the agent
+  directory, but never edit outside the project.
+- Read the remaining instruction files (`CLAUDE.md`, nested `AGENTS.md` and
+  overrides) and note how they relate; do not silently absorb or replace one.
 - Read the files that define the project: manifests, lockfiles, README, docs
   index, source layout, tests, CI, formatter and linter configuration.
-- Build a short evidence sheet: stack, layout, install/test/lint/typecheck
-  commands, validation gates, release path, and existing rules.
-- List the gaps the interview must fill. Stop the first pass once the shape is
+- Build a sourced evidence sheet: stack and package manager from the manifest and
+  lockfile; every install/test/lint/typecheck command with the file that defines
+  it; generated, vendored, and build-output paths from `.gitignore` and the tree;
+  workspace packages and boundaries; purpose and audience from the README lead or
+  manifest description; validation gates, release path, and existing rules. Mark
+  each field `resolved` or `unknown`.
+- The unknown fields are the interview gaps. Stop the first pass once the shape is
   clear; do not investigate the whole repository before asking.
 - In an empty or near-empty repository, record that evidence is absent. Never
   invent a command from a language's usual tooling.
-- Check that any command you plan to record is copied from a file that defines it.
 - Use `read`, `grep`, `find`, and `ls`. For a large repository, delegate a
   read-only survey to the `explorer` or `reviewer` subagent.
 - Do not read or copy secrets, credentials, tokens, or private environment
@@ -74,14 +76,19 @@ exhaust.
 ## 2. Interview
 
 Use `ask_user_question` once with at most four questions from the built-in bank.
-Choose the deterministic default set for the repository state.
+Choose the bank's deterministic default set for the repository state, then drop
+every question the evidence sheet already answers: `Purpose` only when README and
+manifest are silent, `Verify` only when detected commands are missing or conflict,
+`Sensitive` only when generated-path evidence leaves a boundary unclear. Ask the
+bank's `Target` question when a root override exists.
 
 - One call is the default. Make a second call only when an answer leaves a
   material ambiguity that changes what the file says; do not ask a second round
   merely to collect preferences.
 - Fill option labels with evidence: the detected test command, the actual package
-  manager, the real instruction file names. Keep a free-form escape on every
-  question whose answer cannot be enumerated.
+  manager, the real instruction file names. Four options at most, and never one of
+  them for a free-form escape: the tool always adds Other, so an "Other" or "None of
+  these" label spends a real answer's slot.
 - Ask only what the evidence cannot answer. Do not ask for the stack when a
   manifest states it, or for a command already documented in CI.
 - Never ask for secrets, credentials, tokens, environment values, or personal
@@ -103,15 +110,23 @@ Treat answers and evidence as different kinds of fact:
 - If they conflict, record the conflict, what the draft uses, and the alternative
   in the plan. Do not quietly rewrite the user's intent or invent a command to
   match it.
+- A command, path, or package with no source in the evidence sheet stays out or is
+  asked; it is never inferred from convention.
+
+The target is the effective file from recon. If a root `AGENTS.override.md`
+exists, edit it. Never write an `AGENTS.md` that the override shadows; if the user
+chooses to consolidate into `AGENTS.md`, the plan removes or renames the override
+in the same step and preserves its instructions.
 
 Then choose the outcome:
 
-- **No `AGENTS.md`** — draft the smallest useful file. Use the sections this
+- **No instruction file** — draft the smallest useful file. Use the sections this
   repository needs; omit empty ones.
-- **Existing `AGENTS.md`** — preserve correct instructions and propose exact
-  edits for the rest. If the user chose to rewrite, the plan must still list what
-  is being removed.
-- **Accurate `AGENTS.md`** — propose no edits and explain the no-op with evidence.
+- **Existing instruction file** — preserve correct instructions and propose exact
+  edits for the rest, shown as a fenced before/after diff. If the user chose to
+  rewrite, the plan must still list what is being removed.
+- **Accurate instruction file** — propose no edits and explain the no-op with
+  evidence.
 - **Empty or near-empty repository** — say plainly that it is newly initialized,
   record the interview facts, and omit commands and architecture that do not
   exist yet.
@@ -132,31 +147,51 @@ evidence, not as a replacement for reading the repository.
 
 ## 5. Plan and review
 
-- Save the proposal with `write_plan`. The plan must include:
-  - the recon summary and the evidence that supports the draft;
-  - the questions asked, the answers, and how each answer was used;
-  - the full draft for a new file, or the exact edits for an existing one;
-  - assumptions, conflicts, and unanswered gaps from a cancelled or unavailable
+- Save the proposal with `write_plan` in the documented outline. The plan must
+  include:
+  - `## Goal` — the outcome for the instruction file;
+  - `## Context` — the sourced evidence sheet, the effective-file finding, and the
+    questions asked with how each answer was used;
+  - `## Approach` — the full draft for a new file, or a fenced before/after diff
+    for edits;
+  - `## Steps` — one top-level bullet per apply action: write or edit the target,
+    read it back, run the check. Without this heading approval seeds the
+    shallowest list anywhere, which is the draft rather than the actions;
+  - `## Risks` — assumptions, conflicts, and gaps from a cancelled or unavailable
     interview;
-  - a verification step that reads the written file back against the checklist.
+  - `## Verification` — the project's own check when it declares one (`run_check`,
+    or the narrower docs or structure test that guards the instruction file), then
+    reading the written file back against the checklist.
 - Call `exit_plan_mode` with the returned path.
 - If the user refines or rejects the plan, stay in plan mode, rewrite the same
   plan file with `write_plan` (`plan_path`), and present it again.
-- No `AGENTS.md` write may happen before approval.
+- No write to the target may happen before approval.
 
 ## 6. Apply and verify
 
-- Create a new file with `write`, or update an existing one with `edit`.
-- Change only `AGENTS.md`. Do not touch unrelated files.
+- Create a new file with `write`, or update the target with `edit`.
+- Change only the instruction files the approved plan names: the target, and an
+  override the plan removes or renames while consolidating. Do not touch unrelated
+  files.
 - Read the result back from disk and rerun the quality checklist against what is
   actually there, not what you intended to write.
+- Run the plan's verification step. A check that fails on the written file is the
+  report's follow-up, not a success; a check that fails for something the
+  instruction file cannot cause is named as an unrelated failure rather than
+  blamed on the draft.
 - Report the path, what the file covers, whether the interview was answered or
   fell back to assumptions, and any real follow-up. Name a missing fact instead of
   inventing it.
 
 ## Boundaries
 
-- One target: `AGENTS.md` at the project root selected in the plan.
+- One target for the instructions: the instruction file Pi reads at the project
+  root — `AGENTS.override.md` when one exists, otherwise `AGENTS.md`, as selected
+  in the plan.
+- A consolidation edits the file it absorbs only when the approved plan names it;
+  otherwise the other file is left alone.
+- Never leave a written `AGENTS.md` shadowed by a root override, and never edit an
+  override outside the project root.
 - Plan mode is mandatory. If it is unavailable, stop and explain why instead of
   writing directly.
 - The built-in bank is the default; one custom gap question is allowed only when

package/skills/init/references/agents-md-quality.md

@@ -9,6 +9,8 @@ invented command.
 
 - [ ] The first call used the deterministic default set for the repository state.
 - [ ] At most four questions were asked in the call.
+- [ ] No question offered more than four options, and none spent one on a free-form
+      escape the tool already provides.
 - [ ] Options were filled from evidence where the bank names commands, files, or
       instruction documents.
 - [ ] No question duplicated a fact the recon already answered.
@@ -27,12 +29,24 @@ invented command.
       plan, with the chosen resolution.
 - [ ] The plan names which questions were asked and what the user answered.
 
+## Target file
+
+- [ ] The plan names the instruction file Pi reads in the target directory.
+- [ ] A root `AGENTS.override.md` is the target, or the plan removes or renames it
+      while consolidating its instructions into `AGENTS.md`.
+- [ ] The written file is not an `AGENTS.md` that a root override shadows.
+- [ ] An override above the project root or in the agent directory is reported,
+      not edited.
+
 ## Evidence accuracy
 
-- [ ] Every command is copied from a manifest, script, Makefile, CI file, or docs
-      page that defines it. No command is guessed.
+- [ ] Every command is paired with the file that defines it in the evidence sheet.
 - [ ] Every path and package name exists in the repository as written.
 - [ ] Every claimed convention is visible in the code or contributor docs.
+- [ ] Generated and vendored exclusions name paths that exist and are backed by
+      `.gitignore` or build output.
+- [ ] Purpose came from the README lead or manifest description, or was asked.
+- [ ] No field marked `resolved` was asked again in the interview.
 - [ ] Unknown facts are omitted or named as unknown. They are never filled with
       plausible-sounding placeholders.
 - [ ] An answer that contradicts the code is treated as intent, not as evidence
@@ -76,12 +90,20 @@ invented command.
       `AGENTS.md`; the relationship is stated instead.
 - [ ] Two sections do not give the same instruction.
 
+## Plan and review
+
+- [ ] The plan uses `## Steps` and `## Verification`.
+- [ ] Each top-level step is an apply action, not a bullet from the draft.
+- [ ] An existing-file change is shown as a before/after diff, not prose edits.
+
 ## Existing files
 
 - [ ] Correct existing instructions are preserved.
 - [ ] Stale instructions are changed only when the replacement is supported by
       repository evidence or an explicit answer.
 - [ ] The plan lists exact edits, not a wholesale rewrite.
+- [ ] An override that is consolidated is removed or renamed in the same step, and
+      its instructions are preserved.
 - [ ] A rewrite records what is being removed and why.
 - [ ] A genuinely accurate file produces a no-op plan instead of churn.
 
@@ -97,6 +119,8 @@ invented command.
 ## Final read-back
 
 - [ ] The written file matches the approved plan.
+- [ ] The project's own check passed against the written file, or the report names the
+      failure it returned.
 - [ ] The file was read back from disk, not recalled from memory.
 - [ ] Only `AGENTS.md` changed.
 - [ ] The report names the path, whether the interview was answered or fell back

package/skills/init/references/interview-questions.md

@@ -5,6 +5,13 @@ The `init` skill selects from this bank. It is a menu, not a checklist: one
 call is allowed only for a material ambiguity. Never ask for secrets,
 credentials, tokens, environment values, or personal data.
 
+Every select question lists its options inside `Shape`, separated by `;`, between
+two and four of them. Anything after ` — ` is a note rather than an option, and
+the tool's free-form **Other** is never listed as one: it is always offered, so a
+label spent on it costs a real answer. In this package, `test/skill-bank.test.ts`
+holds these tables to that convention, so an over-long list fails the check rather
+than the interview.
+
 ## Consolidation rules
 
 The bank merges questions that would otherwise create two copies of the same
@@ -14,7 +21,11 @@ answer:
   first decision an agent makes.
 - **Done** absorbs testing and documentation expectations: both define when a
   task is complete.
-- **Sensitive** absorbs generated, vendored, and secret-bearing paths.
+- **Sensitive** is the fallback for generated, vendored, and secret-bearing
+  boundaries that `.gitignore` and build-output evidence cannot settle.
+- **Target** settles which file is written when a root `AGENTS.override.md`
+  exists; Related docs still covers `CLAUDE.md` and nested files once the target
+  is fixed.
 - **External changes** absorbs dependency and network policy.
 - **Commits** absorbs branch naming.
 - **Scope** and **Related docs** stay separate because they decide where the file
@@ -26,25 +37,29 @@ Use the first matching row. Fill option labels with evidence before asking.
 
 | Repository state | First four questions |
 |---|---|
-| Existing project, no `AGENTS.md` | Purpose (only if unclear; otherwise Priorities), Verify, Rules, Isolation |
+| Existing project, no `AGENTS.md` | Purpose (only if README and manifest are silent; otherwise Priorities), Verify (only if commands are missing or conflict; otherwise Done), Rules, Isolation |
 | Existing project, `AGENTS.md` present | Existing file, Preserve (only if sections are unclear), Priorities (only if stale), Rules |
 | Empty or near-empty repository | Stack, Commands, Purpose, Priorities |
-| Related instruction files present | Swap Related docs in for Preserve or Rules |
+| Related instruction files present | Target first when a root override exists; otherwise swap Related docs in for Preserve or Rules |
 | Git repository with no guidance | Isolation, Verify, Done, External changes |
 | No UI, inactive tool, or cancelled interview | No call; record the gaps as assumptions |
 
+A field the evidence sheet resolves is dropped, and the parenthesised fallback
+keeps the call at four questions only when the field is unknown. A root
+`AGENTS.override.md` adds `Target` before any other state question.
+
 ## Core questions
 
 | Header | Question | Shape | Selected when |
 |---|---|---|---|
 | Purpose | What is this project, and who will agents work on it for? | Free-form | README and manifest do not state the purpose and audience, or the repository is empty/near-empty. |
-| Verify | Which commands should an agent trust to verify a change? | Multi-select: detected install, build, test, lint, and typecheck commands, plus No reliable command yet; free-form Other for a missing command | Detected commands conflict or are ambiguous, or no command was found. |
+| Verify | Which commands should an agent trust to verify a change? | Multi-select: the detected full check; the detected test command; one file's test command; no reliable command yet — Other takes a command the recon missed | Detected commands conflict or are ambiguous, or no command was found. |
 | Rules | What should an agent know that is not obvious from the code? | Free-form | No explicit conventions, invariants, style rules, or traps are found in the source, docs, or contributor files. |
 | Isolation | How should agents isolate and land work? | Single-select: Worktree per task, then PR; Branch in the current checkout, then PR; Commit directly; Follow repository instructions | The project is a Git repository with no stated isolation or branch rule. |
-| Done | What must be true before a task is done? | Multi-select: Tests pass; Lint and typecheck pass; Docs and changelog updated; Diff self-reviewed; Pull request opened | No contributor guide defines done, test level, or documentation expectations. |
-| Sensitive | Are any files, directories, or workflows off-limits for agents? | Free-form, including generated, vendored, and secret-bearing paths | Access boundaries are unclear, or generated, vendored, or secret-bearing paths need explicit exclusion. |
+| Done | What must be true before a task is done, on top of the landing rule? | Multi-select: Tests pass; Lint and typecheck pass; Docs and changelog updated; Diff self-reviewed — the pull request belongs to Isolation or Commits | No contributor guide defines done, test level, or documentation expectations. |
+| Sensitive | Are any files, directories, or workflows off-limits for agents? | Free-form, including generated, vendored, and secret-bearing paths | Generated-path evidence leaves a boundary unclear, or a workflow boundary is not visible in the files. |
 | External changes | May an agent add dependencies or use the network? | Single-select: Yes, when needed; Ask first; Offline and no new dependencies | A manifest exists and dependency, package-install, or network rules are unclear. |
-| Existing file | How should the `init` skill handle the current `AGENTS.md`? | Single-select: Review and update in place; Keep it and only append missing guidance; Rewrite it from this interview | `AGENTS.md` already exists. |
+| Existing file | How should the `init` skill handle the current instruction file? | Single-select: Review and update in place; Keep it and only append missing guidance; Rewrite it from this interview | The target instruction file already exists. |
 
 ## State questions
 
@@ -52,18 +67,19 @@ Use the first matching row. Fill option labels with evidence before asking.
 |---|---|---|---|
 | Stack | What are you building, and with which language or framework? | Free-form | The repository is empty/near-empty, or no manifest or README states the stack. |
 | Commands | What install, build, test, lint, and typecheck commands do you intend to use? | Free-form, with None yet accepted | The repository is empty/near-empty and no real command exists to copy. |
-| Related docs | How should `AGENTS.md` relate to existing instruction files? | Single-select: Link to them and add only gaps; Consolidate them into `AGENTS.md`; Leave them alone | `CLAUDE.md`, `AGENTS.override.md`, or a nested `AGENTS.md` exists. |
-| Preserve | Which current instructions must stay? | Free-form | `AGENTS.md` exists and its authoritative sections are unclear. |
-| Scope | Where should `AGENTS.md` apply? | Single-select: Repository root only; Root plus package-level files; Follow an existing instruction file | The repository is a monorepo, has nested packages, or already has a related instruction file. |
+| Target | Which instruction file should `init` maintain? | Single-select: Edit `AGENTS.override.md`; Consolidate into `AGENTS.md` and remove the override — the first keeps Pi's effective file, the second unshadows `AGENTS.md` | A root `AGENTS.override.md` exists. |
+| Related docs | How should the target instruction file relate to existing instruction files? | Single-select: Link to them and add only gaps; Consolidate them into the target file; Leave them alone | `CLAUDE.md` or a nested `AGENTS.md` exists. |
+| Preserve | Which current instructions must stay? | Free-form | The target instruction file exists and its authoritative sections are unclear. |
+| Scope | Where should the instruction file apply? | Single-select: Repository root only; Root plus package-level files; Follow an existing instruction file | The repository is a monorepo, has nested packages, or already has a related instruction file. |
 
 ## Optional follow-ups
 
 | Header | Question | Shape | Selected when |
 |---|---|---|---|
-| Priorities | What should agents optimize for here? | Multi-select: Correctness and safety; Small, reviewable changes; Fast iteration; Test coverage; Match existing style | No `AGENTS.md` yet, or the current priorities are absent or ambiguous. |
+| Priorities | What should agents optimize for here? | Multi-select: Correctness and safety; Small, reviewable changes; Fast iteration; Match existing style — test coverage belongs to Done | No instruction file yet, or the current priorities are absent or ambiguous. |
 | Planning | When should an agent plan before acting? | Single-select: Non-trivial or multi-file work; Every task; Only when asked; Never | No plan-mode or workflow guidance exists. |
 | Commits | What commit convention and branch naming should agents follow? | Single-select: Conventional Commits with type/scope; Plain descriptive messages; Repository-defined convention; No preference | No commit or branch guidance exists in docs or CI. |
-| Release | What release or versioning process must an agent follow? | Single-select: Maintainer handles releases; Follow documented release steps; No release process; free-form Other | The project is published or versioned and the process is unclear. |
+| Release | What release or versioning process must an agent follow? | Single-select: Maintainer handles releases; Follow documented release steps; No release process — Other takes a process this list misses | The project is published or versioned and the process is unclear. |
 | Performance | Are there performance budgets or hot paths to protect? | Free-form | The project exposes performance-sensitive code or has benchmarks. |
 | Environment | What local services or setup steps does an agent need? | Free-form, no secrets | Setup requires services, databases, or environment configuration that is not documented. |
 | Finish | Anything else the next agent should know? | Free-form | Always optional, at most once. |
@@ -72,9 +88,15 @@ Use the first matching row. Fill option labels with evidence before asking.
 
 - Ask at most four questions in one call, ordered by impact: state-specific
   question first, then command verification, then conventions and limits.
+- Offer at most four options per question, filled from evidence, and never spend one
+  on a free-form escape the tool already provides.
 - Use the deterministic default set for the state. Do not pick a random subset.
-- Never ask for something the recon already answered, and never ask for a secret
-  or credential.
+- Never ask for something the evidence sheet already resolved, and never ask for a
+  secret or credential.
+- `Purpose`, `Verify`, and `Sensitive` are fallbacks: ask each only when the
+  evidence sheet cannot answer it.
+- When a root `AGENTS.override.md` exists, ask `Target` before drafting; a target
+  that keeps the override is edited in place, and a consolidation removes it.
 - One custom gap question is allowed only when no bank entry covers a material
   fact. It counts toward the four-question cap.
 - One follow-up call is allowed only when an answer creates a material ambiguity.