Codebase Audit Pack

    1

    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

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIDeepSeekDeepSeekMuseMuse+22 more

    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, commit f753c29 (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 with references/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.

    CheckWired intoLocal 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:embedYes (just check, root npm run typecheck)Yes, incidentally: npm run build:embed at release.yml:61Fails
    tsc strict, clicli typecheck = tsc --noEmitjust check: yes. Root npm run typecheck: fails on a clean checkout (TS2307, cli/embed.ts is generated and gitignored)NoFails (when it can run)
    noUnusedLocals, noUnusedParameters, noFallthroughCasesInSwitchviewer/tsconfig.json onlyViewer onlyViewer onlyFails. cli lacks them (0 errors if enabled)
    vite buildbuild:embedNot in just checkYesStrips types, proves nothing about them
    bun build --compilescripts/build-all.sh, just buildNot in just checkYesDoes 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 specNoThrows ParseError, no test pins it
    Unit / integration / snapshot testsNone existn/an/an/a
    Linter, formatter, import-boundary rulesNone exist (no eslint, prettier, biome, dependency-cruiser, knip)n/an/an/a
    Tap-token preflightrelease.yml:23-44NoYes, first stepFails (good)
    Shell scripts (install.sh, build-all.sh, render-formula.sh)No lint wiredNoNoI ran shellcheck once: 1 info-level note, otherwise clean
    Screenshot helpers viewer/scripts/{shot,hover,export,shotfile}.mjsManual, need a running dev serverNoNoProduce 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 check 15 s end to end on a cold viewer build, of which about 5 s is tsc. Not a correctness issue.

    5. What's already right

    • strict: true in both typechecked packages, plus noUnusedLocals and noFallthroughCasesInSwitch in the viewer. The V10 recommendation extends this rather than adding a parallel tool.
    • build:embed runs tsc -b before vite build, so the viewer cannot ship type-broken even though Vite would let it.
    • The dependency graph is clean and small: core imports only js-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 to dsl/SPEC.md and examples/, so the contract has one source and cannot drift from the docs it teaches.
    • computeLayout is 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.

    ItemBar it would need to clear
    ESLint / BiomeA 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-cruiserA 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 thresholdNot 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 parserWorth it only if V1 and V6 leave the validator still leaking. Fuzzing YAML shapes is a natural fit later.
    knip / unused exportsNot run. Cheap one-time check, not a gate at this size.
    Pinned @types/bun / typescript rangesBoth are ^; lockfile pins them, so only an update PR would move them.
    npm ci with playwright in the release buildInstalls 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

    Generated

    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. 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. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 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 Files
    Write Files
    Terminal / Shell

    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.

    Listed22 days ago

    What's inside

    Frequently Asked Questions

    Any agent that reads the open SKILL.md format, including Claude Code, Cursor and Codex CLI. Unzip it into your agent's skills folder and ask in your own words.

    A generic review recites best practice. This skill starts from the rules your repo already claims (ADRs, READMEs, the module graph, comments) and checks which ones anything actually enforces. Every finding cites file:line, names the exact mechanism to add, what it would forbid, how to prove it works, and what it costs. Findings are capped at 12-18 so the report gets read.

    No. Install the skill, open your repo, and ask. It finds your build files, analyzers, tests and CI config itself. A repo with no tests or linter at all is a valid target; the gap is then the finding.

    That is what the vertical slice audit is for. It follows one piece of data through every type it becomes and rules on what each transition buys: validation, a refusal path, provenance, serialization, or nothing. The optional placement census puts real line counts on core vs adapter vs wire code. If the typing turns out to be load-bearing, it says so instead of inventing a refactor.

    No. It reads files and may run your repo's existing build or test command to observe it. The only file it writes is the report, dated and recording the commit it audited.

    One skill with both audits: the verification audit with JVM, Python and TypeScript playbooks, and the vertical slice audit with its placement census. One-time purchase, use it on as many of your own and your employer's repositories as you like.

    New in Code Quality & Review