Skip to content

GentBajko/capstone / skills/core

Internal to the capstone suite - carries the shared rules (references/) and scripts every capstone subcommand reads; it exists so npx-skills installs ship them alongside the command skills. Not meant to be invoked directly; when invoked anyway, run references/../scripts/help.sh and output its stdout verbatim.

FileKindSize
SKILL.mdskill md902 B
VERSIONother6 B
references/arch-craft.mdmarkdown6.6 KB
references/code-craft.mdmarkdown9.6 KB
references/core-authoring.mdmarkdown8.7 KB
references/core.mdmarkdown55.5 KB
references/dispatcher.mdmarkdown1.9 KB
references/interview.mdmarkdown17.5 KB
references/logic-craft.mdmarkdown9.5 KB
references/protocols/architecture.mdmarkdown12.2 KB
references/protocols/build.mdmarkdown10.5 KB
references/protocols/doctor.mdmarkdown9.3 KB
references/protocols/edges.mdmarkdown12.6 KB
references/protocols/feature.mdmarkdown5.3 KB
references/protocols/groom.mdmarkdown11.2 KB
references/protocols/implement.mdmarkdown15.2 KB
references/protocols/logic.mdmarkdown10.7 KB
references/protocols/map.mdmarkdown38.5 KB
references/protocols/mockup.mdmarkdown11.0 KB
references/protocols/plan.mdmarkdown9.3 KB
references/protocols/retro.mdmarkdown9.3 KB
references/protocols/review.mdmarkdown10.6 KB
references/protocols/stack.mdmarkdown8.8 KB
references/protocols/standards.mdmarkdown8.5 KB
references/protocols/start.mdmarkdown14.6 KB
references/protocols/uiux.mdmarkdown24.8 KB
references/schema.txtmarkdown11.9 KB
references/standards-inventory.mdmarkdown36.9 KB
references/style.mdmarkdown1.8 KB
references/topics.mdmarkdown21.2 KB
references/uiux-craft.mdmarkdown20.7 KB
references/uiux-inventory.mdmarkdown19.3 KB
scripts/help-hook.shexecutablescript1.5 KB
scripts/help.shexecutablescript6.4 KB
scripts/init-config.shexecutablescript16.3 KB
scripts/lint-sync.shscript133.5 KB
scripts/map-check.shexecutablescript52.8 KB

references/protocols/map.md

View on GitHub
# map - build the reference, and keep it true

**Reads:** config → the existing `<index_file>` and every stamped
file's frontmatter (mode select, then stamps and globs; a full body
only when regenerating it) → `../topics.md` (required sections, and
template drift). A full build additionally reads Phase 1's recon set
(manifests, type/lint configs, README/CLAUDE/AGENTS, tree, entry
points); the deep-dive reads source per topic, and the extractions
read the composed chapters (per logic.md and uiux.md). For `check`
the script half (`scripts/map-check.sh`, the `core` skill) reads the
stamped files' frontmatter, `changelog.d/`, `09-interfaces.md`'s
`edges:` block and `02-models.md`'s entity headings; the model half
also reads the ledger -
`changelog.md`, its rotation files, and `changelog.d/` fragments
(absorption drift) - and `05-dependencies.md` plus the manifests and
lockfile (re-vetting). When config `cross_repo` is `auto` and the
`quarry` CLI is on PATH, Phase 2's interfaces pass also reads the
existing `09-interfaces.md` and the output of
`quarry docs index --json` and `quarry docs list --json`. Nothing
else unprompted.

The descriptive reference for the current project: a lean
`00-index.md` index and chapterized topic files in `<docs_dir>/`,
the `logic/` business-logic map, and the `uiux/` surface map. The
audience is future AI sessions; they read these docs instead of
re-exploring the repository.

**One verb, because the branch is readable off disk, not off intent.**
No index → build it. An index → rewrite only what drifted. The user
should never have to know which of those they needed. The two things
that are *not* inferable stay explicit words:
`rebuild` (rewrite a current reference anyway) and `check` (report,
write nothing).

**Announce at start**, naming the mode you selected: "I'm using the
capstone map skill to build the architecture reference" for a full
build, "...to refresh the reference where the code moved" for a
refresh.

## Phase 0 - mode select

0. Per core.md: read the config first. `docs_dir` and `index_file`
   must be relative paths inside the repository. With config
   `workspaces` set, branches 2-5 are taken per workspace, each
   against its own docs area and index, and a workspace name as the
   argument targets that workspace alone (Workspaces, below).
1. `check` → the read-only trust report at the end of this file.
   Writes nothing, not even a changelog entry.
