feat(pack): knowledge-explorer — the vault is obligatory, the graph enriches it

[arozumenko]

A fifth Octobots pack skill for the question every role hits before acting on code it did not write: what do we already know about this area?

The premise

Two sources, and they are not equal.

.agents/knowledge/    the committed, verified vault     OBLIGATORY   read it, always
octograph             the co-change graph from git      OPTIONAL     use it where installed

The vault is the source of record. octograph is an instrument — it produces evidence the vault cannot hold (which files actually move together, who owns a path, whether a decomposition is clean). Where it is absent or its history is too thin, the answer is still valid, just thinner, and the skill says so rather than pretending.

They belong in one skill because of the loop between them: the graph is how the vault grows. A verified, durable, cross-role finding is promoted into the vault, so nobody pays for the discovery twice.

What the skill adds that docs/octograph.md cannot

The doc says what each command answers. The skill carries the discipline:

• doctor before believing any zero. This repo reports degraded — 31 analysable commits, squash-merged — which makes an empty impact missing evidence, not evidence of absence.
• Reading a zero. (no coupled files) has three indistinguishable causes: an excluded path, an untracked path, or support below minSupport. The skill gives the two commands that discriminate them, and the rule that an excluded path should be re-queried at its unexcluded twin.
• Verify before reporting. The graph proposes; opening the file proves. support/nPMI travel with every claim.
• Report your blind spots. Part 3 of the output contract — excluded paths, degraded history, absent instrument — is not optional. An answer that silently omits what it could not see reads as complete.

Measured against issue #60

Full record: docs/superpowers/spikes/2026-08-13-knowledge-explorer-vs-issue-60.md. Both pass conditions were tested, and the result is not the one the design predicted — it is recorded as it happened.

Issue #60 names four files. The true change set is seven. Of the three it misses:

Miss	grep	graph
packages/board/src/validate.ts:321 — the same rule in TypeScript, which the issue explicitly claims does not exist	found	found, rank 1, npmi=0.857
packages/board/test/validate.test.ts:210 — the test pinning it	found	missed
the pack version-bump cohort — 6 files obliged by editing any pack SKILL.md	not found	found, support=19–20

Grep wins on the textual rule sites; the graph wins on the process cohort. Its unique contribution is not "find the other file that says the same thing" — a good grep does that more cheaply. It is "changing this kind of file obliges this ritual", a coupling that exists only in commit history and shares no token with the change. That is the class of miss that ships a red CI run.

Pass condition 2 passed outright, and exercised a cause the design had not anticipated: impact on add-workflow.js returned zero, and the three-cause rule correctly classified it as a support-floor zero (3 commits, tracked, not excluded) rather than an exclusion.

The spec has been corrected where the run disproved it: .claude/ copies are gitignored install output in this repo, not change targets. The doubling is real only in a repo that vendors the pack — which is where #60 was originally hit.

Also filed

#94 — (no coupled files) meaning three different things is a defect in packages/graph/src/cli.ts, kept out of this change deliberately. On the board as octograph-code-architecture-graph/bugs/bug-impact-reports-an-excluded-path-as-uncoupled.

Wiring

• OCTOBOTS_SKILLS gains "knowledge-explorer"; the four parameterised convention tests apply to it automatically.
• Pack version 49 → 50 as one unit: five SKILL.md frontmatter lines, three hand-edited banners, the regenerated graph/octograph.mjs, and its hash in graph-payload-versions.json.
• Each of the four sibling skills names it at the moment it hits the question — pointers, not gates — pinned by a new test, so a future skill cannot go unreferenced the way this one nearly did.

Verification

pnpm build && pnpm typecheck && pnpm lint && pnpm test — all green. 1,278 tests: graph 565, extension 401, board 269, tokenomics 43.

🤖 Generated with Claude Code

[arozumenko]

Two follow-ups added, both of which the skill itself asked for.

The vault gains the finding only the graph could produce. .agents/knowledge/architecture/pack-version-is-one-unit.md records the version cohort as one obligation: nine markers, a regenerated bundle, a recorded hash, and no partial state accepted by packStatus. The individual pieces were each already documented — in graph-payload-versions.json's _why, in graph-payload.test.ts's regression comment — but nothing stated the obligation as a whole, which is why it gets rediscovered per author. This closes the skill's own loop: the next reader gets it from tier 1 without spending a graph query.

The query ladder gained the rule the spike exposed. Run impact on the doctrine file as well as the code file. Process obligations attach to a kind of file, so they are reachable only from that file and never from the change that triggers them — which is precisely how the cohort stayed invisible to grep. A sample of one, but the mechanism is not accidental.

No version re-bump: v50 is unreleased on this branch, and the payload hash covers octograph.mjs only, not SKILL.md content. Extension suite still 401 passing.