Bankai handbooks — the resolved set, cited, never improvised

No fixed mode. This skill is consulted from whichever mode is doing the work that needs a
citation — most often Enhancer (building in a Bankai-consuming product repo), sometimes Transmuter or
Conjurer. Name that mode when you invoke this; this skill only resolves the set the citation draws
from.

The handbooks in zheref/bankai-handbooks — public, MIT — are the single canonical source for
Bankai work: the five general handbooks, the four stack handbooks, CONSTITUTION.md (CON-{n}) and
CONVENTIONS.md, exactly as CON-13 names them. They moved there on 2026-09-28 out of the frozen
<reference-repo> (that repository's MIGRATION.md records what came from where, what was renamed
and what was left behind). Hatsu reads them from a local checkout at the tag its own registry pins
— nen/repos.json → maintained_tools → zheref/bankai-handbooks → pinned (v0.6.0 as of this
port; read the file, never this line). Load the right ones and no more — a rule cited from
memory is a rule that has already drifted, and this is not a hypothetical: the retired skill's own
"always load" list went stale twice, by its own repository's history, not by passive drift. In the
frozen predecessor, 3a463b4 (2026-08-08) added ux-baseline.md to handbooks/INDEX.md's table
without touching the retired skill's hardcoded list; c711f4e (2026-08-20) added
quality-baseline.md to that same table and edited the retired skill file itself in the same
diff — yet still left its "always load" prose at three files. Two chances to fix it, both missed:
the set is five files today (§ 2 below; recorded live in docs/ab/bankai-handbooks.md § 1 against
the frozen source, re-verified against handbooks/INDEX.md at zheref/bankai-handbooks v0.6.0).
This is exactly the repeated maintenance failure the read handbooks/INDEX.md fresh every time
rule exists to prevent — resolve fresh, every time; never carry a fixed list forward from a previous
session or from this file's own prose.

The pin is a tag, read from the registry — verify the checkout sits on it with
git -C "$canon" describe --tags --exact-match (§ 0) before trusting it (a stale local clone
silently drifts off the pin; verified live at this port: v0.6.0). <reference-repo> is
FROZEN and is not read any more: its handbooks/ are the pre-migration copy at v0.11.3, not
canon, and nothing is ever written to it — no PRs, no branches, no issues, nothing. A handbook
gap found while resolving is a finding to raise to the human (§ 4); its landing repository is now
zheref/bankai-handbooks, at G4, and only on the maintainer's word.

CON-13, as rewritten at handbook set v0.6: one canonical source, a generated, pinned
mirror everywhere canon is read. A consumer carries, in the rules location of every agent surface
it declares, a mirror rendered from a tag of bankai-handbooks — `$limbo`
is the skill that renders and checks it (nen canon mirror generate / check, the generated-from
marker as the ownership claim) — never hand-edited, a build artifact and not a
second source — and a live nen canon resolve against a checkout at the same pin returns the
same canon. This skill takes the live path: it resolves from the checkout at the pin, because
the computation is cheap and exact, and it never treats a product repo's mirror as its source. Point
--repo at a registry (§ 1) and open the resolved files in the bankai-handbooks checkout (§ 2).

---

0. Locate the canon checkout — or fetch it at the pin

The handbooks are files on disk, so every step below needs a checkout of zheref/bankai-handbooks
sitting on the pinned tag. No nen verb fetches one (nen bootstrap fetches nen itself) — that is
residue, named here, and the shell below is its one carve-out. It is deterministic: an explicit
location or a cache slot keyed on the repository, never the cwd; a public, anonymous, read-only clone;
and the tag re-verified on every run.

pin='<nen/repos.json → maintained_tools → zheref/bankai-handbooks → pinned, read by you; e.g. v0.6.0>'
canon="${HATSU_CANON_CHECKOUT:-${XDG_CACHE_HOME:-$HOME/.cache}/hatsu/canon/zheref/bankai-handbooks}"
[ -d "$canon/.git" ] || git clone --quiet https://github.com/zheref/bankai-handbooks.git "$canon"
git -C "$canon" fetch --quiet --tags origin
git -C "$canon" -c advice.detachedHead=false checkout --quiet "$pin"
git -C "$canon" describe --tags --exact-match        # must print exactly $pin

• $pin is read off nen/repos.json, never remembered — the same no-jq reading $ten § 0
  applies to nen/contract.json. A registry entry with no pinned is a missing-configuration
  finding, never a fall-back to main.
• HATSU_CANON_CHECKOUT names a checkout the maintainer already keeps (asked for once as
  missing-configuration, then carried as a shell variable in the block that uses it); absent, the
  cache slot is used and created on first use. Nothing here writes into the repository itself.
• The describe line is the gate. Anything but the pin — a branch, a newer tag, fatal: no tag exactly matches — is a G5 stop naming what it printed, never a read of whatever happens to be
  checked out. A dirty tree (git -C "$canon" status --porcelain non-empty) is the same stop.
• $ten does not yet place this checkout at warm-up — a follow-up for the warm-up, named in the
  PR that made this port. Until then every run of this skill (and of bankai-quality, which reads the
  same $canon) runs this block first.

1. Resolve the scenario

nen repo scenario --repo <registry checkout> --target <owner/name>

nen repo scenario reads the scenario recorded for --target under consumers[] in --repo's
nen/repos.json — and nen canon resolve (§ 2) reads the same field from the same registry,
deriving the stack path from the string alone (src/canon/resolve.ts: neither verb opens a handbook
file). So --repo here names the registry, not the handbooks, and which checkout that is has two
answers today — tried in this order, never guessed past:

1. zheref/bankai-handbooks' own nen/repos.json — the consumer registry CON-13 names. At
   v0.6.0 it records no consumers: the repository is public and the estate's product
   repositories are private, so they are not named there. Every --target is therefore refused today
   with the verb's own sentence — verified live at nen 0.15.1: nen repo scenario --repo "$canon" --target zheref/hatsu → "'zheref/hatsu' is recorded in …
   nen/repos.json (under 'maintained_tools'), but only a consumers[] entry carries a 'scenario'
   field", exit 1.
2. The target's own checkout, when its nen/repos.json records itself under consumers[] with a
   scenario — verified live at nen 0.15.1 against a registry carrying exactly one such entry:
   nen repo scenario --repo <that checkout> --target <its slug> → the scenario, exit 0, and
   nen canon resolve against the same --repo → the full set (§ 2).

A repository recorded only under maintained_tools — a machinery repository: zheref/bankai-handbooks
itself, zheref/hatsu, zheref/nen — has no consumers[] scenario in any registry by construction,
and both answers above refuse it with the same sentence. That is the expected answer, not a defect to
repair by writing a registry entry: its scenario is bankai-machinery, read from handbooks/INDEX.md
(§ 2) — the one direct read this skill keeps, spelled out in `bankai-quality` § 1.

A target neither registry records is a missing-configuration finding, asked for and set up
inline (missing-argument, missing-configuration; `WORKFLOW.md` § 4
Ask, set up, continue): relay the verb's sentence, offer the scenario in the picker, and land it on
that repository's own declaration PR at its own gate — never by writing to
zheref/bankai-handbooks' registry (a canon repository at G4, and one whose redaction policy names
no private repository), and never by guessing. Which registry is canonical for a private consumer
is an OPEN question for the maintainer (raised in the PR that made this port); until it is ruled,
the order above is what runs, and an OPEN item stays OPEN.

Finding against the retired skill's prose, not the binary. The old bankai-handbooks skill said
the scenario comes "from .github/workflows/bankai.yml". Verified live: nen repo scenario never
reads that file — it reads the value recorded for the target in a registry (nen/repos.json,
kept factual against the live workflow file by hand, one layer removed). The distinction matters
when the two disagree: resolve from the registry, the way the verb does, never by opening
bankai.yml yourself.

• --repo is a path to a checkout — never an owner/name slug — and it is required: omitted,
  the verb refuses at exit 2 by name (nen v0.2.0, #73, closes zheref/nen#28; verified live at
  v0.3.0), never a silent cwd default.
• --target is an owner/name slug — never a product code. nen repo scenario refuses a code
  outright, verified live at v0.3.0: --target takes an owner/name repository slug and 'RA' is not one.
  If you only have a code, resolve it first with nen repo resolve <CODE> --repo <registry checkout> —
  since nen v0.2.0 --repo is valid on the token form too ("the same flag its siblings take, valid
  with and without a token", nen repo --help), which closes the finding this port filed against
  v0.1.0 (docs/ab/bankai-handbooks.md § 2.3: the token form read the registry from the process's
  cwd regardless). BH is zheref/bankai-handbooks in Hatsu's registry and in its own (verified live:
  nen repo resolve BH --repo "$canon" → zheref/bankai-handbooks (BH) via code).
  --from is the no-token form's flag only and is refused beside a token.
• No GH_TOKEN needed anywhere in this skill. Both verbs here are pure local-file reads against
  the checkouts on disk — verified live with no token exported at all.
• Exit 1 → a finding about the registry, with a distinct reason for each state (nen v0.2.0,
  #73): the checkout carries no registry (<checkout>/nen/repos.json: no such file); the target
  is not recorded anywhere in it ("not as a consumer, a product-code value, a maintained tool, or a
  pending onboarding"); or it is recorded but not as a consumer — under maintained_tools,
  pending_onboarding, or only as a product_codes value — and "only a consumers[] entry carries a
  'scenario' field". Relay the sentence; it is the diagnosis, and the third one is what the canon
  registry answers for every target today (above).
• Exit 2 → an invocation mistake: an omitted or malformed --target, an omitted --repo,
  or a --repo path that does not exist on disk — since nen 0.7 (zheref/nen#93) across the
  sixteen verbs of the repo, labels, pr and issue families, where v0.6.0 answered 1
  (docs/ab/bankai-handbooks.md § Retired at nen 0.7). Fix the command — asking for whichever value
  the session cannot supply — and never read exit 2 as "no scenario."

The exit code is load-bearing, and reading it is the point. "You typed it wrong" and "the
thing you asked for did not work" want different reactions, and a retry wrapper honouring that
distinction retries a 1 and gives up on a 2. So: exit 1 is a finding about the registry
— one of the three causes above, each with its own sentence — and exit 2 is a finding about
the command. The refusal text is still what you relay, because it is the diagnosis; the code is
what you branch on. Recorded in full, with both transcripts, in docs/ab/bankai-handbooks.md
§§ 2.2–2.3, finding 5 of § 4, and § Retired at nen 0.7.

2. Resolve the handbook set

nen canon resolve --repo <registry checkout> --target <owner/name> \
  --always-load <paths from "$canon"/handbooks/INDEX.md's "Always load" table, comma-separated> \
  --stack-dir handbooks/stacks \
  --json

--always-load is caller data — read fresh from handbooks/INDEX.md's own "Always load" table, in
$canon (§ 0) at the pin, every time. It is not looked up by the verb; you
supply it. It is also not stable: the table grew twice while the retired skill's own copy of it sat
frozen (three files → four → five, § above). Verified live at v0.6.0, it resolves to:

handbooks/uzf-core.md, handbooks/security-baseline.md, handbooks/ux-baseline.md,
handbooks/release-policy.md, handbooks/quality-baseline.md

— UZF-{n}, SEC-{n}, UX-{n}, REL-{n}, QA-{n} respectively. CONVENTIONS.md sits in the same
manifest's catalog and is not part of the always-load set — INDEX.md says so: it is the output
shape every agent follows, cited by CON-3, CON-17 and CON-32, not a rule family. Read the
table yourself before every resolve rather than pasting this list from memory next session — that
is exactly the drift this section exists to name.

--stack-dir handbooks/stacks is the fixed directory layout, not caller data — it does not change per
scenario and needs no re-reading.

--always-load, --target and --repo all refuse outright (exit 2, "is required") when
omitted — verified live at nen 0.15.1: --repo <path> is required. It is the checkout whose nen/repos.json maps --target to the scenario this handbook set derives from. (At the port, v0.3.0
let --repo fall back to the cwd silently; that residue is retired.) Never omit it.

The verb computes, in one call, both halves the old skill's title promised: the always-load set
(echoed back for confirmation) and exactly one stack handbook, derived directly from the scenario
nen repo scenario returned — never looked up in a table of its own. The paths it returns are
relative to $canon (§ 0), and that is where you open them — at the pinned tag, never at a
branch. Today's scenario → stack → rule-prefix mapping, read from handbooks/INDEX.md's
own stack table at resolve time, never memorized:

Scenario	Stack handbook	Rule-ID prefix	Platform · UI
swiftui-tca-uzf-v2	handbooks/stacks/swiftui-tca-uzf-v2/architecture.md	SW-{n}	iOS/macOS · SwiftUI + TCA
compose-uzf-v2	handbooks/stacks/compose-uzf-v2/architecture.md	KT-{n}	Android · Compose + Hilt
react-uzf-v1	handbooks/stacks/react-uzf-v1/architecture.md	RC-{n}	Web + Mobile · Next.js/Expo + RTK
bankai-machinery	handbooks/stacks/bankai-machinery/architecture.md	BC-{n}	Bankai machinery (CI plane, CLI, local plugin) · self-review, no product code

bankai-machinery is the renamed machinery scenario. Until handbook set v0.6 its id was the
frozen reference implementation's own repository name (the <reference-repo> row in
docs/ab/bankai-handbooks.md); INDEX.md, stack-matrix.md and the stack's own README.md §
Name and prefix record the rename. The BC- rule-id prefix is unchanged, so every existing
BC-{n} citation across the estate stays valid — never rewrite one.

The public registry names no consumer per row. The retired skill's table carried a "recorded
consumer today" column read off the frozen registry; zheref/bankai-handbooks' registry records
none (§ 1), so which repository runs under which scenario is read from the registry that records it,
never from this table. react-uzf-v1 and bankai-machinery were not in the retired skill's table
at all — resolve from handbooks/INDEX.md, never from this table once it, too, is a session old.

Never load another stack's folder. The verb enforces this structurally — it returns exactly one
stackHandbook path, never a list — so there is nothing to improvise here even under pressure to check
"just one more."

3. Report

Quote the resolved set; do not summarize it:

<owner/name>  (scenario: <scenario>)
  canon: zheref/bankai-handbooks @ <tag $canon sits on>  ($canon)
  always load: <alwaysLoad, joined>
  stack handbook: <stackHandbook>

Then cite findings by rule ID, drawn only from the files just resolved: UZF-{n}, SEC-{n},
UX-{n}, REL-{n}, QA-{n} from the always-load set; SW-{n} / KT-{n} / RC-{n} / BC-{n} from
whichever ONE stack file resolved for this repo. Never improvise a policy that is not written in one of
these files, and never cite a rule ID belonging to a stack folder other than the one that just
resolved.

4. When a rule is missing or ambiguous

The retired skill routed this to CI Yamamoto (a handbook/schema gap) or Naruto (a governance gap) per
CON-37, both landing a canon-lane PR in <reference-repo> merged at G4. <reference-repo> is
frozen — no PR lands there any more. The landing repository is now zheref/bankai-handbooks: a
bankai:handbook-question, and a canon-lane PR the human merges at G4 (CON-7, CON-37;
handbooks/INDEX.md's own closing note names the procedure). This skill still authors none of it.
Surface the gap as a finding — the file, the scenario, and what is missing or contradictory — then
stop at G5 for the maintainer to decide; canon is written only on their word (Kurapika's
Conjurer mode, or $great-hiker), never as a side effect of a resolve. Never draft a fix that
reads as though the question were already settled: an OPEN gap stays OPEN
(claude/agents/kurapika.md § Conjurer, "An OPEN item stays OPEN").

5. What this skill must never do

• Hardcode the always-load set or the scenario/stack table across sessions. Both drifted twice
  already, by the same repeated maintenance failure of an edit not reconciling a table it grew in the
  same diff (§§ 1–2 above); re-read handbooks/INDEX.md at the pinned checkout every time, never from
  this file's own prose.
• Read nen repo scenario's exit code alone as the diagnosis. Exit 1 covers three distinct
  registry states, each with its own sentence; read the refusal text to tell them apart (§ 1).
• Load more than one stack folder, or guess a scenario when nen repo scenario refuses one.
• Improvise a policy that is not written in one of the resolved files, or cite a rule ID from a
  file that did not resolve for this repo.
• Treat "not a consumer" as "not a Bankai repo." Since nen v0.2.0 the refusal itself says
  whether the target is recorded under pending_onboarding / maintained_tools / a product_codes
  value — report which one it actually is, in the verb's own words.
• Read the handbooks from <reference-repo>'s handbooks/. That copy is frozen at v0.11.3,
  pre-migration; canon is zheref/bankai-handbooks at the pin, and only there.
• Write to <reference-repo>, or open a canon-lane PR to zheref/bankai-handbooks on this
  skill's own authority, to fix a handbook gap. File the finding and stop at G5 instead (§ 4).
• Fall back to a product repo's .claude/rules/ mirror when a live bankai-handbooks checkout is
  available. The mirror is a build artifact of the same pin (CON-13), not this skill's source —
  resolve from the checkout.
• Pass a product code to --target. Resolve it to owner/name first, against the registry
  (§ 1).
• Rewrite a BC-{n} citation because the machinery stack folder was renamed. The prefix is
  stable by design; the folder name is not what a citation carries.