2. A single topic argument → run Phase 1 recon, then Phases 2-4 for
   that topic only, regardless of staleness; it always regenerates
   that chapter, and Phase 3's extractions (steps 4-5) do not run.
   Confirm before overwriting a chapter that is current. With no
   `<index_file>` on disk a topic argument is a full build (branch
   4): one chapter is not a reference, and the Refresh would never
   write the rest.
3. `rebuild` → full build (Phases 1-4), overwriting what exists.
   Confirm once first: it rewrites every chapter, and a plain `map`
   would have refreshed only what drifted. In this mode Phase 3's
   extractions regenerate existing **extraction-mode** `logic/` and
   `uiux/` files too, rather than only filling gaps; interview-derived
   files in those folders are still never touched, whatever the mode
   (their provenance decides, not the verb).
4. **No `<index_file>` on disk** → full build (Phases 1-4). This
   branch is unconditional: core.md's Missing reference rule leans on
   it when another protocol delegates here, so it must never turn
   into a refusal or a pointer at another command.
5. **An `<index_file>` exists** → **Refresh** (below): rewrite only
   what drifted. The index itself carries no stamps (Phase 3 step 7),
   so its presence is the whole test - the stamps the Refresh reads
   live in the topic files. An index with no stamped topic file beside
   it is a torn build, not a reference: say so and full-build. The
   root index-of-indexes of a project with `workspaces` set is exempt:
   it has no topic files beside it by design (Workspaces, below).
   Never silently rewrite a current reference; a user who wants
   everything redone says `rebuild`.

## Phase 1 - inline recon

Do this in the main session with cheap reads only:

1. Read dependency manifests that exist: `pyproject.toml`,
   `package.json`, `Cargo.toml`, `go.mod`.
2. Read type and lint configs: `tsconfig.json`, pyright config
   (`pyrightconfig.json` or `[tool.pyright]`), `mypy.ini`, eslint
   config.
3. Read `README*`, `CLAUDE.md`, `AGENTS.md` if present.
4. List the directory tree two to three levels deep, ignoring
   `node_modules`, `dist`, `build`, `.git`, and caches.
5. Identify entry points: main modules, CLI entries, server startup,
   route/command registries.
6. Build the **module map**: every top-level module or package, its
   one-line purpose, and its key entry-point files. All later phases
   and every subagent treat this map as authoritative. (A Refresh does
   not re-derive it: it reads the module map the index already
   carries, and re-verifies it at the end.)
7. Decide applicable topics using each topic's **Applicable** test in
   `../topics.md`. Record inapplicable topics with a one-line reason;
   they appear in the index as absent.
8. Measure size: count tracked source files (`git ls-files` filtered
   to source extensions; `find` outside git). This is also the count
   core.md's Missing reference rule gates on before an unrequested
   full build.
9. If that count is ~0 and no entry points or manifests were found,
   stop here. There is nothing to describe yet; write nothing and
   point the user at `start` (or `start architecture` directly), the
   greenfield path.

## Phase 2 - deep-dive

An inherited [Execution choice](../core.md#execution-choice) governs
every dispatch below, including Phase 3's scenario and surface
extraction. In inline mode, analyze all of them in this conversation
regardless of the threshold. Standalone `map` keeps its usual
threshold behavior; a pipeline's inline choice overrides that behavior.

- **At or below the subagent threshold (default 150 source files):**
  analyze each applicable topic inline yourself, against that topic's
  required sections and checklist in `../topics.md`.
- **Above the threshold:** dispatch one read-only subagent per
  applicable topic, in parallel (if your harness has no subagent
  capability, analyze the topics sequentially inline instead). Each
  subagent prompt must contain:
  1. The topic's required sections and checklist, copied from
     `../topics.md`.
  2. The full module map from Phase 1, marked authoritative:
     "Do not re-derive the module map."
  3. The rules: read-only, modify nothing; facts only; a `file:line`
     pointer for every claim; no recommendations; return raw markdown
     matching the required sections, no preamble.
  4. For the operations topic, the resolved config `redact` list
     (project file over global), verbatim, so the deep-dive knows
     which variables get `<redacted>` in the Default column.

**Interfaces pass.** Whichever branch runs, the `interfaces` topic
(when applicable) works in a fixed order, because the chapter's
`edges:` frontmatter block is the canonical record and only part of
each row is this run's to write (`../topics.md`'s interfaces
section).

1. **Read the existing chapter first**, if there is one, and keep its
   `edges:` block: every row's `to` and `from` is an answer - a
   person's, a confirmation's, or an `edges` run's - and **no run
   edits one**. `map` derives none: the one thing it writes there is
   the answer step 5's ask is given (core.md hard rule 3).
2. **Derive this run's rows from the code**: `kind`, `name`, `site`
   as a repo-relative path with no line number, and `schema` naming
   the `### <Entity>` section `02-models.md` holds for that payload,
   or no `schema` where the payload is ad-hoc and the row's
   `### <Name>` section carries its own field table instead.
