GentBajko/capstone / skills/core
core
VerifiedInternal 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.
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 470k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |