- Home
- Skills
- Code Quality & Review
- Codebase Audit Pack
Codebase Audit Pack
Two read-only audits that settle architecture arguments with file:line evidence instead of taste: which of your repo's own rules nothing enforces, and which of its types and layers actually earn their keep.
$12
Works with the AI Agents you already use
Codebase Audit Pack
Example session with this skill installed
Audit hexarch's verification. What do our gates actually guarantee, where are the holes, and which architecture tests should we add to lock down the core / viewer / cli boundaries?
- Read your context and instructions
- Compiled the codebase audit
- Generated the document
Verification audit: hexarch
- Audited:
a-grasso/hexarch, commitf753c29(main, clean tree), 2026-10-25 - Stack: TypeScript (Bun + Node 22 + Vite/React), npm workspaces
core/viewer/cli, about 1,700 lines of source. Worked withreferences/typescript.md. - Calibrated against: one author (every commit is a-grasso), pre-1.0 (0.1.1), but the output ships as prebuilt binaries via GitHub releases and a Homebrew tap, and a Claude skill tells other people's agents to trust the parser. One contributor plus review is a real control for the code; it is not a control for what a tag push publishes.
1. Verdict
hexarch's verification is exactly one thing: just check, a strict tsc typecheck of the viewer and CLI (15 s including the viewer build), run by hand. There is no test runner, no linter, no architecture rule, and the only CI workflow fires on a v* tag and publishes to GitHub and Homebrew without running that typecheck. Two things are widely believed to be guaranteed and are not. First, that the parser "fails fast" on structural mistakes: it silently discards a misspelled adapters: section, a list where a mapping belongs, and a missing architecture:, and reports a valid spec (core/parser.ts:4-6 promises the opposite, and skills/hexarch/SKILL.md:120 repeats it to every agent that installs the skill). Second, that a green release means type-checked code: the CLI half of the repo is never type-checked on the release path, the compiled binary ships regardless (I appended a type error and bun build --compile produced a working binary), and the CLI exits 0 when some of the specs it was given are invalid. The structure itself is sound and unguarded: core imports only js-yaml, viewer and cli never import each other, and Bun's built-in test runner is already in the toolchain, so every recommendation below costs lines, not dependencies.
2. Enforcement graph
Traced as: exists -> wired into -> reached by the local gate -> reached by CI -> fails or warns.
| Check | Wired into | Local gate (just check / what a dev runs) | CI (release.yml, tag-only) | Fails or warns |
|---|---|---|---|---|
tsc strict, viewer + core (via include: ../core) | viewer typecheck = tsc -b --noEmit; also tsc -b inside build:embed | Yes (just check, root npm run typecheck) | Yes, incidentally: npm run build:embed at release.yml:61 | Fails |
tsc strict, cli | cli typecheck = tsc --noEmit | just check: yes. Root npm run typecheck: fails on a clean checkout (TS2307, cli/embed.ts is generated and gitignored) | No | Fails (when it can run) |
noUnusedLocals, noUnusedParameters, noFallthroughCasesInSwitch | viewer/tsconfig.json only | Viewer only | Viewer only | Fails. cli lacks them (0 errors if enabled) |
vite build | build:embed | Not in just check | Yes | Strips types, proves nothing about them |
bun build --compile | scripts/build-all.sh, just build | Not in just check | Yes | Does not type-check; succeeds with type errors |
Parser validation, 4 rules (core/parser.ts:129-171) | Runtime only, on every parse() | Only if someone runs hex-render on a spec | No | Throws ParseError, no test pins it |
| Unit / integration / snapshot tests | None exist | n/a | n/a | n/a |
| Linter, formatter, import-boundary rules | None exist (no eslint, prettier, biome, dependency-cruiser, knip) | n/a | n/a | n/a |
| Tap-token preflight | release.yml:23-44 | No | Yes, first step | Fails (good) |
Shell scripts (install.sh, build-all.sh, render-formula.sh) | No lint wired | No | No | I ran shellcheck once: 1 info-level note, otherwise clean |
Screenshot helpers viewer/scripts/{shot,hover,export,shotfile}.mjs | Manual, need a running dev server | No | No | Produce PNGs for a human, assert nothing |
The divergences that matter: the only job that publishes artifacts runs half of what the local gate runs, and the two typecheck entry points (just check and npm run typecheck) disagree about whether a fresh clone is green.
3. Findings
Ranked globally by the evidence ladder. 11 findings: 2 x T1, 2 x T2, 2 x T3, 3 x T4, 2 x T5 promoted by evidence.
V1 - the parser accepts structural mistakes it claims to reject [T1 Violated]
Invariant A spec with a structural mistake (wrong-shaped section, missing required
`architecture`, a section name that matches nothing) raises ParseError.
Rule source core/parser.ts:4-6: "strict where it must be (structural mistakes and
dangling references raise ParseError pointing at the spot)".
dsl/SPEC.md:59 "`architecture` (required)"; SPEC.md:147 "Forgiving in,
strict out". skills/hexarch/SKILL.md:120: "a bad spec fails fast with
the offending element named".
Evidence Probed parse() directly (bun, 19 inputs). ACCEPTED, no error:
`ports:` as a list -> 0 ports, no error
`adapters:` as a list -> adapter silently dropped
`adaptors:` (typo) with an adapter implementing a port that does
not exist -> accepted; dangling-reference
check never runs because the
section was never read
`core: [A, B]` -> domain empty
no `architecture:` key at all -> "Untitled Architecture"
Cause: parser.ts:91,92,94,102 all use `isObj(x) ? x : {}`, which turns
"wrong shape" into "absent". The fallbacks are right for absent and
wrong for present-but-malformed. Note `inbond:` (typo) happened to be
rejected, only because an adapter then referenced a port that was never
read; with no adapter it would pass too.
The three shipped examples all parse and all have `architecture.name`,
so tightening breaks nothing in the repo.
Mechanism Extend parse(), no new dependency. One helper:
section(doc, key): undefined/null -> {}; present but not a mapping
-> throw ParseError(`'${key}' must be a mapping`)
used at the four sites above. Add a known-key check per level
(top level: architecture, actors, core, ports, adapters; likewise
ports, adapters, core.application) that throws on an unknown key and
suggests the nearest known one. Require `architecture.name` (the SPEC
already says required). Tests live in V11.
What it forbids Forward compatibility: dsl/SPEC.md:150-154 lists planned extensions
(bounded contexts, multiplicity). A newer spec read by an older
hex-render would be rejected instead of ignored. Decide: reject (matches
the parser's own header) or warn on unknown keys and only throw on wrong
shapes. Rejecting is my recommendation while the grammar is 0.x.
Proof it works Write the five cases above as tests first and watch them fail against the
current parser (they do: all five print ACCEPTED). Then fix and watch
them pass. Also run all three examples/ through the new parse().
Cost About 25 lines in parser.ts, 5 test cases. Behaviour change is
user-visible (specs that load today may start erroring), so it wants a
0.2.0 note.
V2 - hex-render exits 0 when some specs are invalid [T1 Violated]
Invariant A spec that fails validation fails the command.
Rule source skills/hexarch/SKILL.md:120: "`hex-render <file>` validates on load; a
bad spec fails fast". The skill tells agents to use the CLI as the
validator in its "Curate / lint" workflow, and the CLI is the only
validator the repo ships.
Evidence cli/index.ts:141 `if (valid === 0) fail(...)`. Anything short of
all-invalid renders and exits 0. Reproduced:
hex-render --dir specs/ -o out.html (bad.yaml + url-shortener.yaml)
-> prints "x bad.yaml: adapter 'A' implements unknown port
'Missing'", writes out.html, exit=0
hex-render bad.yaml -o out2.html -> exit=1
So `hex-render --dir docs/ -o x.html` in someone's CI is green while a
spec in docs/ is broken. There is no validate-only mode either.
Mechanism In readAndValidate (index.ts:125-143) set `process.exitCode = 1` when
`valid < files.length`, after rendering, so the picker flow still works.
Optionally add `--check` (validate, print, exit, no render, no browser).
What it forbids Scripts that do `hex-render --dir docs -o x.html && open x.html` while
one spec is a work in progress would stop at the `&&`. That is the
point, but say it in the changelog. `--serve` should stay exit-0-on-
start (it is a long-running process; keep the red mark in the viewer).
Proof it works Re-run the reproduction above: expect exit=1 with the file still written.
Cost 3 lines for the exit code, about 10 for `--check`.
V3 - the only CI job publishes releases without running the typecheck [T2 Decorative]
Invariant Nothing is published from a tag that does not pass `just check`.
Rule source Justfile:32 `check` ("Typecheck viewer + CLI"), README.md "Develop"
section. The check exists and is the repo's definition of green; the
release is the one moment the repo's output leaves the machine.
Evidence .github/workflows/release.yml triggers on tags only (:14-15) and never
calls `npm run typecheck`, `just check`, or any test. What type-checking
it gets is accidental: `build:embed` runs `tsc -b` (:61) which covers
viewer + core. `cli/index.ts`, `cli/lib/*` are only compiled by
`bun build --compile` (build-all.sh:20), which erases types without
checking them. Experiment on a scratch clone: appended
`const bad: number = "x";` to cli/index.ts -> `tsc --noEmit` reports
TS2322; `bun build cli/index.ts --compile` exits 0; the produced
binary runs and prints 0.1.1.
Also `bun-version: latest` (release.yml:52): the toolchain that
compiles the shipped binary changes between releases with no commit.
Mechanism Add one step to the existing job, after "Build viewer bundle + embed
it" (the embed exists by then, so the CLI typecheck can run):
- run: npm run typecheck
and pin `bun-version` to the version the repo is built with locally
(1.4.2 here). No new workflow file, no new tool. If you later want PR
feedback, the same line goes in an `on: [push, pull_request]` job; for
one maintainer the release gate is the higher-leverage place.
What it forbids Nothing legitimate. It makes a release cost about 10 more seconds.
Proof it works On a scratch branch append the type error above, push a tag to a fork
with the secret preflight stubbed (or run the step sequence locally:
build:embed, gen-embed, typecheck) and confirm the job stops before
"Publish GitHub release". I did the local sequence: typecheck exits 2.
Cost 2 lines in an existing file, plus about 10 s of CI per release.
V4 - two typecheck entry points disagree; npm run typecheck fails on a fresh clone [T2 Decorative]
Invariant The documented typecheck command works from a clean checkout.
Rule source package.json:15 `typecheck`; README.md and viewer/README.md present
`typecheck` as the check. Justfile:32 `check: embed` is a second,
different definition.
Evidence git clone + (node_modules linked) + `npm run typecheck`:
viewer: passes
cli: lib/html.ts(5,33): error TS2307: Cannot find module '../embed'
`cli/embed.ts` is generated by gen-embed.ts and gitignored
(.gitignore, line "cli/embed.ts"), so the CLI typecheck depends on a
208 KB build artifact that has nothing to do with types. `just check`
works only because it builds the viewer first. Anyone (or any future CI
job) that follows the root script gets red on a good tree and learns to
ignore it, which is how a check becomes decorative.
Mechanism Commit `cli/embed.d.ts` containing one line:
export const VIEWER_HTML_B64: string;
TypeScript resolves the generated `embed.ts` when present and the
declaration when not (verified both ways: rc=0 with only the .d.ts,
rc=0 with both). Then make the Justfile `check` recipe call
`npm run typecheck` so there is one definition. `just check` no
longer needs the `embed` dependency and drops from about 15 s to
about 5 s.
What it forbids Nothing. The declaration cannot drift because the generated file is
one exported constant.
Proof it works On a fresh clone: `npm run typecheck` exits 0 without running the
embed (verified on the scratch clone). Residual risk: the .d.ts cannot
notice if gen-embed.ts renames the export; the first `just build` would.
Cost 1 new line-file, 1 changed Justfile line.
V5 - core must stay environment-neutral; today nothing stops DOM or Node leaking into it [T3 One import away]
Invariant core/ imports only js-yaml and itself, and touches neither DOM nor Node
APIs, because the same files run in the browser bundle and in the Bun
binary.
Rule source core/package.json description: "semantic model + YAML parser/validator
(shared by viewer and CLI)"; README.md "core/ shared semantic model";
model.ts:1-8 "no geometry". Structure implies it: two consumers with
different runtimes.
Evidence Holds today: core/*.ts import only "js-yaml" and "./model"; viewer/src
and cli never import each other (grep). But both consumers
typecheck core under a tsconfig that permits everything: viewer has DOM
lib plus `types: ["vite/client", "node"]`, cli has `types: ["bun",
"node"]` and default libs. Experiment: appended
import fs from "node:fs"; ... && document.title
to core/parser.ts. viewer `tsc`: clean. cli `tsc`: clean. `vite build`
(embed): "built in 1.98s", only a "Module node:fs has been externalized
for browser compatibility" warning, and the shipped viewer would throw
at runtime.
Mechanism A type-level boundary, not a test. Add core/tsconfig.json with
`"lib": ["ES2022"], "types": []`, `include: ["*.ts"]`, and run
`tsc -p core` from `typecheck` (one more command in the existing script).
With the leak above it reports TS2307 on node:fs and TS2584 on
`document`; on the clean tree it passes. No dependency, no new
framework, and the violation is unrepresentable at typecheck time
rather than caught by a pattern match.
What it forbids Any host global outside ES2022 (`console`, `URL`, `TextEncoder`,
`structuredClone`). If core legitimately needs one, widen `lib` in
core/tsconfig.json, a deliberate one-line edit that shows up in review.
Proof it works Append `import fs from "node:fs"` to core/parser.ts, run `tsc -p core`,
watch it fail, revert. (Done on a scratch clone: red with the two errors
above; green after revert.)
Cost 8-line tsconfig, 1 command in package.json. I deliberately do not
recommend a viewer-vs-cli import rule: no evidence of pressure, and the
generated-embed seam already separates them.
V6 - port and adapter names are identifiers, but uniqueness is not enforced and the layout mis-draws collisions [T3 One import away]
Invariant Port names are unique across inbound and outbound; adapter names unique
across primary and secondary; actor names unique.
Rule source Structural: `implements` and `drives` reference by name alone
(model.ts:36-39, 46; SPEC.md:102). The layout keys everything by name:
layout.ts:399-401 `portBox = new Map(); portBox.set(p.port.name, ...)`
over inbound and outbound together; connector ids `p:${adapter}->${t}`
(layout.ts:410).
Evidence parse() accepts `inbound: [P]` + `outbound: [P]`, `inbound: [P, P]`,
and two adapters named A (probed). computeLayout on the first (run
headlessly under bun, which works because measure.ts has a no-DOM
fallback):
inbound P box x=284, outbound P box x=680
connector p:A->P to.x = 680 <- the primary adapter's arrow lands on
the OUTBOUND port, on the far side of the hexagon
No validation error, no warning; the diagram is just wrong. Nothing in
examples/ collides today.
Mechanism Add to validate() (parser.ts:129): collect names per namespace and throw
ParseError(`duplicate port name 'P' (inbound[0], outbound[0])`).
Alternative that keeps names legal: key layout maps by `side:name` and
make `implements` resolve against the adapter's own side, since
validation rule 2 already forces the side. That is the better model
fix (a port called `Notification` on both sides is natural), but it is
a larger change; rejecting is the 6-line version.
What it forbids Reusing one name for an inbound and an outbound port. Legitimate
(e.g. `Notification` offered and required), which is why the side-
scoped key is the better long-term answer. Decide before 1.0.
Proof it works The headless layout probe above is the failing test: assert every
connector's `to` equals the box of the port on the adapter's own side.
It fails today for the same-name spec.
Cost About 10 lines plus a 6-line test (V11), or about 30 lines for the
side-scoped keys.
V7 - release version is typed in three places by hand and nothing compares them [T4 Review-only]
Invariant The tag, the four package.json versions, and what `hex-render --version`
prints agree.
Rule source Commit 49cbe4a "release: 0.1.1" (hand-edited root, core, cli, viewer
package.json + lockfile). Justfile:49 `release VERSION` creates the tag
without touching any file.
Evidence cli/index.ts:17,79 prints `version` from cli/package.json; the Homebrew
formula takes its version from the tag (release.yml:77
`VERSION="${GITHUB_REF_NAME#v}"`). `just release 0.1.2` on a tree still
at 0.1.1 publishes a binary whose --version says 0.1.1 under a formula
that says 0.1.2. Currently consistent (v0.1.1 points at 49cbe4a, all four
files 0.1.1).
Mechanism One step in the existing release job, next to the existing preflight:
test "$(node -p "require('./cli/package.json').version")" = "${GITHUB_REF_NAME#v}"
and the same check as a first line of the `release` Justfile recipe so
it fails before the tag exists.
What it forbids Tagging a pre-release suffix (`v0.2.0-rc1`) against a plain package
version; strip the suffix or bump first.
Proof it works Run the comparison with GITHUB_REF_NAME=v9.9.9 locally and watch it fail.
Cost 2 lines in release.yml, 1 in the Justfile.
V8 - the skill promises specs with no orphan ports; the shipped examples are the skill's reference and nothing checks them [T4 Review-only]
Invariant Every spec in examples/ parses and has no declared port that no adapter
implements.
Rule source skills/hexarch/SKILL.md:124: "No orphans. Every declared port is
implemented by >=1 adapter (an unimplemented port is usually a modelling
gap or a stale entry)". The skill's reference/examples is a symlink
to examples/ (git mode 120000), so agents copy these specs as the
canonical shape.
Evidence Probe: order-service, iot-ingest, url-shortener all parse; orphan ports:
[] for each. So the rule holds, by hand. The parser does not check it
(validate() has the four documented rules only), so an agent following
the skill's "lint" step has no tool support.
Mechanism A test (V11) that parses every file in examples/ and asserts the orphan
set is empty. Do NOT add it to parse(): a spec with a placeholder port is
legitimate work in progress. If you want authors to see it, emit it as a
warning from the CLI (stderr, exit unchanged).
What it forbids Adding an example that demonstrates a deliberately unimplemented port.
Rename it or keep it out of examples/.
Proof it works Add an unimplemented port to a scratch copy of order-service.yaml and
watch the test go red.
Cost 8 lines in the V11 test file.
V9 - "the layout is a pure function" has no test, and it is already headlessly runnable [T4 Review-only]
Invariant computeLayout is a deterministic function of the model: every
`implements` and `drives` pair produces exactly one connector landing on
the right side, and boxes in a column do not overlap.
Rule source layout.ts:3-5 "Pure and deterministic given the measured text widths";
README.md "The layout is a pure function of the parsed model plus
measured text, so the same code drives the live viewer and any static
output".
Evidence Ran computeLayout under bun against order-service.yaml with no DOM:
it works (measure.ts:19 falls back to a length estimate), 6 implements
pairs plus actor drives = 8 connectors. 471 lines of geometry whose only
current verification is a human looking at screenshots from
viewer/scripts/shot.mjs (manual, needs a running dev server, outside
every tsconfig).
Mechanism Structural assertions only, against the fallback measurer: connector
count equals implements + drives pairs across all examples; each
connector endpoint lies on its own port or adapter box; no box overlap
per column. Do not assert pixel values: the fallback widths are not real
font widths.
What it forbids Pixel assertions and font-dependent expectations. Visual polish stays a
screenshot job, which is the right tool for it.
Proof it works Break one `adapterBox.set` line in layout.ts locally; the count or
endpoint assertion goes red.
Cost About 25 lines; shares V6's probe.
V10 - strictness drift between viewer and cli, and noUncheckedIndexedAccess has a live bug behind it [T5 promoted by evidence]
Invariant Both packages typecheck under one strictness level, and array and
record access is checked.
Rule source Both tsconfigs say `strict: true`; viewer adds noUnusedLocals,
noUnusedParameters, noFallthroughCasesInSwitch (viewer/tsconfig.json),
cli has none of them.
Evidence Counted by running tsc with each flag on a scratch clone:
noUncheckedIndexedAccess viewer 2 errors, cli 7, core 0
noUnusedLocals/Parameters cli 0 (free to align)
exactOptionalPropertyTypes viewer 4, cli 7
noImplicitReturns viewer 2
All seven cli errors are in parseArgs; the one with a user-visible effect is
cli/index.ts:75 `next = () => inlineVal ?? toks[++i]`, typed `string` but
`undefined` at the end of argv (error at :81). Reproduced end to end:
$ hex-render --file
TypeError: The "paths[0]" property must be of type string, got
undefined (raw Bun stack trace, not "hex-render: --file needs
a value")
and `hex-render spec.yaml -o` silently ignores the dangling flag.
The flag points at the line the bug is on. This is why it is promoted
out of the checklist: it has a failing input.
Mechanism Extract tsconfig.base.json (strict, skipLibCheck, noUnused*,
noFallthroughCasesInSwitch, noUncheckedIndexedAccess) and `extends` it
in viewer, cli and core (V5). Fix 9 error sites; `next()` should fail
with "<flag> needs a value".
What it forbids Nothing; the 2 viewer sites are an `entry` destructure and an index
type, both one-line guards. Do not turn on noPropertyAccessFromIndexSignature
(68 errors, near-zero value).
Proof it works Enable the flag, watch 9 errors, fix, watch 0; re-run `hex-render --file`
and expect a one-line message and exit 1.
Cost 1 new 12-line file, 3 `extends` lines, about 10 lines of fixes.
V11 - there is no test runner, and the one in the toolchain is already installed [T5 promoted by evidence]
Invariant The parser's documented contract (SPEC.md:127-137, four rules, shorthands,
defaults) is executable.
Rule source skills/hexarch/SKILL.md:95 "Rules that keep a spec valid (the parser
enforces these)". Four rules, all currently true (probed), none pinned.
Evidence Zero test files, zero test scripts, no runner in any package.json. The
parser is the single input boundary for both consumers and for every
agent using the skill; V1, V6, V8, V9 and the V2 reproduction are all
tests waiting to be written, and V1 found five silent accepts by 19 hand
probes in one sitting. The value is not a test count: the 19 probe inputs
(listed by name in the Method section) already exist and turn into
assertions in minutes.
`bun test` is the runner: bun 1.4.2 is already a build requirement
(README, install.sh, release.yml), zero dependencies.
Mechanism Put tests in `cli/test/` (not `core/`: viewer/tsconfig.json includes
../core, so `import "bun:test"` there breaks the viewer typecheck. I
verified: TS2307 'bun:test' in core/parser.test.ts). Add "test" to
cli/tsconfig `include`, `"test": "bun test"` in root package.json, and
`just test`. Seed with: the four validation rules (accept and reject
cases), one shorthand case each, the V1/V6 probes, examples-parse and
no-orphan (V8), layout invariants (V9).
What it forbids Nothing, but it creates a thing to maintain; keep it to the parser,
the CLI arg parsing, and the layout invariants. Do not add coverage
thresholds or mutation testing at this size (see appendix).
Proof it works Each new test is born red against the current code (V1, V2, V6, V10 all
have live failing inputs); a test that cannot be seen failing is not
added.
Cost One test directory, 2 script lines, about 150 lines for the seed set.
CI cost: `bun test` ran a 1-test file in 0.02 s.
4. Existing suite notes
No suite to audit. What does exist: the typecheck (see section 2), three example specs that all parse today, four manual screenshot scripts (viewer/scripts/*.mjs, 110 lines, not type-checked because no tsconfig includes .mjs, and playwright is a viewer devDependency solely for them).
Docs have drifted from the tree. viewer/README.md:32-33 lists src/dsl/model.ts and src/dsl/parser.ts; they moved to core/ (viewer/src has no dsl/ directory). viewer/README.md:22 documents typecheck as tsc --noEmit; the script is tsc -b --noEmit. A one-line test that every backticked path in READMEs exists would have caught both, but at this size a review pass is enough.
The generated embed can go stale. cli/embed.ts is gitignored and regenerated only by just embed and its dependents. bun run cli/index.ts run directly serves whatever viewer build was last embedded. The just render and just serve recipes depend on embed, so the supported paths are fine; the direct path is not.
Escape-hatch density is low: no any, no @ts-ignore, no eslint-disable; one as cast (viewer/src/specs.ts:37), four non-null assertions (Diagram.tsx:71,94,95,340). The .find(...)! at Diagram.tsx:340 relies on port names being unique (V6).
- Speed:
just check15 s end to end on a cold viewer build, of which about 5 s istsc. Not a correctness issue.
5. What's already right
strict: truein both typechecked packages, plusnoUnusedLocalsandnoFallthroughCasesInSwitchin the viewer. The V10 recommendation extends this rather than adding a parallel tool.build:embedrunstsc -bbeforevite build, so the viewer cannot ship type-broken even though Vite would let it.- The dependency graph is clean and small:
coreimports onlyjs-yaml; viewer and CLI meet only through a generated artifact. V5 locks down what already holds. - Parser errors name the element and the fix (
parser.ts:137-157), the best property to build tests on. - Shell scripts are clean under shellcheck (1 info note across 3 scripts), so no linter rollout is needed there.
- The release preflight (commit f753c29) is a good pattern to copy: cheap check first, before anything is built or published. V3 and V7 follow it.
- The skill's
reference/is a tracked symlink todsl/SPEC.mdandexamples/, so the contract has one source and cannot drift from the docs it teaches. computeLayoutis a real pure function, runnable headlessly under Bun with no setup. That is why V9 is cheap.
6. Appendix: unenforced conventions and checklist gaps (T5, not recommendations)
None of these is declined in a repo document (there are no ADRs); none has repo evidence attached yet.
| Item | Bar it would need to clear |
|---|---|
| ESLint / Biome | A second contributor, or the first lint-class bug tsc cannot see (a floating promise in serve.ts). At 1,700 lines, strict tsc plus V10 covers most of it. |
| dependency-cruiser | A third consumer of core, or a boundary V5's tsconfig cannot express. It would be a new tool for a graph with three edges. |
| Coverage threshold | Not before V11 exists; a threshold on an empty suite is decoration. |
| Mutation testing (pitest-class) | The parser tests are the only candidate and a 171-line file does not justify the tuning cycle. |
| Property-based tests for the parser | Worth it only if V1 and V6 leave the validator still leaking. Fuzzing YAML shapes is a natural fit later. |
| knip / unused exports | Not run. Cheap one-time check, not a gate at this size. |
Pinned @types/bun / typescript ranges | Both are ^; lockfile pins them, so only an update PR would move them. |
npm ci with playwright in the release build | Installs a dev dependency used only by manual scripts. Cosmetic. |
7. Method
Read: Justfile, all four package.json, both tsconfig.json, vite.config.ts, .github/workflows/release.yml, scripts/*.sh, install.sh, .gitignore, all of core/, cli/, viewer/src/specs.ts, viewer/src/App.tsx (top), layout.ts and Diagram.tsx (the parts cited), dsl/SPEC.md, README.md, viewer/README.md, skills/hexarch/SKILL.md, git log, tags, and the release: 0.1.1 commit. Rules harvested from SPEC, SKILL, READMEs, parser/layout header comments; modal-verb grep over source found no only/never/must constraint comments beyond those.
Ran (read-only against the repo): 19 hand-written probe inputs (empty doc, missing/typo'd/mis-shaped sections, duplicate and colliding names, wrong-direction implements, zero-port adapter, actor driving a secondary adapter, invalid YAML, top-level list, non-string names) plus the three examples through parse(); computeLayout headlessly on two specs; shellcheck once via nix run. All in /tmp; nothing was written inside the audited repository.
Ran on a scratch clone in /tmp/hexaudit (node_modules symlinked): root npm run typecheck (red, fresh clone), just check (green, 15 s), tsc with five extra strictness flags, a leaked node:fs/document in core through viewer tsc, cli tsc, vite build, and a neutral core/tsconfig.json; a deliberate type error through tsc and bun build --compile; embed.d.ts resolution with and without the generated file; a core/parser.test.ts under bun test and viewer tsc; the CLI with --file, -o and a mixed valid/invalid --dir.
Verified vs assumed: V1, V2, V3 (local sequence), V4, V5, V6 (headless layout), V8 (probe), V10, V11 (the viewer-typecheck conflict) were reproduced. V3's "stops before publish" and V7's mismatch are reasoned from release.yml and cli/index.ts, not executed in Actions (no tag was pushed, and the tap token is not available here). V9's invariant list is proposed, not run. Not run: knip, the browser viewer, Actions itself.
Known blind spot: the viewer UI (App.tsx, Diagram.tsx, styles.css) was judged as source only; I did not open it in a browser, so visual and interaction regressions are outside this audit.
Diagram.tsx
PDF · document
Example file from a real run - the skill writes it into your workspace.
Connects securely to your tools. The creator never sees your data.
About this skill
Your repo has rules nobody enforces and abstractions nobody justifies. This skill finds both, and proves it with file:line evidence instead of taste.
It carries two read-only audits and picks the right one from what you ask.
Verification audit: what do your gates actually guarantee?
Maps what your build, analyzers, architecture tests and CI gates genuinely guarantee, then finds the gap against what your team believes they guarantee.
Its core move: the highest-value check to add is one your repo already believes in but defends only by review discipline. "Domain stays framework-free", "only the llm module touches the SDK": rules living in an ADR or in one person's head are architecture tests waiting to be extracted, and because the rule is already agreed, the fix needs no debate.
Every finding names the invariant, its source, the evidence, the exact mechanism, what it would forbid, how to prove it works, and what it costs in lines. Capped at 12-18 findings, because a report proposing forty rules gets read as noise. Ships with playbooks for JVM (Konsist, ArchUnit, Maven/Gradle), Python (import-linter, ruff, mypy, pytest) and TypeScript (dependency-cruiser, eslint, tsc, vitest).
Vertical slice audit: does this abstraction earn its keep?
Answers "too many types?", "too much indirection?", "is this module secretly two things?" with evidence. It traces one piece of data end to end, names every representation it becomes with file:line, and rules on what each transition actually buys: validation, a refusal path, provenance, serialization, or nothing.
An optional placement census classifies every file in the suspect modules as core / adapter / wire / support and reports the real line totals, so "this module is bloated" becomes a number. "The typing is load-bearing" is a legitimate verdict; it won't invent a refactor to justify the exercise.
Why they ship together
They are two halves of one question. The verification audit asks what your repo defends; the vertical slice audit asks what it carries. One finds the rules nothing enforces, the other finds the structure nothing justifies.
What it doesn't do
No edits, no commits, no --fix, no new plugins or dependencies. Running your existing gate to observe it (mvn verify, pytest, npm run typecheck) is fair game and usually the best evidence available; changing what it does is not. The output is a dated report in your repo, recording the commit it audited.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Code Quality & Review.
Read-only: it reports, it never refactors, installs or commits. The quality of the audit tracks the model running it; the type trace and the ranked findings are judgement work. Language playbooks cover JVM, Python and TypeScript; other stacks get the same method without a playbook, and the report says so. Observing a gate means running it, so the repo's own toolchain must be installed.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 22 days ago
- Software
Git
Permissions
Read-only audit. Reads source, build and CI config; runs the repo's own existing gate (e.g. mvn verify, pytest, npm run typecheck) to observe it, never changes it. Writes exactly one file: the report under review/. Git is used read-only to record the audited commit. No network access, no edits, no commits.