3. **Merge by `(direction, kind, name)`**: a row the block already
   carries keeps its `to`/`from` untouched and takes this run's
   `site` and `schema`; a row the code has and the block lacks is
   added with neither; a row the block has and the code no longer
   does is dropped and named in the run report
   (`dropped: sqs old-topic (was to record-store)`).
4. **Fill the chapter's `known_as`** from the deploy sources the
   operations topic reads - compose files, ingress and gateway
   manifests, Kubernetes manifests, service-discovery config - per
   `../topics.md`.
5. **Ask about what the registry could not join.** When config
   `cross_repo` is `auto` (the default) and the `quarry` CLI is on
   PATH, run `quarry docs index --json` once in the main session and
   read its `ambiguous` rows for this repo (the workspace name when
   `workspaces` is configured, per core.md); each is a contract
   several sibling repos sit on, which the join cannot settle alone.
   Put them to the user as core.md's Edge confirmation describes -
   one digest, one line per row - and write each answer into that
   row's `to` or `from`. Run `quarry docs list --json` in the same
   pass to confirm this repo is registered; when it is not, say so in
   one report line, because an unregistered repo is one no join will
   ever reach. No `09-interfaces.md` is required for either call,
   unlike `groom` and `plan`. Any condition unmet (config `off`, no
   CLI, a command that fails, an empty `ambiguous` list) → skip
   silently and leave those rows without a `to` or a `from`, which is
   what quarry expects to resolve later.
6. **Render the tables and the payload sections from the merged
   block**, and the legacy top-level mirror too when config
   `interfaces_frontmatter` is on.

## Phase 3 - compose

1. Write each topic file **chapterized**: a numbered prefix in
   reading order so the folder itself reads like a table of contents:
   `01-architecture.md`, `02-models.md`, `03-conventions.md`,
   `04-data-flow.md`, `05-dependencies.md`, `06-testing.md`,
   `07-operations.md`, `08-glossary.md`, `09-interfaces.md` (skip
   absent topics without renumbering; `09-interfaces.md` also honors
   the config `interfaces` key per `../topics.md`). If unnumbered topic files exist from an earlier
   version, rename them to the chapter names during the run and
   update every cross-reference. Use the exact headings from
   `../topics.md`, with this frontmatter:

```yaml
---
generated_at_commit: <12-char sha of HEAD>   # omit outside git
generated_date: <YYYY-MM-DD>
capstone_version: <this installation's version or skill hash>  # omit if unreadable
content_hash: <12 chars>   # omit outside git; see core.md's stamps rule
paths_covered:
  - "<glob>"
---
```

   `content_hash` is computed per core.md's stamps rule:
   `git ls-files -s --full-name -- <this file's globs> | git hash-object --stdin`,
   first 12 chars (the index entries under the globs: mode, blob,
   stage, root-relative path; `ls-tree` does not expand `*`). It is
   the stamp that survives a squash or rebase merge making
   `generated_at_commit` unreachable.

   `09-interfaces.md` carries two more frontmatter keys, `known_as`
   and the canonical `edges:` block, per `../topics.md`'s interfaces
   section; the Produces and Consumes tables are rendered from that
   block, and each row gets a `### <Name>` section holding
   either `Model: <Entity>` (the row's `schema`, resolved against
   `02-models.md`) or its own `Field`, `Type`, `Required` table
   (topics.md's Payload sections). The
   producer's `quarry check` compares exactly those fields, so a row
   with no section, or a section naming a model `02-models.md` does
   not hold, is a chapter that fails the schema pass.

2. Choose `paths_covered` globs deliberately; they drive the Refresh's
   staleness. Cover every directory the topic's content was derived
   from, but prefer the tightest globs that still do: package-level
   over repo-level, so unrelated commits don't mark the topic stale.
   Some topics (architecture, conventions) are legitimately
   repo-wide. Anchor every glob at the repository root with the
   `:(top)` magic pathspec (e.g. `:(top)src/api/**`) so staleness
   checks work from any cwd. A glob list that could match the docs
   area (a repo-wide `:(top)**`, or a glob over a parent of
   `<docs_dir>`) carries one more entry excluding it,
   `":(top,exclude)<docs_dir>/**"`: without it this run's own docs
   writes, and every later docs commit, mark the chapter stale
   forever. git honours the exclusion in `git diff`, `git status` and
   `git ls-files` alike, so the staleness test and the `content_hash`
   recipe take the list as written. `09-interfaces.md`'s globs also
   cover the deploy sources its `known_as` was read from, so a renamed
   service marks the chapter stale.
3. Ensure the global config and the docs area's `.gitignore` exist by
   running the platform-appropriate initializer from the `core`
   skill's `scripts/` directory (idempotent, never overwrites
   either):
   `init-config.sh <docs_dir>` via bash (Git Bash on Windows). If
   bash is unavailable, write the global JSON template from core.md
   and the ignore list from core-authoring.md yourself.
4. **Logic extraction** (full build and refresh only; a topic
   argument skips steps 4-5 per Phase 0 branch 2, and the config
   `extract` key gates each pass: run this step only when `"logic"`
   is listed, step 5 only when `"uiux"` is - `[]` skips both, and a
   skipped pass is recorded in the index as disabled by config, not
   absent): build
   `<docs_dir>/logic/` per logic.md's
   extraction mode, invoked as its "Invoked by `map`" rules say: the
   entry-point inventory from the module map and the just-written
   chapters, one descriptive scenario file per scenario covering
   logic.md's full Phase B section list, every rule cited
   `file:line`, stamped with `paths_covered`. Above the subagent
   threshold, dispatch extraction per scenario like Phase 2's
   per-topic dispatch, same rules. A repo with no observable entry
   points records `logic` absent in the topic index with that reason.
   Existing `logic/` files are left alone and extraction fills only
   the scenarios the map is missing - except under `rebuild`, which
   regenerates the extraction-mode ones. Interview-derived scenario
   files are never regenerated in any mode.
5. **Design extraction**: applicable when the repo has a frontend
   (client entry points, routes or views, or token/theme files: the
   same evidence `01-architecture.md`'s Frontend section reports).
   Build `<docs_dir>/uiux/` per uiux.md's extraction mode,
   invoked as its "Invoked by `map`" rules say: the surface inventory
   from the module map and the route table, one
   `screens/NN-<route>.md` per surface covering what the code actually
   renders, `02-system.md` from the observed tokens and component
   language with `file:line` cites, and `01-direction.md` only where a
   direction is genuinely observable (uiux-craft §9). Every file
   stamped with `paths_covered` over the frontend globs it was read
   from. Above the subagent threshold, dispatch per surface like
   Phase 2's per-topic dispatch, same rules. A repo with no frontend
   records `uiux` absent in the Companion docs table with that
   reason. Existing `uiux/` files are left alone and extraction fills
   only the surfaces the map is missing - except under `rebuild`,
   which regenerates the extraction-mode ones. A committed design the
   `uiux` interview produced is never overwritten, in any mode.
6. Write the changelog entry per core.md's Changelog ledger (a
   `changelog.d/` fragment), key `map/<topic|all>@<the run's stamp>`,
   suffixed `.2`, `.3` when the ledger already holds that key and its
   entry does not record what this run wrote (core.md's ledger rule;
   the fragment is named `<YYYY-MM-DD>-map-<target>-<rev>.md` after
   the suffixed key); one bullet per chapter and logic scenario
   written **this run** (every one, never only those you judge
   materially changed; that judgment is the escape hatch), the topics
   recorded absent with their reasons, and whether the index was created or refreshed.
   Nothing written (Phase 1 step 9's empty-repo stop) → no entry.
   This run writes the docs area, so it also **folds** any waiting
   `changelog.d/` fragments into `changelog.md` per that ledger rule:
   on the default branch only, its own entry included.
7. Write `<index_file>` **last**, so the index reflects what was
   actually written. It is chapter zero of the docs area
   (`docs/capstone/00-index.md` by default), and it carries no stamps:
   freshness lives in each file's own frontmatter, which is what the
   Refresh reads (core-authoring.md's Index maintenance). Four parts,
   nothing else:
   - Project one-liner, tech stack, and paradigm summary in a few
     lines.
   - Module map with `file:line` entry-point pointers.
   - Topic table `| Topic | File |`, plus absent topics with their
     reasons in place of a file. `logic/` gets one row per scenario
     file in this same table, `Topic` reading `logic` for every row
     (the monorepo split mechanic below, applied to a subfolder
     instead of the root); a repo with no scenarios yet records
     `logic` absent here with its reason instead.
   - If companion docs exist (`review.md`, `changelog.md` and its
     `changelog-<YYYY>.md` rotation files, `standards.md`,
     `implementation.md`, `mockup/`, `uiux/`, `features/`,
     `questionnaires/`), a `| File | What it is |` table below
     the topic table; the factual reference and the
     opinionated/instructional outputs stay visibly distinct.
     Interview Q&A files are never indexed, and the index never lists
     itself.
8. Monorepos: split a topic per subsystem while keeping the parent
   chapter's number (`01-architecture-frontend.md`,
   `01-architecture-backend.md`) when one file would be unwieldy; the
   index shows the split.

## Phase 4 - verify

1. Re-read the index: every topic link resolves to an existing file,
   and every file written this run has a row.
2. Spot-check three `file:line` pointers across topic and logic files
   against the actual source.
3. Report to the user: files written, topics skipped or absent and
   why.
4. The local-only outputs (`features/`, interviews, `review.md`) are
   already covered by
   `<docs_dir>/.gitignore`; this question is only about the factual
   reference (`changelog.md` and the project config `capstone.json`
   included, both always committed per core.md). If those generated files are
   untracked and not covered by `.gitignore`: honor the `docs_in_git`
   config key when set (`commit` or `ignore`); when it is `ask` or
   unset, ask the user whether to commit them or ignore them; never
   decide unilaterally. Ignoring adds the reference's own paths to
   `.gitignore` (`<index_file>`, the topic chapters, and
   `<docs_dir>`'s `logic/`, `mockup/`, `uiux/` and `standards.md`),
   never `<docs_dir>/` as a whole: that would also ignore the ledger,
   `capstone.json` and `questionnaires/`, which are always committed.
   On later runs, respect whichever choice is in place.

## Refresh - rewrite only what drifted

Selected by Phase 0 branch 5. This is the selector; Phases 2-3 remain
the writer, applied per file rather than to everything. A refresh also
fills gaps in `logic/` and `uiux/`, not only staleness: the maps are
part of the reference, and a missing scenario is as wrong as a stale
one.

First scan every indexed final Markdown output, including stamp-only
prescriptive files, for interview filenames or interview-question
provenance. Any match makes that output stale regardless of source
drift. Rewrite confirmed decisions and rationale directly into the
final file and remove that provenance. A completed interview body may
be opened only when the output omits information needed for this
repair; if that working record is unavailable, report the missing
content and never invent it.

Then, for each stamped file with `paths_covered`:

1. Read `generated_at_commit`, `capstone_version`, `content_hash`,
   and `paths_covered` from its frontmatter.
2. If the frontmatter has `mode: prescriptive` and tracked source now
   exists under its globs (`git ls-files -- <globs>` lists a file),
   the file is **stale by definition**: code has landed where the plan
   put it. Re-run its Phase 2
   deep-dive, rewrite it descriptively, drop
   `mode: prescriptive` and the banner, and record
   designed-vs-implemented divergences from the existing chapter as
   facts ("designed as X; implemented as Y (`file:line`)"), preserving
   the design rationale inline. With nothing tracked under its globs
   the file is current, the same test `check` runs; when the repo
   does have tracked source elsewhere, the run report names the file:
   planned paths the code did not follow. When regenerating
   `05-dependencies.md` by ANY path (refresh, rebuild, or a topic
   argument), carry forward every final-chapter pick not yet present in
   the manifests as a fact ("picked but not yet installed"); the
   user's researched stack decisions must never vanish because the
   code hasn't caught up.
3. Otherwise check staleness against the **working tree**, not just
   commits: from the repo root, `git diff --name-only <stamp> -- <globs>`
   (commit vs working tree) plus `git status --porcelain -- <globs>`
   for untracked files. **Stamp unreachable** (squash or rebase merge
   erased the branch commit): fall back to `content_hash` - recompute
   it per core.md's stamps rule
   (`git ls-files -s --full-name -- <globs> | git hash-object --stdin`,
   first 12 chars) and compare. Equal, and the working tree is clean
   over the globs → current; different → stale, regenerate this file
   only. A `content_hash` equal to the empty-input hash
   `e69de29bb2d1` was written by a 6.1 or earlier recipe that never
   expanded the globs; treat it as absent. Only a file with neither a
   reachable stamp nor a `content_hash` (written by an older
   capstone) is stale-by-unknowable and regenerates. `check`'s script
   half (`scripts/map-check.sh`) runs this same test, and step 2's,
   and prints the verdict per file; its part 1 rows are their output.
4. **No changes** → skip; leave the file and its stamp untouched.
   **Changes** → regenerate it through Phases 2-3; a stale
   extraction-mode `logic/` or `uiux/` file regenerates per its own
   protocol's extraction mode instead. Template drift overrides the
   skip: a chapter missing a required section that `../topics.md` now
   defines (the template changed after the chapter was stamped) is
   stale regardless of `git diff`, and so is a glob list that could
   match the docs area without a `":(top,exclude)<docs_dir>/**"` entry
   (Phase 3 step 2); regenerate either against the current template.
   So does a **version gap**: a `capstone_version` older
   than the running plugin's marks a file written by an earlier
   template generation. Drift catches a section that went missing; it
   cannot catch one whose meaning moved under it, or a rename, which
   is what the version stamp is for. Re-read such a file against the
   current `../topics.md` and regenerate when they disagree in shape
   or meaning (not merely in wording). When they agree, write the
   running version into the file's `capstone_version` and change
   nothing else: the gap is closed, and `check` stops reporting a
   page that has nothing wrong with it. A file carrying no
   `capstone_version` predates the stamp: same treatment.
5. Re-run the **Applicable** test from `../topics.md` for every topic
   the index lists as absent; write any newly applicable topic at
   its fixed chapter number and update its index row.
6. **Logic coverage** (only when `"logic"` is in the config `extract`
   list; steps 6-7 follow the same gating as Phase 3 steps 4-5).
   Build the entry-point inventory per logic.md's
   extraction mode: every externally triggerable behavior (routes, UI
   actions, jobs and crons, queue consumers, CLI commands, webhooks)
   from the chapters' dispatch tables and the module map. Every entry
   point must be claimed by a scenario file in `logic/` (one scenario
   may span several entry points); `logic/` absent counts as every
   scenario missing. Run logic.md's extraction mode for the missing
   ones: full scenario files per its Phase B section list, every rule
   cited `file:line`, stamped with `paths_covered` so later refreshes
   keep them current. Interview-derived scenario files are not
   touched here; they absorb shipped features through `implement`.
7. **Design coverage.** Applicable when the repo has a frontend and
   `"uiux"` is in the config `extract` list.
   Build the surface inventory per uiux.md's extraction mode: every
   route or view a user reaches, from the chapters' route tables and
   the module map. Every surface must be claimed by a chapter in
   `uiux/screens/` (one chapter may cover a surface family);
   `uiux/` absent counts as every surface missing. Run uiux.md's
   extraction mode for the missing ones, stamped with `paths_covered`
   so later refreshes keep them current. **Interview-derived `uiux/`
   files are never touched here**: a committed direction is the user's
   decision, and extraction must not quietly overwrite it with what
   the code happens to do. Where extraction and a committed chapter
   disagree, that is drift for `review` to judge, not for `map` to
   resolve.
8. If any file was rewritten or created in this run, write the
   changelog entry per core.md's ledger (a `changelog.d/` fragment),
   key `map/<scope>@<the run's stamp>` (`<scope>` = the topic name
   for a single file, `all` otherwise), suffixed `.2`, `.3` when the
   ledger already holds that key and its entry does not record what
   this run wrote (core.md's ledger rule; the fragment is named
   `<YYYY-MM-DD>-map-<scope>-<rev>.md` after the suffixed key, so a
   second refresh at one commit records itself); record the files
   regenerated or created and each one's trigger (covered paths
   changed, `mode: prescriptive` with code now under its globs,
   template drift,
   version gap, newly applicable topic, logic or design coverage
   gap), the divergences recorded, and the files skipped as current.
   A writing run also folds waiting `changelog.d/` fragments per the
   ledger rule, on the default branch only. A run where every file was current writes nothing
   and folds nothing.
9. Always re-verify the index's module map and rows.
10. Fall back to a full build (Phases 1-4) only when there is no git
   repo. An unreachable stamped commit is no longer that trigger:
   step 3's `content_hash` comparison keeps the refresh per-file
   through squash and rebase merges and shallow clones. When falling
   back, say so before doing it: the user asked to refresh and is
   getting a rewrite.

Config `workspaces` set → the refresh runs for each workspace that
has an index, as the Workspaces section below says.

## check - the read-only trust report

No writes, and no changelog entry: nothing was done, only read - it
reports leftover `changelog.d/` fragments (part 7) rather than
folding them. Eight parts in two halves. Parts 1, 7 and 8 are
mechanical - `git diff` over globs, a directory listing, grep - and
live in a script, so a CI gate runs them with no model and no API
key. Parts 2-6 need judgment and stay here.

**The script half first.** From the repo root, run the `core` skill's
`scripts/map-check.sh <docs_dir>` via bash (Git Bash on Windows). With
config `workspaces` set, pass every workspace's docs area as its own
argument in one call, so the script prints one verdict. Include its
stdout verbatim, unedited, as the report's parts 1, 7 and 8; never
recompute, restate, or re-verdict any of it. What it prints, listed
by the part numbers this protocol uses and not in a sequence of its
own:

- Part 1, staleness: one row per stamped file with
   `paths_covered` - file | stamp | capstone_version | files changed
   since | verdict.
   The verdict is `current`; `stale` (`git diff --name-only <stamp>
   -- <globs>` against the **working tree**, so uncommitted work
   counts, plus `git status --porcelain -- <globs>` for untracked
   files, found changes; a stamp made unreachable by a squash or
   rebase merge falls back to recomputing `content_hash` per
   core.md's stamps rule,
   `git ls-files -s --full-name -- <globs> | git hash-object --stdin`
   first 12 chars, and comparing, with the legacy empty-input hash
   `e69de29bb2d1` read as absent); `stamp unreachable` (no reachable
   stamp and no `content_hash`); `written by an older capstone`
   (`capstone_version` absent or below the running installation's
   identity, read from its manifest, version file or skills lockfile;
   opaque skill hashes compare for equality); or `prescriptive, pending first
   observation` (`mode: prescriptive` while tracked source exists
   under its globs; with no tracked source under them the file is
   `current`, the Refresh's step 2 test). Outside git every verdict
   is `unknowable (not a git repo)` and counts for nothing. A docs
   area without its index is one finding, `no index at <path>`, and
   gets no rows.
- Part 7, unfolded fragments: every file in `changelog.d/` with
   its key and the repair (any writing run folds them; so does
   `doctor`). Informational only: fragments are the designed state on a branch,
   so they never count toward the verdict - a doc-carrying PR must
   not fail a freshness gate for carrying its own ledger entry.
- Part 8, schema: a mechanical pass over every generated file, grep
   only, no judgment. The definition it runs against is
   `../schema.txt`, one record per output type naming the frontmatter
   keys that type owes, its `## ` headings in order, and the columns
   its tables carry; the script reads that file at runtime and holds no
   copy of it, and `lint-sync` checks 15, 20 and 21 keep it equal to
   `../topics.md` and to the protocols that write `logic/`, `mockup/`
   and `uiux/`. Every file the index reaches is checked against its
   record, so a scenario file, a screen chapter and a questionnaire
   are held to their section lists the way a chapter is. A page whose
   part 1 row already counts its version gap is not held to its
   headings and tables until its stage rewrites it; a page whose row
   counts nothing (no globs, or outside git) is, so an older
   interview-derived page with a section missing is still reported.
   A schema that cannot be read
   costs the headings and the tables and nothing else: the run prints
   `schema: <path> unreadable; headings and tables not checked`, holds
   every page to `generated_date`, and reaches the same verdict line
   with the same exit code. Four columns per file: missing frontmatter
   keys
   (`generated_date` everywhere; inside git also `generated_at_commit`
   and `content_hash` for stamped files and `paths_covered` for
   chapters; prescriptive and interview-derived files are held to
   `generated_date` only, since they carry no commit stamps or globs
   by design; on `09-interfaces.md` also `known_as`, reported missing
   when the key is absent and `known_as not a list` when its value is
   a scalar instead of a bracketed or `- ` list, whatever the mode and
   inside git or out, because quarry registers no alias at all for
   that page and says so only on `docs index --force`;
   `capstone_version` absent is part 1's older-capstone
   verdict, not re-reported here); missing required `## ` headings
   per the record's `head` list, which `../topics.md` and the owning
   protocol spell in prose (a section may be satisfied by "None found"
   text, but the heading itself must exist), reported as
   `## <Heading>`; a heading that sits ahead of one the record puts
   before it, `## <Heading> out of order (before ## <Previous>)`, since
   a template read out of order is drift a reader meets before the
   content does; a table under a required heading whose header row
   lacks a column the record names,
   `table <Heading> missing <Column>`, matched by lowercased header
   name rather than position, with a section carrying no table at all
   left alone; on `09-interfaces.md`, the edge findings below; and secret-shaped
   strings, reported by pattern name and never by the matched text,
   in every file, the index itself included. Every item counts toward the
   verdict: a missing heading is template drift, a missing stamp
   breaks the refresh, an unknown site is a dead edge, and a leaked
   credential must not ship; the repair for the first three is
   `map`, which regenerates the file against the current template.
   - Edges, on `09-interfaces.md` only: the pass reads the
     frontmatter `edges:` block, and falls back to the Produces and
     Consumes tables on a page written before the block existed. Four
     findings, none of them a judgment call. A row with no `site`
     (`no site for <kind> <name>`, in the sites column): the chapter
     cannot point at the code. A `site` whose path, once a trailing
     `:<line>` or `:<from>-<to>` is stripped, fails
     `git ls-files --error-unmatch` or matches something other than
     itself, so a directory and a wildcard are both findings
     (`site <cell>`; skipped for a prescriptive chapter, whose sites
     are planned, and outside git; quarry runs the same test at
     import, so a site this pass rejects is the one
     `quarry update --strict` refuses). A row with no `### <Name>`
     payload section (`### <Name>`, in the headings column), and a
     section holding neither a field table nor a `Model:` line
     (`payload ### <Name>`): `quarry check` has nothing to compare
     either way. And a `schema` or `Model:` naming an entity this
     docs area's `02-models.md` has no `### <Entity>` section for
     (`model <Entity>`, in the headings column), which is a payload
     reference pointing at nothing. The last three are checked
     outside git and on a prescriptive chapter too: they are text the
     page owes, not paths the tree has to hold. `to` and `from` are
     never checked here - they are quarry's to resolve and the user's
     to settle, and this pass never reads them.
   - Secret-shaped strings: every file the pass visits is grepped for
     the six shapes below, and so is every non-markdown file the docs
     area carries (inside git, every one it tracks). The skip list the
     rest of the pass applies holds here too - `changelog*.md`,
     `changelog.d/`, `*-interview.md`, `features/`, `review.md`,
     `be-review.md`, `fe-review.md`, `capstone.json` and `.gitignore`
     are never opened by either pass, so a credential parked in one of
     them is not reported. A hit is reported as `secret: <name>`, never
     the matched text, and counts toward the stale verdict. The repair
     is to remove the value from the source the chapter quoted, add its
     variable to the config `redact` list, and run `map`.
     | Shape | Pattern |
     | --- | --- |
     | aws-access-key | `AKIA[0-9A-Z]{16}` |
     | github-token | `gh[pousr]_[A-Za-z0-9]{36,}` |
     | slack-token | `xox[abprs]-[A-Za-z0-9-]{10,}` |
     | stripe-key | `sk_(live\|test)_[A-Za-z0-9]{16,}` |
     | google-api-key | `AIza[0-9A-Za-z_-]{35}` |
     | private-key | `-----BEGIN [A-Z ]*PRIVATE KEY-----` |

The script ends with exactly one of

    MAP CHECK: current
    MAP CHECK: stale (<N> findings)

and exits 1 on stale, 2 on a usage error. That line is the CI gate's
contract (`templates/capstone-map-check.yml` greps it): never omit,
reword, recompute, or repeat it.

**The model half.** Then, reading only what each part names:

2. **Pointer drift**: the sample is fixed, so two runs on one commit
   report the same drift. Take the files part 1 reported `stale`, in
   index order (the order of their rows in `<index_file>`), and
   within each file its `file:line` pointers in order of appearance;
   the sample is the first five. When part 1 reported no stale file,
   the sample is the first five pointers of the first chapter in
   index order. Check each against the source and report hits and
   misses with the drifted lines' new locations when findable.
3. **Absorption drift**: interview-derived `logic/`, `mockup/`, and
   `uiux/` files carry no globs; their staleness signal is shipped
   features they never absorbed. From the ledger (`changelog.md`,
   rotation files, and unfolded fragments), list
   `implement/*` keys newer than each folder's newest stamp whose
   entry's outputs name that folder; report "logic/ missed N absorbed
   features" (repair: `doctor`, which re-runs the absorb step
   feature by feature).
4. **Dependency re-vetting**: compare `05-dependencies.md`'s recorded
   picks against the manifests and lockfile (picked but absent,
   installed but unrecorded, version below the recorded floor) and
   flag any pick whose recorded research date is more than 6 months
   old as "re-vet suggested (`start stack refresh`)".
5. **Logic coverage**: the Refresh step 6 inventory, read-only:
   entry points no `logic/` scenario claims. Report "logic/ missing
   N scenarios", naming the unclaimed entry points (repair: `map`,
   which extracts them). `"logic"` absent from the config `extract`
   list reports the section as disabled by config, never as a gap.
6. **Design coverage**: the Refresh step 7 inventory, read-only:
   surfaces no `uiux/screens/` chapter claims. Report "uiux/
   missing N surfaces", naming them (repair: `map`, which extracts
   them). A repo with no frontend reports the section as not
   applicable rather than as a gap; `"uiux"` absent from the config
   `extract` list reports it as disabled by config.

End with one sentence (whether the reference can be trusted as-is,
needs `map`, or needs `map rebuild`), then your own machine verdict
line, after the script's, exactly one of:

    MAP REVIEW: clean
    MAP REVIEW: <N> findings

`<N>` is the count across parts 2-6: pointer misses, unabsorbed
features, dependency flags, unclaimed entry points, unclaimed
surfaces. `templates/capstone-map-review.yml` parses that line and
never the script's; never omit or reword either.

## Workspaces

When config `workspaces` is set, a plain `map` covers every
workspace, with `<path>/docs/capstone/` as its docs area and Phase 0
taken for each on its own: a workspace whose docs area has an index
is refreshed (Refresh, above), and one with none gets a full build
(Phases 1-4). A workspace name as the argument targets just that
one. Then write, or on a refresh re-verify, the root `<index_file>`
as an index-of-indexes: project one-liner, a workspace table (name ·
path · index link · newest stamp), and cross-cutting notes. It has
no topic files beside it by design, so Phase 0's torn-build test
never applies to it. When
Phase 1 recon detects workspace manifests (`pnpm-workspace.yaml`,
`go.work`, a Cargo, uv, or poetry workspace) and `workspaces` is
unset, offer to record them in the project config (per core.md,
creating it holding just that key if absent); never silently.

## Non-git projects

Use `generated_date` only (no commit stamps). There are no stamps to
diff, so every run is a full build; `check`'s script half prints
`unknowable (not a git repo)` for every stamped file and skips site
verification; the model half falls back to pointer drift alone.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall