This is a self-contained setup guide for the architecture-awareness half of an agent-driven\nrepository: a PlantUML map of the code tree and its cross-cutting flows, a linter that keeps the map\nhonest against the code, and a design-time hook that forces the map to be consulted before a new\nfeature is written. It is the companion to The requirements machine —\nhttps://kodavr.xyz/dumps/2026-09-18-opencode-requirements-machine/ — and it extends that registry:\nthe hook below lives inside the registry's coverage check (npm run req). Apply the requirements\nmachine first.
The problem it solves is not \"the agent cannot read files\". It is that an agent, working one file at a\ntime, cannot see the shape of the system — so the shortest line to its goal often cuts across a\nshared step, and that shortcut is locally green and globally a second source of truth that drifts.\nThe map is the helicopter view that lets the agent see the forest; the linter is what makes the map\nworth trusting; the hook is what makes the agent open it.
\nAll sources are inlined in §6. Paths: <project> = the root of your repository, ~ = your home\ndirectory. The example map and the palette are from the author's project (Kodavr, a static site);\ntreat them as a worked example, not as your architecture — your drawers, processes and classes differ.
Long agent sessions fail in a specific architectural way. The agent is asked for a small feature. It\nreads the file in front of it, finds the fastest correct-looking path, and takes it — a direct call\nfrom the page renderer to the copy module, bypassing the i18n registry that is supposed to own every\nstring; a fresh write path next to the existing one instead of through the shared publishing engine.\nEach shortcut passes its own tests. What breaks is a cross-cutting flow: a concern that is owned\nby one shared step (a registry, an engine, an audit gate) and that every feature is supposed to route\nthrough. Two write paths drift; the registry stops being the single truth.
\nA diagram in the prompt does not fix this by itself:
\nSo the design has three parts, and they only work together: a cheap convention (§2), a\nlinter that makes the map true (§3), and a hook that makes the map get used (§4).
\n<project>/\n ├── docs/\n │ ├── workflow-arrows.puml # the map: the machine source the agent reads (this dump)\n │ └── workflow-arrows.svg # its human render (generated; never hand-edited)\n ├── scripts/\n │ └── tooling/\n │ ├── workflow-map/\n │ │ ├── workflow-arrows-lint.mjs # the linter: the map vs the code tree (this dump)\n │ │ └── workflow-arrows-svg.mjs # injects the .svg hover block (this dump)\n │ └── quality-gates/\n │ └── req-coverage.js # the registry check + the flow-impact hook (base + this dump)\n ├── AGENTS/\n │ ├── workflow-arrows.md # the convention doc the agent reads (this dump)\n │ └── requirements.md # registry protocol with the flow subsection (base + this dump)\n ├── AGENTS.md # the startup digest that points at the map (base + this dump)\n └── tests/\n └── unit/workflow-arrows.test.js # pins P1-P3 with synthetic diagrams (this dump)\ndocs/workflow-arrows.puml is plain text the agent can read and you can edit; the linter\nchecks it. .svg is only for human eyes and is generated — one artifact, two files.The agent does not \"see\" a diagram; it reads the .puml as text. What it needs is to answer two\nquestions cheaply: who is in which directory, and what calls what. Everything else is human\ngarnish. Design the notation around those two facts and keep it small.
Be honest about what this is, and is not. It is not a complete architecture diagram and does not\ntry to be one — someone will always object that a map this sparse is \"not real architecture\". That is\nthe wrong test. This is a helicopter view: an altitude deliberately chosen so an agent can hold the\nwhole system in a few thousand tokens. Its only job is to make the agent see the forest before it edits\none tree, so it widens an existing flow instead of cutting a new path across it. Judge it by whether\nthat works, not by how complete it looks.
\npackage \"<dir>\\n<why it exists>\" block\n— the header states why the directory exists.[[../<path>#symbol <label>]], symbol optional).<<ext>>.-- → members)Every brick and drawer uses exactly one grammar, so the reader is never confused about which line is\nwhich:
\ncomponent \"build.mjs\nthe one build pipeline (controller)\n--\nbuildProject\" as BUILD\nName first, then one or more lines of what it does (business meaning), then — only when there are\nexported symbols to list — a -- divider and the members. A brick whose meaning line already\nnames its single method needs no members line. The old shape (members above the line, a description\nbelow it) is drift: check J rejects it. This is small, but it is the difference between a map an\nagent parses in one pass and a map it mis-reads.
1..N) are the cross-cutting flow: the journey a unit of work takes\nthrough the system;N · callee.method() — the API method of the target brick (the callee);--> is a call, dashed ..> is a return or a push;N ⟵ ...); a numbered call carries a link.Each arrow is coloured by the business process it belongs to, from a small fixed palette, and the\nnumbered flow is grouped by process rank: all rank-1 steps before rank-2, and so on. This is how\nan agent, holding one requirement, sees which slice of the map it is touching. The palette lives in\none place — PROCESSES at the top of the linter — and is exported, so the registry hook (§4) uses the\nsame names (one truth per entity).
| # | \nProcess example | \nColour | \nCovers | \n
|---|---|---|---|
| 1 | \nPR review | \n#00897B teal | \na contribution arrives and is validated | \n
| 2 | \nPublish | \n#1E88E5 blue | \nbuild → engine → artifact | \n
| 3 | \nNotify | \n#8E24AA purple | \nmirroring / notifications | \n
| 4 | \nConsume | \n#43A047 green | \nmachine + human reads | \n
| 5 | \nEngineering | \n#6D4C41 brown | \nlocal dev / tooling | \n
Grey #9E9E9E is structural glue (plain imports, assets): never a process, never a numbered step.
Every non-exempt brick must be reachable from an actor by following the drawn arrows (dashed\nincluded). An orphan brick is a sign the map is decorative rather than a flow: it means something\nexists that nothing calls, which is either a missing arrow or dead code. Check P3 enforces it.
\nA linter that cannot be satisfied by hand gets disabled, and a linter that can be silenced silently\nbecomes self-deception. So there is exactly one way to suppress a finding, and it must justify\nitself: an @lint-ignore block embedded in the .puml:
' @lint-ignore\n' [I] IGN -> CTRL_DUMPS # by-path: spawned by path, not imported\n' @end\nI, P1, P2, P3) — never a structural one;# <mechanism>: <reason>, where the mechanism is from a closed vocabulary\n(by-path, dynamic, transitive, non-module) — so a mask asserts why it is a false\npositive, not merely that the author is tired;suppressed N (see @lint-ignore).The point is that a suppression is a claim a reviewer can check, not a silence.
\nThe map is not an exhaustive call graph. Its job is the altitude at which an agent can see the whole\nsystem for a few thousand tokens. Concretely, the rules that keep it cheap:
\ncover: files: every matching file must appear as one brick) or dir-only\n(cover: dir: bricks are illustrative) — use dir-only where box-by-box coverage would only add noise;If a map becomes too heavy to read in one pass, it has stopped being architectural glue and become\nanother file the agent skips.
\nThe linter is the part that turns a document into a mechanism. It is a pure function —\nlintDiagram({ text, pumlDir, repoRoot }) — so it is testable without the filesystem, and it runs both\nlocally and in CI.
| check | \nwhat it holds | \n
|---|---|
| A | \ndrawer coverage both ways — declared drawers ↔ the configured first-party dirs | \n
| B | \nfile coverage both ways for code drawers — every file is exactly one brick; every brick link exists; no file drawn twice | \n
| C | \nevery [[...]] link resolves, relative to docs/ | \n
| D | \na link's #symbol is declared in the target file | \n
| E | \nstep numbers are exactly 1..N, unique and contiguous | \n
| F | \na brick's stereotype equals its drawer's | \n
| G | \na numbered call to a module carries a [[file#symbol]] link; a numbered return carries none | \n
| I | \na drawn edge between two module bricks is a real import in one direction — the linter builds the first-party import graph and flags a drawn edge the code does not have | \n
| J | \none label grammar (name → meaning → -- → members); a linked #symbol must be a member | \n
| P1 | \nevery arrow carries a palette colour or the structural grey | \n
| P2 | \na numbered step carries a process colour and the process rank is non-decreasing in draw order | \n
| P3 | \nevery non-exempt brick is reachable from an actor — no orphans | \n
| M | \nthe @lint-ignore block is well-formed; guards (unused mask, unknown mechanism, no reason) are never suppressible | \n
Checks A–H are structural (the map matches the tree). P1–P3 are semantic (the map reads as a\nflow) and are additionally pinned by synthetic diagrams in tests/unit/workflow-arrows.test.js, so\nthe linter's own behaviour is contracted by tests, the same way any other requirement is.
Check I is the one that earns trust. A map is most dangerous not when it is incomplete but when\nit is confidently wrong. In the author's repository, the first run of I failed on an edge the map\ndrew between the page layer and the copy module: the code did not import it. The map was lying, and\nthe linter said so — which is exactly the class of lie an agent cannot detect by reading one file. The\nfix is never to delete the edge; it is to fix the map (or, if the code change was unintended, the\ncode): retarget the arrow to the real import, and add the arrow that keeps the target reachable.
A true, cheap map is still a document. For the agent to use it at design time, the consultation has\nto be part of a step every feature already passes. In the companion setup that step is the\nrequirements registry: every obligation lives as one row in REQUIREMENTS.md with a stable ID and a\ntest. So the hook is one field on the row:
flow: — the business process(es) it extends or touches, none, or (for\ngrandfathered rows) legacy;PROCESSES);npm run req fails a new row without a valid flow:, or with an unknown process.The agent cannot reason about which process a feature touches without looking at the map — so merely\nfilling the field opens the map. That is the whole trick: not a reminder in the prompt, but a required\nfield whose value comes from the map.
\nThe exemption is frozen in code, not in a list. Rows that predate the hook carry flow: legacy.\nThe set is anchored by LEGACY = { count, sha256 } inside the coverage script: the check recomputes\nthe legacy set and fails if it changed. So a new row cannot dodge the hook by writing legacy — that\ngrows the set and trips the anchor. Changing the set is a deliberate, reviewable edit of the constant,\nnot a quiet marker.
(Implementation note for the inlined script: the 64-character digest literal is replaced by a\nplaceholder in §6.4, both because it is meaningless to a stranger and because a long hex run trips the\ndump's own secret-entropy scan. Compute your own with the one-liner in §6.4.)
\nnpm run req, the AGENTS.md digest).docs/workflow-arrows.puml — start from the empty skeleton, not from a full map.scripts/tooling/workflow-map/workflow-arrows-lint.mjs and the SVG injector\nworkflow-arrows-svg.mjs; wire the npm scripts in §6.8.req-coverage.js with the flow-impact hook (§6.4) and export PROCESSES from the linter\n(one truth for the palette).AGENTS/workflow-arrows.md (§6.5) and the digest sections in AGENTS.md\n(§6.6); add the flow subsection to AGENTS/requirements.md (§6.7).tests/unit/workflow-arrows.test.js and run npm test.npm run workflow-arrows:lint exits 0 (silent) on the starter map.Everything below is copied verbatim from the working repository, except where a note says otherwise\n(the palette, drawer list and PREFIX are the author's; the legacy digest is a placeholder). Fenced\nblocks use four backticks where the inlined file itself contains code fences.
\ndocs/workflow-arrows.pumlThe worked example: a real, linted map. Read it as the demonstration of §2, not as your map. It has\none @startuml, drawers as package blocks, bricks with the label grammar, the numbered flow grouped\nby process colour, a legend, and an @lint-ignore block with two guarded masks.
@startuml\n' workflow-arrows — the linted map of kodavr's code tree and the numbered flow.\n' How to read / maintain / lint / render: AGENTS/workflow-arrows.md.\n' Never edit the .svg. scripts/tooling/workflow-map/workflow-arrows-lint.mjs fails on any drift:\n' drawers, file coverage of code dirs, links, symbols, stereotypes, step numbers.\n!pragma layout smetana\n' Hover colour source (PlantUML native, QA-5453). The whole-arrow highlight + linger\n' is injected into the rendered .svg by `npm run workflow-arrows:svg`; visible only in a\n' browser, never in PNG/IDE preview. See AGENTS/workflow-arrows.md.\nskinparam pathHoverColor #C62828\nskinparam backgroundColor #FFFFFF\nskinparam shadowing false\nskinparam componentStyle rectangle\nskinparam packageStyle rectangle\nskinparam linetype ortho\nskinparam ArrowFontSize 12\nskinparam ArrowFontColor #263238\nskinparam DefaultFontSize 12\nskinparam nodesep 18\nskinparam ranksep 28\n' Stereotype themes: one per drawer; <<ext>> is reserved for external actors/systems.\nskinparam component {\n BackgroundColor<<ext>> #FAFAFA\n BorderColor<<ext>> #9E9E9E\n BackgroundColor<<lib>> #E3F2FD\n BorderColor<<lib>> #1E88E5\n BackgroundColor<<cli>> #FFF3E0\n BorderColor<<cli>> #FB8C00\n BackgroundColor<<audit>> #FFF8E1\n BorderColor<<audit>> #F9A825\n BackgroundColor<<ctrl>> #E8F5E9\n BorderColor<<ctrl>> #43A047\n BackgroundColor<<view>> #EDE7F6\n BorderColor<<view>> #7E57C2\n BackgroundColor<<asset>> #FCE4EC\n BorderColor<<asset>> #D81B60\n BackgroundColor<<content>> #E0F2F1\n BorderColor<<content>> #00897B\n}\nleft to right direction\n\ntitle kodavr — drawers, bricks and the numbered flow (number · callee method · why)\n\n' ── externals ──────────────────────────────────────────────────────────────────\nactor \"Author\\n(opening a PR)\" as AUTHOR\nactor \"AI agent\\n(the reader)\" as AGENT\nactor \"Human\\n(a visitor)\" as HUMAN\nactor \"Maintainer\\n(merging a PR)\" as MAINTAINER\nactor \"Developer\\n(local tools)\" as DEVELOPER\ncomponent \"Ignition engine\\nvendor/ignition-ssg\\nHandlebars SSG: input/ + data → output/public\" as ENGINE <<ext>>\n' GitHub = Actions (the workflows) + Pages (the served artifact). Drawn as a\n' rectangle, not a package: a package would read as a first-party drawer.\nrectangle \"GitHub\" as GH {\n component \"Pages\\nserves output/public at kodavr.xyz\" as GH_PAGES <<ext>>\n component \"validate.yml\\nPR + push main\\nnpm ci · validate · test · contract · arrows-lint\" as WF_VALIDATE <<ext>>\n component \"deploy.yml\\npush main\\nvalidate · build → upload-pages-artifact → Pages\" as WF_DEPLOY <<ext>>\n component \"audit.yml\\npull_request (same-repo)\\nvalidate + the advisory audit (model key = a repo secret)\" as WF_AUDIT <<ext>>\n component \"dump-manifest.yml\\npull_request (same-repo)\\nposts the sticky manifest card\" as WF_MANIFEST <<ext>>\n component \"publish-telegram.yml\\nworkflow_run ⇐ deploy (success)\\nmirrors newly published dumps\" as WF_TG <<ext>>\n}\ncomponent \"Playwright (dev)\\nrasterizes the OG card and the touch icon\" as PW <<ext>>\n\n' ── drawers ────────────────────────────────────────────────────────────────────\npackage \"scripts/lib\\nthe smart controller: content, machine contracts, build steps\" as P_LIB {\n component \"build.mjs\\nthe one build pipeline (controller)\\n--\\nbuildProject\" as BUILD <<lib>> [[../scripts/lib/build.mjs#buildProject]]\n component \"dumps.mjs\\ncontent/dumps/* → engine datasets\\n--\\nreadDumps · toDataset\" as DUMPS <<lib>> [[../scripts/lib/dumps.mjs#readDumps]]\n component \"markdown.mjs\\nmarkdown → sanitized HTML\\n--\\nrenderMarkdown\" as MD <<lib>> [[../scripts/lib/markdown.mjs#renderMarkdown]]\n component \"pages.mjs\\nroute datasets: copydeck, SEO, JSON-LD\\n--\\nbuildRouteDatasets · buildNav\" as PAGES <<lib>> [[../scripts/lib/pages.mjs#buildRouteDatasets]]\n component \"copy.mjs\\nsingle source of truth for every human string\" as COPY <<lib>> [[../scripts/lib/copy.mjs]]\n component \"i18n-en.mjs\\nEnglish bundle: copydeck keys, values referenced verbatim\" as I18N_EN <<lib>> [[../scripts/lib/i18n-en.mjs]]\n component \"i18n-ru.mjs\\nRussian bundle: a draft translation of every copydeck key\" as I18N_RU <<lib>> [[../scripts/lib/i18n-ru.mjs]]\n component \"i18n-zh-Hans.mjs\\nSimplified Chinese bundle: a draft translation of every copydeck key\" as I18N_ZH <<lib>> [[../scripts/lib/i18n-zh-Hans.mjs]]\n component \"i18n-es.mjs\\nSpanish bundle: a draft translation of every copydeck key\" as I18N_ES <<lib>> [[../scripts/lib/i18n-es.mjs]]\n component \"i18n.mjs\\nthe locale registry and the loud keyed translator\\n--\\nLOCALES · t · assertComplete\" as I18N <<lib>> [[../scripts/lib/i18n.mjs#t]]\n component \"jsonld.mjs\\nsafe schema.org @graph per page\\n--\\nserializeJsonLd\" as JSONLD <<lib>> [[../scripts/lib/jsonld.mjs#serializeJsonLd]]\n component \"machine.mjs\\nindex.json, schemas, well-known, feeds, tags, sitemap\\n--\\nwriteMachineFiles · writeSitemap\" as MACHINE <<lib>> [[../scripts/lib/machine.mjs#writeMachineFiles]]\n component \"schema.mjs\\nself-describing JSON Schemas for index/manifest\\n--\\nbuildIndexSchema · buildManifestSchema\" as SCHEMA <<lib>> [[../scripts/lib/schema.mjs#buildIndexSchema]]\n component \"ignition.mjs\\nspawns the vendored engine\\n--\\nrunIgnition\" as IGN <<lib>> [[../scripts/lib/ignition.mjs#runIgnition]]\n component \"relativize.mjs\\nhost-agnostic internal links\\n--\\nrelativizeSite\" as REL <<lib>> [[../scripts/lib/relativize.mjs#relativizeSite]]\n component \"verbatim.mjs\\nverbatim robots/humans\\n--\\nROBOTS_TXT · HUMANS_TXT\" as VERB <<lib>> [[../scripts/lib/verbatim.mjs]]\n component \"static-server.mjs\\nlocal preview server\\n--\\ncreateStaticServer\" as SSRV <<lib>> [[../scripts/lib/static-server.mjs#createStaticServer]]\n component \"manifest-card.mjs\\nmanifest.json → the PR reviewer's card\\n--\\nrenderManifestCard\" as MCARD <<lib>> [[../scripts/lib/manifest-card.mjs#renderManifestCard]]\n component \"telegram-mirror.mjs\\nmanifest + brief → a Telegram mirror post\\n--\\nrenderMirrorPost\" as TGMIRROR <<lib>> [[../scripts/lib/telegram-mirror.mjs#renderMirrorPost]]\n}\n\npackage \"scripts/product\\nthe product processes: site build, PR review, telegram, brand media\" as P_PRODUCT {\n package \"scripts/product/site-build\\nthe one build pipeline's entry point\" as P_SITE {\n component \"build.mjs\\nnpm run build → output/public\" as CLI_BUILD <<cli>> [[../scripts/product/site-build/build.mjs]]\n }\n package \"scripts/product/pr-review\\nthe PR surface: the manifest card and the audit entry points\" as P_PR {\n component \"pr-manifest-card.mjs\\nposts the sticky manifest card on a PR\" as CLI_CARD <<cli>> [[../scripts/product/pr-review/pr-manifest-card.mjs]]\n component \"pr.mjs\\nposts the advisory PR audit comment and status\" as CLI_AUDIT <<cli>> [[../scripts/product/pr-review/pr.mjs]]\n component \"local.mjs\\nruns the audit pipeline over our own dumps (npm run audit:local)\" as CLI_AUDIT_LOCAL <<cli>> [[../scripts/product/pr-review/local.mjs]]\n component \"judge.mjs\\nruns the Layer-4 judge over our own dumps (npm run audit:judge)\" as CLI_AUDIT_JUDGE <<cli>> [[../scripts/product/pr-review/judge.mjs]]\n }\n package \"scripts/product/pr-review/audit\\nthe deterministic audit engine: envelope → detectors → policy → report\" as P_AUDIT {\n component \"channel.mjs\\nchannel output schema + allowlist validator\\n--\\nmakeSpan · validateChannelResult\" as AUDIT_CH <<audit>> [[../scripts/product/pr-review/audit/channel.mjs#validateChannelResult]]\n component \"detectors.mjs\\nLayer-1 structural detectors (invisible, base64, homoglyph, hidden)\\n--\\nstructuralChannel\" as AUDIT_DET <<audit>> [[../scripts/product/pr-review/audit/detectors.mjs#structuralChannel]]\n component \"forensic.mjs\\nconverged top-N span map for the human\\n--\\nbuildForensicMap\" as AUDIT_FOR <<audit>> [[../scripts/product/pr-review/audit/forensic.mjs#buildForensicMap]]\n component \"policy.mjs\\ndeterministic envelope + channels -> decision\\n--\\nevaluatePolicy\" as AUDIT_POL <<audit>> [[../scripts/product/pr-review/audit/policy.mjs#evaluatePolicy]]\n component \"envelope.mjs\\nLayer-0 envelope: diff shape + author signals (no content text)\\n--\\ncheckDiffShape · evaluateEnvelope\" as AUDIT_ENV <<audit>> [[../scripts/product/pr-review/audit/envelope.mjs#evaluateEnvelope]]\n component \"report.mjs\\nadvisory PR comment: forensic map, no scores, escaped\\n--\\nrenderAuditComment\" as AUDIT_REP <<audit>> [[../scripts/product/pr-review/audit/report.mjs#renderAuditComment]]\n component \"pr.mjs\\nPR audit orchestration: API inputs -> envelope + policy (shadow)\\n--\\nrunAudit\" as AUDIT_PR <<audit>> [[../scripts/product/pr-review/audit/pr.mjs#runAudit]]\n component \"local.mjs\\nlocal harness: our own dumps -> the pipeline's verdicts\\n--\\ndumpToPr · auditDumps\" as AUDIT_LOCAL <<audit>> [[../scripts/product/pr-review/audit/local.mjs#dumpToPr]]\n }\n package \"scripts/product/pr-review/audit/llm\\nthe LLM audit layers: judge, trace/meta, channel composition\" as P_AUDIT_LLM {\n component \"llm.mjs\\nthe LLM provider client: credentials + one strict-JSON call\\n--\\nproviderFromAuth · callAuditLLM\" as AUDIT_LLM <<audit>> [[../scripts/product/pr-review/audit/llm/llm.mjs#callAuditLLM]]\n component \"judge.mjs\\nLayer-4 LLM judge: data frame, allowlist schema, ensemble\\n--\\nframeContent · judgeChannel\" as AUDIT_JUDGE <<audit>> [[../scripts/product/pr-review/audit/llm/judge.mjs#judgeChannel]]\n component \"trace.mjs\\nLayer-5 deterministic residue classifier + non-LLM quote-masker\\n--\\ndetectTraceResidue · quoteMask\" as AUDIT_TRACE <<audit>> [[../scripts/product/pr-review/audit/llm/trace.mjs#detectTraceResidue]]\n component \"meta.mjs\\nLayer-5 LLM meta-reviewer over a quote-masked trace (witness channel)\\n--\\nbuildMetaMessages · metaReviewChannel\" as AUDIT_META <<audit>> [[../scripts/product/pr-review/audit/llm/meta.mjs#metaReviewChannel]]\n component \"llm-channels.mjs\\ncompose the LLM channels: judge + ensemble + trace/meta, degrade visibly\\n--\\nbuildLlmChannels\" as AUDIT_LLM_CH <<audit>> [[../scripts/product/pr-review/audit/llm/llm-channels.mjs#buildLlmChannels]]\n }\n package \"scripts/product/telegram\\nthe Telegram mirror entry point\" as P_TG {\n component \"telegram-mirror.mjs\\nmirrors newly published dumps to Telegram\" as CLI_TGMIRROR <<cli>> [[../scripts/product/telegram/telegram-mirror.mjs]]\n }\n package \"scripts/product/brand-media\\nthe brand-image generators (OG card, touch icon)\" as P_MEDIA {\n component \"generate-og-image.mjs\\nrasterizes the OG card\" as CLI_OG <<cli>> [[../scripts/product/brand-media/generate-og-image.mjs]]\n component \"generate-touch-icon.mjs\\nrasterizes the touch icon\" as CLI_TI <<cli>> [[../scripts/product/brand-media/generate-touch-icon.mjs]]\n }\n}\n\npackage \"scripts/tooling\\nthe development tooling: quality gates, the map, dev tools\" as P_TOOLING {\n package \"scripts/tooling/quality-gates\\nthe CI gates: content validation, requirements, contracts\" as P_GATES {\n component \"validate.mjs\\nKDV-CI gate over content/dumps\\n--\\nvalidateContent · validateManifest\" as CLI_VAL <<cli>> [[../scripts/tooling/quality-gates/validate.mjs#validateContent]]\n component \"req-coverage.js\\nreconcile tests ↔ REQUIREMENTS.md\" as CLI_REQ <<cli>> [[../scripts/tooling/quality-gates/req-coverage.js]]\n component \"contract.mjs\\nguards the module index (contract headers)\\n--\\nvalidateAll\" as CLI_CONTRACT <<cli>> [[../scripts/tooling/quality-gates/contract.mjs#validateAll]]\n }\n package \"scripts/tooling/workflow-map\\nthe map itself: its drift alarm and hover injection\" as P_MAP {\n component \"workflow-arrows-lint.mjs\\nthis map's drift alarm\\n--\\nlintDiagram\" as CLI_LINT <<cli>> [[../scripts/tooling/workflow-map/workflow-arrows-lint.mjs#lintDiagram]]\n component \"workflow-arrows-svg.mjs\\nadds the map's hover block\\n--\\ninjectHover\" as CLI_SVGHOVER <<cli>> [[../scripts/tooling/workflow-map/workflow-arrows-svg.mjs#injectHover]]\n }\n package \"scripts/tooling/dev-tools\\nlocal developer conveniences\" as P_DEV {\n component \"serve.mjs\\nlocal static server\" as CLI_SERVE <<cli>> [[../scripts/tooling/dev-tools/serve.mjs]]\n component \"state-diet.mjs\\nSTATE.md chronicle → docs/history\" as CLI_DIET <<cli>> [[../scripts/tooling/dev-tools/state-diet.mjs]]\n }\n}\n\npackage \"input/controllers\\nclient controllers injected by the engine\" as P_CTRL {\n component \"dumps.js\\nthe gate, the hall, the reception toggle\" as CTRL_DUMPS <<ctrl>> [[../input/controllers/dumps.js]]\n component \"reception.js\\nthe reception page behaviour\" as CTRL_REC <<ctrl>> [[../input/controllers/reception.js]]\n}\n\npackage \"input/templates\\nHandlebars layouts + partials (the HTML projection)\" as P_VIEW {\n component \"home.hbs · about.hbs · dumps.hbs\\nreception.hbs · contribute.hbs\\nthe human-surface layouts\" as VIEW_PAGES <<view>> [[../input/templates/home.hbs]]\n component \"site/gate.hbs · site/reception-block.hbs\\nthe consumption-contract partials\" as VIEW_GATE <<view>> [[../input/templates/site/gate.hbs]]\n}\n\npackage \"static/assets\\nstylesheet, client JS and brand assets\" as P_ASSET {\n component \"styles.css · site.js\\nstyling + the copy-button behaviour\" as ASSET <<asset>> [[../static/assets/styles.css]]\n component \"logo.svg · og-default.png\\ntouch-icon-192.png\\nthe wordmark and social/touch images\" as ASSET_IMG <<asset>> [[../static/logo.svg]]\n}\n\npackage \"content/dumps\\nthe dumps themselves: manifest.json + raw.md per slug\" as P_CONTENT {\n component \"2026-09-14-kodavr-manifesto/\\nmanifest.json + raw.md\\nthe launch dump: demo + platform manifesto\" as DUMP1 <<content>> [[../content/dumps/2026-09-14-kodavr-manifesto/manifest.json]]\n}\n\n' ── flow ───────────────────────────────────────────────────────────────────────\n' One arrow colour = one business process; N = global step order 1 to 37. The five\n' processes run in dependency order (prerequisites first): PR review (teal, 1-9),\n' Publish (blue, 10-25), Notify (purple, 26-27), Consume (green, 28-30),\n' Engineering (brown, 31-37); grey #9E9E9E is structural glue, never a numbered step.\n\n' ── rank 1 — PR review (#00897B): a dump arrives as a validated PR.\nAUTHOR -[#00897B]-> WF_VALIDATE : 1 · validate.yml\\nPR opens → the validate workflow\nWF_VALIDATE -[#00897B]-> CLI_VAL : [[../scripts/tooling/quality-gates/validate.mjs#validateContent 2 · validateContent()]]\\nthe content gate\nWF_VALIDATE -[#00897B]-> CLI_CONTRACT : [[../scripts/tooling/quality-gates/contract.mjs#validateAll 3 · validateAll()]]\\nthe module-index gate\nWF_VALIDATE -[#00897B]-> CLI_LINT : [[../scripts/tooling/workflow-map/workflow-arrows-lint.mjs#lintDiagram 4 · lintDiagram()]]\\nthe map-drift gate\nWF_VALIDATE -[#00897B]-> CLI_REQ : [[../scripts/tooling/quality-gates/req-coverage.js 5 · req-coverage]]\\ntests ↔ requirements\nAUTHOR -[#00897B]-> WF_AUDIT : 6 · audit.yml\\nthe same PR → the audit workflow\nWF_AUDIT -[#00897B]-> CLI_AUDIT : [[../scripts/product/pr-review/pr.mjs 7 · pr.mjs]]\\nthe advisory audit\nAUTHOR -[#00897B]-> WF_MANIFEST : 8 · dump-manifest.yml\\nthe same PR → the card workflow\nWF_MANIFEST -[#00897B]-> CLI_CARD : [[../scripts/product/pr-review/pr-manifest-card.mjs 9 · pr-manifest-card.mjs]]\\nthe sticky manifest card\n\n' The advisory audit's internal wiring (dashed, unnumbered, same process).\nCLI_AUDIT -[#00897B]..> AUDIT_PR : fetches the diff + author signals via the API\\nand runs the deterministic audit\nCLI_AUDIT -[#00897B]..> AUDIT_LLM_CH : builds the LLM channels from env\\nand passes them to the pure audit\nAUDIT_PR -[#00897B]..> AUDIT_ENV : builds the Layer-0 envelope from the diff shape\nAUDIT_PR -[#00897B]..> AUDIT_DET : scans the API patch with the Layer-1 detectors\nAUDIT_PR -[#00897B]..> AUDIT_POL : reduces envelope + channels to a recommendation\nAUDIT_PR -[#00897B]..> AUDIT_REP : renders the advisory comment (marker, no scores)\nAUDIT_ENV -[#00897B]..> AUDIT_POL : the envelope feeds the decision\nAUDIT_POL -[#00897B]..> AUDIT_CH : evaluates every channel's result\nAUDIT_POL -[#00897B]..> AUDIT_FOR : requests the forensic map for the human\nAUDIT_DET -[#00897B]..> AUDIT_CH : each detector emits a channel result\nAUDIT_LLM_CH -[#00897B]..> AUDIT_LLM : resolves the provider from env\\nand retries transient errors\nAUDIT_LLM_CH -[#00897B]..> AUDIT_JUDGE : runs the judge, plus a second run for the ensemble\nAUDIT_LLM_CH -[#00897B]..> AUDIT_TRACE : reads the primary run's reasoning trace deterministically\nAUDIT_LLM_CH -[#00897B]..> AUDIT_META : and asks the meta-reviewer over the masked trace\nAUDIT_JUDGE -[#00897B]..> AUDIT_LLM : one strict-JSON chat call per judge run\nAUDIT_JUDGE -[#00897B]..> AUDIT_CH : normalizes the judge verdict into a channel result\nCLI_CARD -[#00897B]..> MCARD : renders content/dumps/<slug>/manifest.json\n\n' ── rank 2 — Publish (#1E88E5): build → engine → artifact.\nMAINTAINER -[#1E88E5]-> WF_DEPLOY : 10 · deploy.yml\\nmerge to main\nWF_DEPLOY -[#1E88E5]-> CLI_VAL : [[../scripts/tooling/quality-gates/validate.mjs#validateContent 11 · validateContent()]]\\nthe same gate before the build\nWF_DEPLOY -[#1E88E5]-> CLI_BUILD : [[../scripts/product/site-build/build.mjs 12 · build.mjs]]\\nnpm run build\nCLI_BUILD -[#1E88E5]-> BUILD : [[../scripts/lib/build.mjs#buildProject 13 · buildProject()]]\\nthe one build pipeline (controller)\nBUILD -[#1E88E5]-> DUMPS : [[../scripts/lib/dumps.mjs#readDumps 14 · readDumps()]]\\nread every content/dumps/*\nBUILD -[#1E88E5]-> DUMPS : [[../scripts/lib/dumps.mjs#toDataset 15 · toDataset()]]\\nmerge the manifest, turn the body into HTML\nDUMPS -[#1E88E5]-> MD : [[../scripts/lib/markdown.mjs#renderMarkdown 16 · renderMarkdown()]]\\nsanitize before markdown becomes HTML\nBUILD -[#1E88E5]-> PAGES : [[../scripts/lib/pages.mjs#buildRouteDatasets 17 · buildRouteDatasets()]]\\nassemble every route's dataset\nPAGES -[#1E88E5]-> I18N_EN : [[../scripts/lib/i18n-en.mjs#EN 18 · EN — the English copydeck]]\\nthe copydeck source: i18n-en re-exports copy.mjs\nPAGES -[#1E88E5]-> JSONLD : [[../scripts/lib/jsonld.mjs#serializeJsonLd 19 · serializeJsonLd()]]\\nper-page schema.org @graph\nBUILD -[#1E88E5]-> IGN : [[../scripts/lib/ignition.mjs#runIgnition 20 · runIgnition()]]\\nhand input/ + data to the engine\nIGN -[#1E88E5]-> ENGINE : 21 · engine build\\nthe SSG renders output/public\nBUILD -[#1E88E5]-> REL : [[../scripts/lib/relativize.mjs#relativizeSite 22 · relativizeSite()]]\\nrewrite internal links per page depth\nBUILD -[#1E88E5]-> MACHINE : [[../scripts/lib/machine.mjs#writeMachineFiles 23 · writeMachineFiles()]]\\nindex.json, well-known, feeds, tags\nBUILD -[#1E88E5]-> MACHINE : [[../scripts/lib/machine.mjs#writeSitemap 24 · writeSitemap()]]\\nsitemap.xml over the pretty URLs\nMACHINE -[#1E88E5]..> GH_PAGES : 25 ⟵ output/public\\nthe artifact GitHub Pages serves\n\n' ── rank 3 — Notify (#8E24AA): mirror / card posts on completion.\nWF_DEPLOY -[#8E24AA]-> WF_TG : 26 · publish-telegram.yml\\non completion (workflow_run) → mirror newly published dumps\nWF_TG -[#8E24AA]-> CLI_TGMIRROR : [[../scripts/product/telegram/telegram-mirror.mjs 27 · telegram-mirror.mjs]]\\nmirror newly published dumps\nCLI_TGMIRROR -[#8E24AA]..> TGMIRROR : renders the mirror post from manifest + brief\n\n' ── rank 4 — Consume (#43A047): machine + human reads.\nAGENT -[#43A047]-> MACHINE : [[../scripts/lib/machine.mjs 28 · GET /index.json]]\\nthe agent picks dumps by field\nAGENT -[#43A047]-> DUMP1 : [[../content/dumps/2026-09-14-kodavr-manifesto/manifest.json 29 · manifest.json + raw]]\\nfetch the contract and the body\nHUMAN -[#43A047]-> CTRL_DUMPS : [[../input/controllers/dumps.js 30 · dumps.js]]\\ncheck in, or hand the dump to an agent\n\n' ── rank 5 — Engineering (#6D4C41): local dev / tooling.\nDEVELOPER -[#6D4C41]-> CLI_SERVE : [[../scripts/tooling/dev-tools/serve.mjs 31 · serve.mjs]]\\nnpm run serve\nDEVELOPER -[#6D4C41]-> CLI_DIET : [[../scripts/tooling/dev-tools/state-diet.mjs 32 · state-diet.mjs]]\\nnpm run state:diet\nDEVELOPER -[#6D4C41]-> CLI_OG : [[../scripts/product/brand-media/generate-og-image.mjs 33 · generate-og-image.mjs]]\\nnpm run og-image\nDEVELOPER -[#6D4C41]-> CLI_TI : [[../scripts/product/brand-media/generate-touch-icon.mjs 34 · generate-touch-icon.mjs]]\\nnpm run touch-icon\nDEVELOPER -[#6D4C41]-> CLI_AUDIT_LOCAL : [[../scripts/product/pr-review/local.mjs 35 · local.mjs]]\\nnpm run audit:local\nDEVELOPER -[#6D4C41]-> CLI_AUDIT_JUDGE : [[../scripts/product/pr-review/judge.mjs 36 · judge.mjs]]\\nnpm run audit:judge\nDEVELOPER -[#6D4C41]-> CLI_SVGHOVER : [[../scripts/tooling/workflow-map/workflow-arrows-svg.mjs#injectHover 37 · injectHover()]]\\nnpm run workflow-arrows:svg\nCLI_SERVE -[#6D4C41]..> SSRV : serves output/public locally\nCLI_OG -[#6D4C41]..> PW : rasterizes the OG card\nCLI_TI -[#6D4C41]..> PW : rasterizes the touch icon\nCLI_AUDIT_LOCAL -[#6D4C41]..> AUDIT_LOCAL : reads content/dumps/* locally\\nand prints what the pipeline says\nCLI_AUDIT_JUDGE -[#6D4C41]..> AUDIT_JUDGE : frames our own dumps as data\\nand runs the Layer-4 judge locally\nCLI_AUDIT_JUDGE -[#6D4C41]..> AUDIT_LLM : resolves the provider from env, auth or a work-flow config\\n(never a hardcoded key)\n\n' Structural edges (dashed, unnumbered, grey #9E9E9E): imports, assets and glue —\n' the things that anchor every remaining brick to the flow (no orphans).\nBUILD -[#9E9E9E]..> ASSET : publishes static/ into the artifact\nBUILD -[#9E9E9E]..> ASSET_IMG : and the brand images\nIGN -[#9E9E9E]..> VIEW_PAGES : the engine renders the layouts\nIGN -[#9E9E9E]..> VIEW_GATE : and the consumption-contract partials\nIGN -[#9E9E9E]..> CTRL_DUMPS : injects the page controller\nIGN -[#9E9E9E]..> CTRL_REC : injects the reception controller\nPAGES -[#9E9E9E]..> MACHINE : reads buildIndexEntry / buildWellKnown\nMACHINE -[#9E9E9E]..> SCHEMA : embeds + serves the index/manifest JSON Schemas\nMACHINE -[#9E9E9E]..> VERB : writes robots.txt / humans.txt verbatim\nBUILD -[#9E9E9E]..> I18N : assembles the copydeck + locale bundles\nI18N -[#9E9E9E]..> I18N_EN : English: the source bundle\nI18N -[#9E9E9E]..> I18N_RU : Russian: a draft translation\nI18N -[#9E9E9E]..> I18N_ZH : Simplified Chinese: a draft translation\nI18N -[#9E9E9E]..> I18N_ES : Spanish: a draft translation\nI18N_EN -[#9E9E9E]..> COPY : re-exports the copydeck (the single source)\n\nlegend right\n **how to read an arrow**\n line 1 (colored link): N · callee.method() — the API method\n of the TARGET brick this arrow calls (the callee), N = global order 1 to 37\n line 2 (plain text): why the call happens (business intent)\n solid = call · dashed = return · dashed to an actor = a push\n click a brick → its file · click a call → the method's source\n each brick: name → what it does → -- → members\n **colour = business process**: teal #00897B PR review (rank 1)\n blue #1E88E5 Publish (2) · purple #8E24AA Notify (3)\n green #43A047 Consume (4) · brown #6D4C41 Engineering (5)\n grey #9E9E9E = structural glue (imports/assets), never a numbered step\n **drawers** = first-party code dirs; the code drawers are covered\n file-by-file (scripts/lib, scripts/product/**, scripts/tooling/**, input/controllers)\n **linted idioms** (workflow-arrows-lint): a brick's stereotype =\n its drawer; every numbered call links the callee method,\n returns carry no link; step numbers are exactly 1..N grouped by rank\n steps are grouped by process in dependency order (prerequisites first);\n every brick is reachable from an actor (no orphans)\nendlegend\n\n' ── lint suppressions ─────────────────────────────────────────────────────────\n' The ignition engine injects the client controllers by path, never by import.\n' @lint-ignore\n' [I] IGN -> CTRL_DUMPS # by-path: the controller is spawned by path, not imported\n' [I] IGN -> CTRL_REC # by-path: the controller is spawned by path, not imported\n' @end\n\n@enduml\nscripts/tooling/workflow-map/workflow-arrows-lint.mjsThe utility at the centre of the setup: palette, DRAWERS, checks A–H, P1–P3, I, J, M, the\n@lint-ignore parser, and a CLI that prints suppressed N and exits non-zero on unsuppressed drift.\nIt exports PROCESSES, MASKABLE_CODES, lintDiagram, lintProblems and the helpers the tests use.
#!/usr/bin/env node\n/**\n * CONTRACT: scripts/tooling/workflow-map/workflow-arrows-lint.mjs\n * ROLE: the drift alarm for docs/workflow-arrows.puml against the code tree\n * EXPORTS:\n * DRIFT_GUIDANCE — the guidance printed before the DRIFT lines\n * MASKABLE_CODES — the codes an @lint-ignore mask may suppress (I, P1–P3)\n * PROCESSES — the 5 business processes: colour = process, rank = global step order\n * STRUCTURAL_COLOR — the grey used by imports/assets/glue, never a numbered step\n * actorAliases — the Set of actor aliases declared in the diagram\n * bricks — the diagram's component bricks with their drawer and link\n * declaredDrawers — the drawer paths declared in the diagram\n * formatProblem — render a structured problem as \"CODE: subject — message\"\n * lintDiagram — the pure linter over the diagram text (formatted strings)\n * lintProblems — the structured linter: { problems, suppressed, ignoreErrors }\n * main — the CLI entry point\n * missingScriptDrawers — dirs under scripts/ (recursively) not declared drawers\n * parseArrows — every arrow line as { source, target, operator, color, label }\n * parseLinks — every [[url]] with its file and #symbol\n * symbolDeclared — true when a #symbol is declared or called in a file\n * CONSUMES:\n * node:fs — read the diagram and the linked files\n * node:path — resolve links and the trees\n * node:url — find the repo root and detect the entry point\n * INVARIANTS:\n * — a red lint names the drift and exits 1; it is never weakened to pass\n */\n\n// workflow-arrows-lint — linter for docs/workflow-arrows.puml (kodavr).\n//\n// The diagram is a hand-drawn map of kodavr's code tree:\n// * drawer blocks — package \"<dir>\\n<why>\" for each first-party code dir;\n// * module bricks — component \"<file>\\n<meaning>\\n--\\n<members>\" as X <<st>> [[<link>]];\n// one grammar (J): NAME → business meaning → `--` → members; the `--` only\n// when members exist, and a linked #symbol must be one of the members;\n// * a numbered flow — labels `N · call` (with a link) / `N ⟵ return` (no link).\n// Everything in it points at real things; the linter is the drift alarm:\n//\n// (A) drawer coverage both ways — declared drawers vs the configured first-party dirs\n// (B) file coverage both ways for code drawers — every file is a brick, every\n// brick link exists, and no file is drawn twice\n// (C) every [[url]] resolves to an existing file (relative to docs/)\n// (D) a link's #symbol is declared in the target file\n// (E) the flow's step numbers are exactly 1..N, unique and contiguous\n// (F) a brick's stereotype equals its drawer's stereotype\n// (G) T3 idiom — a numbered call to a module brick carries a [[file#symbol]]\n// link; a numbered return carries none\n// (H) every directory under scripts/ (recursively) is a declared drawer, so a\n// new role subfolder or nested process folder cannot be added without\n// drawing it (KDV-STRUCT-09)\n// (I) a drawn edge between two MODULE bricks is a real import in one direction:\n// a by-path spawn (the engine injects the controllers) or a stale map edge\n// is drift; non-modules (.css/.svg/.png/.hbs/...) and unresolved links are\n// other checks' business (KDV-CI-24)\n// (J) every brick/drawer label follows one grammar — NAME, then the business\n// meaning, then `--` and the members (`--` only when members exist):\n// members never sit above the line, a `--` needs a meaning above it and\n// members below it, and a linked #symbol must be one of the members\n// (KDV-CI-26)\n// (P1) every arrow carries a process colour from the palette (or the structural\n// grey) — the colour names the business process\n// (P2) a numbered step carries a process colour (never the structural grey) and\n// the process rank is non-decreasing in draw order: steps grouped by process\n// (P3) every non-exempt brick is reachable from an actor by the drawn arrows\n// (dashed included): no orphan bricks\n// (M) the @lint-ignore block itself is well-formed: a mask may target ONLY a\n// cheap-validation code (I, P1–P3), must cite a reason mechanism\n// (by-path|dynamic|transitive|non-module), and must actually match a\n// problem — an unused, unreasoned or structural-targeting mask is drift\n//\n// Suppression — a mask is proof of a false positive, never a way to hide a\n// structural gap. The block lives in the same puml text:\n// ' @lint-ignore\n// ' [I] IGN -> CTRL_DUMPS # by-path: spawned by path, not imported\n// ' [P1] arrow * # transitive: the glue arrow elides the chain\n// ' @end\n// A `'`-line without `[CODE]` is a plain comment. The glob matches the problem\n// key \"CODE: subject\" gitignore-style: `*` any run, `?` one char, `!` un-ignores\n// keys matched earlier (last match wins). Structural codes (A–H, M) are never\n// suppressible.\n//\n// lintDiagram() is pure over `text`; it reads the filesystem only to resolve\n// links and list drawer files. An empty array means clean. The CLI exits 1 on\n// any problem and stays silent when the diagram is clean.\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport { fileURLToPath, pathToFileURL } from 'node:url';\n\nconst ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');\nconst DEFAULT_PUML = path.join(ROOT, 'docs', 'workflow-arrows.puml');\n\n// The first-party code drawers. A drawer is a directory block in the map.\n// `cover: 'files'` (with `ext`) → every matching file must appear as exactly one\n// brick, and every brick link must point at a file in that drawer.\n// `cover: 'dir'` → the folder is declared/checked, bricks are illustrative.\nconst DRAWERS = [\n { path: 'scripts/lib', st: 'lib', ext: ['.mjs'], cover: 'files' },\n { path: 'scripts/product', st: 'pack', ext: [], cover: 'dir' },\n { path: 'scripts/product/site-build', st: 'cli', ext: ['.mjs'], cover: 'files' },\n { path: 'scripts/product/pr-review', st: 'cli', ext: ['.mjs'], cover: 'files' },\n { path: 'scripts/product/pr-review/audit', st: 'audit', ext: ['.mjs'], cover: 'files' },\n { path: 'scripts/product/pr-review/audit/llm', st: 'audit', ext: ['.mjs'], cover: 'files' },\n { path: 'scripts/product/telegram', st: 'cli', ext: ['.mjs'], cover: 'files' },\n { path: 'scripts/product/brand-media', st: 'cli', ext: ['.mjs'], cover: 'files' },\n { path: 'scripts/tooling', st: 'pack', ext: [], cover: 'dir' },\n { path: 'scripts/tooling/quality-gates', st: 'cli', ext: ['.mjs', '.js'], cover: 'files' },\n { path: 'scripts/tooling/workflow-map', st: 'cli', ext: ['.mjs'], cover: 'files' },\n { path: 'scripts/tooling/dev-tools', st: 'cli', ext: ['.mjs'], cover: 'files' },\n { path: 'input/controllers', st: 'ctrl', ext: ['.js'], cover: 'files' },\n { path: 'input/templates', st: 'view', ext: ['.hbs'], cover: 'dir' },\n { path: 'static/assets', st: 'asset', ext: [], cover: 'dir' },\n { path: 'content/dumps', st: 'content', ext: [], cover: 'dir' },\n];\n\n// A link carries a scheme when it is not a repo-relative file reference.\nconst SCHEME = /^(?:www\\.|https?:|mailto:|about:)/i;\n// Stereotypes that are not a drawer theme: external actors/systems and packs.\nconst EXEMPT_STEREOTYPES = new Set(['ext', 'pack', 'p_pack']);\n\n// The member-line grammar (KDV-CI-26): identifier-only symbols, ` · `-separated,\n// each with an optional `()`. A file list (`home.hbs · about.hbs`) or prose is\n// NOT a member line — the dot/space rules them out.\nconst MEMBER_LINE = /^[A-Za-z_$][\\w$]*(\\(\\))?(?: · [A-Za-z_$][\\w$]*(\\(\\))?)*$/;\n\n// The business processes: the arrow COLOUR names the process and the RANK fixes\n// the global step order — all rank-1 steps precede rank-2, and so on (P1/P2).\n// One truth: this table is the palette the linter and the diagram share.\nexport const PROCESSES = [\n { name: 'PR review', rank: 1, color: '#00897B' }, // teal\n { name: 'Publish', rank: 2, color: '#1E88E5' }, // blue\n { name: 'Notify', rank: 3, color: '#8E24AA' }, // purple\n { name: 'Consume', rank: 4, color: '#43A047' }, // green\n { name: 'Engineering', rank: 5, color: '#6D4C41' }, // brown\n];\n\n// Grey: imports, assets and glue — a valid arrow colour, but NOT a process and\n// never carried by a numbered step.\nexport const STRUCTURAL_COLOR = '#9E9E9E';\n\n// The guidance a red lint prints BEFORE the DRIFT lines. A failing check must\n// send the reader to the rules (fix the diagram / the code), never to a weakened\n// check. Exported so a project test can pin the pointer.\nexport const DRIFT_GUIDANCE = [\n 'workflow-arrows-lint: docs/workflow-arrows.puml has drifted from the code.',\n 'Maintenance rules + how to read it: AGENTS/workflow-arrows.md',\n 'then make the diagram match the code — or fix the code if the change was',\n 'unintended. Never weaken/skip this check or erase bricks; re-render the .svg.',\n].join('\\n');\n\n// The check codes an @lint-ignore mask may suppress — only the cheap validations.\n// Everything else (A–H and M) is STRUCTURAL: a mask naming it is itself an error,\n// so a structural gap can never be hidden. `I` is the module-edge check: a\n// by-path spawn or a dynamic import is a legitimate false positive.\nexport const MASKABLE_CODES = new Set(['I', 'P1', 'P2', 'P3']);\n\n// The closed vocabulary of reasons a mask may cite. The mechanism states WHY the\n// drawn thing is not a real edge, so a mask asserts a falsifiable fact.\nconst MECHANISMS = new Set(['by-path', 'dynamic', 'transitive', 'non-module']);\n\n// formatProblem(p) → \"CODE: subject — message\" (the CLI/test rendering).\nexport function formatProblem(p) {\n return `${p.code}: ${p.subject} — ${p.message}`;\n}\n\n// globToRegex(glob) → an unanchored RegExp for a gitignore-style mask: `*` = any\n// run, `?` = one char, every other character literal (regex metachars escaped).\nfunction globToRegex(glob) {\n let out = '';\n for (const ch of glob) {\n if (ch === '*') out += '.*';\n else if (ch === '?') out += '.';\n else out += ch.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n }\n return new RegExp(out);\n}\n\n// parseIgnoreBlock(text) → { masks, errors }. A block is:\n// ' @lint-ignore\n// ' [P1] arrow * # transitive: ...\n// ' @end\n// Only lines between the markers are read; a `'`-line with no `[CODE]` is a\n// comment. Every rule is validated here — a maskable code, a reason with a known\n// mechanism — and an invalid rule is an M error and is NEVER applied.\nconst IGNORE_START = /^\\s*'\\s*@lint-ignore\\b/;\nconst IGNORE_END = /^\\s*'\\s*@end\\b/;\n\nfunction parseIgnoreBlock(text) {\n const masks = [];\n const errors = [];\n const lines = text.split(/\\r?\\n/);\n for (let i = 0; i < lines.length; i++) {\n if (!IGNORE_START.test(lines[i])) continue;\n const startLine = i + 1;\n let end = -1;\n for (let j = i + 1; j < lines.length; j++) {\n if (IGNORE_END.test(lines[j])) {\n end = j;\n break;\n }\n }\n if (end === -1) {\n errors.push({ code: 'M', subject: `line ${startLine}`, message: '@lint-ignore without @end' });\n break;\n }\n for (let k = i + 1; k < end; k++) {\n const raw = lines[k];\n if (!raw.trim()) continue;\n if (!/^\\s*'/.test(raw)) {\n errors.push({\n code: 'M',\n subject: `line ${k + 1}`,\n message: \"ignore-block line is not a puml comment (must start with ')\",\n });\n continue;\n }\n const body = raw.replace(/^\\s*'\\s?/, '').trim();\n if (!body) continue;\n const rule = body.match(/^\\[([A-Za-z0-9]+)\\]\\s+(.+)$/);\n if (!rule) {\n // A `[`-opening line is meant to be a rule and failed to parse; anything\n // else is a plain comment.\n if (body.startsWith('[')) {\n errors.push({\n code: 'M',\n subject: `line ${k + 1}`,\n message: \"malformed mask (expected '[CODE] <glob> # <mechanism>: <reason>')\",\n });\n }\n continue;\n }\n const code = rule[1];\n const rest = rule[2];\n const hash = rest.indexOf('#');\n const globRaw = (hash === -1 ? rest : rest.slice(0, hash)).trim();\n const reason = hash === -1 ? '' : rest.slice(hash + 1);\n const label = `[${code}] ${globRaw}`;\n\n if (!MASKABLE_CODES.has(code)) {\n errors.push({ code: 'M', subject: label, message: `mask targets a structural check ${code}` });\n continue; // structural targets are never applied\n }\n const mech = reason.match(/^\\s*([A-Za-z][\\w-]*)\\s*:/);\n if (!mech) {\n errors.push({ code: 'M', subject: label, message: \"mask has no reason (expected '# <mechanism>: ...')\" });\n continue;\n }\n if (!MECHANISMS.has(mech[1])) {\n errors.push({\n code: 'M',\n subject: label,\n message: `unknown mechanism '${mech[1]}' (allowed: by-path|dynamic|transitive|non-module)`,\n });\n continue;\n }\n const negated = globRaw.startsWith('!');\n const glob = negated ? globRaw.slice(1).trim() : globRaw;\n if (!glob) {\n errors.push({ code: 'M', subject: label, message: 'mask has no glob' });\n continue;\n }\n masks.push({ code, glob, negated, regex: globToRegex(glob), label, used: false });\n }\n i = end;\n }\n return { masks, errors };\n}\n\n// pkgPath(name) → the drawer path (the title line before the `\\n====` divider)\nfunction pkgPath(name) {\n return (name ?? '').split('\\\\n')[0].trim();\n}\n\n// immediateFiles(dir, exts) → sorted direct file names ([] if absent / no match)\nfunction immediateFiles(dir, exts) {\n if (!fs.existsSync(dir)) return [];\n return fs\n .readdirSync(dir, { withFileTypes: true })\n .filter((e) => e.isFile() && (!exts || !exts.length || exts.some((x) => e.name.endsWith(x))))\n .map((e) => e.name)\n .sort();\n}\n\n// declaredDrawers(text) → the drawer paths from `package \"<path>...\"`\nexport function declaredDrawers(text) {\n return [\n ...new Set(\n [...text.matchAll(/^\\s*package\\s+\"([^\"]*)\"/gm)]\n .map((m) => pkgPath(m[1]))\n .filter((p) => p && !p.startsWith('npm:')),\n ),\n ].sort();\n}\n\n// parseLinks(text) → [{ raw, url, file, symbol }]. The puml wraps a link as\n// [[<url>[ <label>]]]; the URL ends at the first space (the label may hold the\n// step number). `file` drops the fragment; `symbol` is the fragment (or null).\nexport function parseLinks(text) {\n const out = [];\n for (const m of text.matchAll(/\\[\\[([^\\]]+)\\]\\]/g)) {\n const raw = m[1];\n const sp = raw.indexOf(' ');\n const url = sp === -1 ? raw : raw.slice(0, sp);\n const hash = url.indexOf('#');\n out.push({\n raw,\n url,\n file: hash === -1 ? url : url.slice(0, hash),\n symbol: hash === -1 ? null : url.slice(hash + 1),\n });\n }\n return out;\n}\n\n// The arrow-line grammar: `A -[#c]-> B : label`, `A --> B : label`,\n// `A ..> B : label`, `A -[#c]..> B : label`. The operator is captured whole so\n// the colour and the solid/dashed shape stay inspectable.\nconst ARROW_LINE = /^(\\w+)\\s+(-\\[[^\\]]+\\](?:->|\\.\\.>)|-->|\\.\\.>)\\s+(\\w+)\\s*:\\s*(.*)$/;\n\n// parseArrows(text) → [{ source, target, operator, color, label }] for every\n// arrow line, in draw order. `color` is the normalized `#RRGGBB` or null.\nexport function parseArrows(text) {\n const out = [];\n for (const line of text.split(/\\r?\\n/)) {\n const m = line.match(ARROW_LINE);\n if (!m) continue;\n const c = m[2].match(/#([0-9A-Fa-f]{6})/);\n out.push({\n source: m[1],\n target: m[3],\n operator: m[2],\n color: c ? `#${c[1].toUpperCase()}` : null,\n label: m[4],\n });\n }\n return out;\n}\n\n// actorAliases(text) → the Set of aliases declared as `actor \"...\" as X`.\nexport function actorAliases(text) {\n return new Set([...text.matchAll(/^\\s*actor\\s+\"[^\"]*\"\\s+as\\s+(\\w+)/gm)].map((m) => m[1]));\n}\n\n// missingScriptDrawers(subdirNames, declaredDrawers) → `scripts/<name>` paths still\n// missing a drawer declaration. `subdirNames` are relative to scripts/ (a nested\n// subpath like `product/site-build` works too), so EVERY directory under scripts/\n// recursively — not just the immediate children — must be drawn.\nexport function missingScriptDrawers(subdirNames, declaredDrawers) {\n return subdirNames\n .map((n) => `scripts/${n}`)\n .filter((p) => !declaredDrawers.includes(p));\n}\n\n// scriptDirNames(scriptsDir) → every directory under scripts/, as posix paths\n// relative to scripts/ without the `scripts/` prefix (`lib`, `product`,\n// `product/pr-review/audit/llm`, …), sorted. The walk is recursive; symlinks are\n// not followed (a symlinked dir is skipped), and a missing tree yields [].\nfunction scriptDirNames(scriptsDir) {\n if (!fs.existsSync(scriptsDir)) return [];\n const out = [];\n const walk = (dir, rel) => {\n for (const e of fs.readdirSync(dir, { withFileTypes: true })) {\n if (!e.isDirectory()) continue;\n const child = rel ? `${rel}/${e.name}` : e.name;\n out.push(child);\n walk(path.join(dir, e.name), child);\n }\n };\n walk(scriptsDir, '');\n return out.sort();\n}\n\n// bricks(text) → the components with their enclosing drawer: [{ alias, st, pkg, file }].\n// A simple brace-depth scan keeps the innermost open `package \"...\"` frame;\n// `skinparam package { ... }` carries no quoted name and is skipped. `file` is\n// the brick's own [[link]] target (the first link on the component line), or null.\nexport function bricks(text) {\n const out = [];\n const stack = [];\n let depth = 0;\n for (const line of text.split(/\\r?\\n/)) {\n const pkg = line.match(/^\\s*package\\s+\"([^\"]*)\"/);\n const comp = line.match(/component\\s+\"[^\"]*\"\\s+as\\s+(\\w+)\\s*<<(\\w+)>>(.*)$/);\n if (pkg) stack.push({ name: pkg[1], depth });\n if (comp) {\n const link = (comp[3].match(/\\[\\[([^\\]]+)\\]\\]/) || [])[1] ?? null;\n const url = link ? link.split(' ')[0] : null;\n out.push({\n alias: comp[1],\n st: comp[2],\n pkg: stack.length ? stack[stack.length - 1].name : null,\n file: url ? url.split('#')[0] : null,\n });\n }\n depth += (line.match(/\\{/g) || []).length - (line.match(/\\}/g) || []).length;\n while (stack.length && depth <= stack[stack.length - 1].depth) stack.pop();\n }\n return out;\n}\n\n// labelBlocks(text) → every component/package label as { kind, subject, text,\n// symbol }: `subject` is the brick alias (or the drawer path), `text` the raw\n// quoted label, `symbol` the `#fragment` of the brick's [[link]] (or null). One\n// parser feeds check (J), so a brick and a drawer are held to one grammar.\nfunction labelBlocks(text) {\n const out = [];\n for (const line of text.split(/\\r?\\n/)) {\n const comp = line.match(/^\\s*component\\s+\"([^\"]*)\"\\s+as\\s+(\\w+)\\s*<<\\w+>>(.*)$/);\n if (comp) {\n const link = (comp[3].match(/\\[\\[([^\\]]+)\\]\\]/) || [])[1] ?? null;\n const url = link ? link.split(' ')[0] : null;\n const hash = url ? url.indexOf('#') : -1;\n out.push({\n kind: 'component',\n subject: comp[2],\n text: comp[1],\n symbol: hash === -1 ? null : url.slice(hash + 1),\n });\n continue;\n }\n const pkg = line.match(/^\\s*package\\s+\"([^\"]*)\"/);\n if (pkg) {\n out.push({ kind: 'package', subject: pkgPath(pkg[1]), text: pkg[1], symbol: null });\n }\n }\n return out;\n}\n\n// symbolDeclared(src, symbol) → true when the symbol is a declaration or a call\n// site (a reference alone is not enough: `#handleChat` must be a real member,\n// not a mention in a comment). This is what catches a renamed method.\nexport function symbolDeclared(src, symbol) {\n const s = symbol.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n return new RegExp(`\\\\b${s}\\\\s*\\\\(|(?:function|class|const|let|var)\\\\s+${s}\\\\b`).test(src);\n}\n\n// importSpecifiers(src) → the module specifiers a file imports: static `from`\n// clauses (re-exports included), side-effect imports and dynamic `import(...)`,\n// deduped. Bare/node specifiers are kept here and filtered later by\n// resolveSpecifier (only relative ones are part of our graph).\nfunction importSpecifiers(src) {\n const out = new Set();\n const patterns = [\n /\\bfrom\\s*['\"]([^'\"]+)['\"]/g,\n /\\bimport\\s*['\"]([^'\"]+)['\"]/g,\n /\\bimport\\s*\\(\\s*['\"]([^'\"]+)['\"]\\s*\\)/g,\n ];\n for (const re of patterns) for (const m of src.matchAll(re)) out.add(m[1]);\n return out;\n}\n\n// resolveSpecifier(spec, fromFile) → the absolute file a RELATIVE specifier points\n// at, trying the path, `+'.mjs'`, `+'.js'`, `/index.mjs`, `/index.js`; null when\n// the specifier is bare / `node:` or nothing exists (not a first-party edge).\nfunction resolveSpecifier(spec, fromFile) {\n if (!spec.startsWith('.')) return null;\n const base = path.resolve(path.dirname(fromFile), spec);\n const candidates = [base, `${base}.mjs`, `${base}.js`, path.join(base, 'index.mjs'), path.join(base, 'index.js')];\n for (const c of candidates) {\n try {\n if (fs.statSync(c).isFile()) return c;\n } catch {\n // try the next candidate\n }\n }\n return null;\n}\n\n// moduleFiles(dir) → every `.mjs`/`.js` file under dir, recursively (absolute).\nfunction moduleFiles(dir) {\n const out = [];\n if (!fs.existsSync(dir)) return out;\n for (const e of fs.readdirSync(dir, { withFileTypes: true })) {\n const p = path.join(dir, e.name);\n if (e.isDirectory()) out.push(...moduleFiles(p));\n else if (e.isFile() && /\\.(?:mjs|js)$/.test(e.name)) out.push(p);\n }\n return out;\n}\n\n// buildImportGraph(repoRoot) → Map<absFile, Set<abs imported file>> for every\n// first-party module under scripts/ and input/ (relative specifiers resolved).\nfunction buildImportGraph(repoRoot) {\n const graph = new Map();\n const files = [...moduleFiles(path.join(repoRoot, 'scripts')), ...moduleFiles(path.join(repoRoot, 'input'))];\n for (const f of files) {\n const imported = new Set();\n graph.set(f, imported);\n let src;\n try {\n src = fs.readFileSync(f, 'utf8');\n } catch {\n continue;\n }\n for (const spec of importSpecifiers(src)) {\n const resolved = resolveSpecifier(spec, f);\n if (resolved) imported.add(resolved);\n }\n }\n return graph;\n}\n\n// lintProblems(text, { pumlDir, repoRoot }) → { problems, suppressed, ignoreErrors }.\n// `problems` = the real problems no mask hides, plus every M (ignore-block) error;\n// `suppressed` = { count, list } of the real problems a mask moved out. M errors\n// are never suppressible. Pure over `text`.\nexport function lintProblems(text, { pumlDir = path.dirname(DEFAULT_PUML), repoRoot = ROOT } = {}) {\n const problems = [];\n const all = bricks(text);\n const arrows = parseArrows(text);\n\n // (A) drawers: the first-party tree, both directions\n const declared = declaredDrawers(text);\n for (const d of DRAWERS) if (!declared.includes(d.path)) problems.push({ code: 'A', subject: d.path, message: 'drawer not drawn' });\n for (const p of declared) {\n if (!DRAWERS.some((d) => d.path === p)) {\n problems.push({ code: 'A', subject: p, message: 'phantom drawer (not a configured first-party dir)' });\n }\n }\n\n // (H) every directory under scripts/ (recursively) must be a declared drawer\n const scriptsDir = path.join(repoRoot, 'scripts');\n const scriptSubdirs = scriptDirNames(scriptsDir);\n for (const p of missingScriptDrawers(scriptSubdirs, declared)) {\n problems.push({ code: 'H', subject: p, message: 'drawer not drawn (scripts/ subfolder)' });\n }\n\n // (B) file coverage for code drawers, both directions + no double-draw\n for (const d of DRAWERS) {\n if (d.cover !== 'files') continue;\n const onDisk = immediateFiles(path.join(repoRoot, d.path), d.ext);\n const drawn = all.filter((b) => pkgPath(b.pkg) === d.path && b.file).map((b) => path.basename(b.file));\n for (const f of onDisk) if (!drawn.includes(f)) problems.push({ code: 'B', subject: `${d.path}/${f}`, message: 'file not drawn' });\n for (const f of drawn) if (!onDisk.includes(f)) problems.push({ code: 'B', subject: `${d.path}/${f}`, message: 'phantom brick file' });\n for (const f of new Set(drawn)) {\n if (drawn.filter((x) => x === f).length > 1) {\n problems.push({ code: 'B', subject: `${d.path}/${f}`, message: 'drawn more than once' });\n }\n }\n }\n\n // (C) + (D) links resolve, and their #symbol is declared in the target\n for (const link of parseLinks(text)) {\n if (SCHEME.test(link.url)) continue;\n const target = path.resolve(pumlDir, link.file);\n if (!fs.existsSync(target) || !fs.statSync(target).isFile()) {\n problems.push({ code: 'C', subject: link.file, message: 'link target not found' });\n continue;\n }\n if (link.symbol && !symbolDeclared(fs.readFileSync(target, 'utf8'), link.symbol)) {\n problems.push({ code: 'D', subject: `${link.file}#${link.symbol}`, message: `link symbol \"${link.symbol}\" not declared` });\n }\n }\n\n // (E) step numbers: the labels must carry exactly 1..N, unique\n const nums = [...text.matchAll(/(\\d+)\\s*(?:·|⟵)/g)].map((m) => Number(m[1]));\n const seen = new Set();\n const dupes = new Set();\n for (const n of nums) {\n if (seen.has(n)) dupes.add(n);\n seen.add(n);\n }\n if (dupes.size) {\n problems.push({ code: 'E', subject: 'flow', message: `step numbering has duplicates: ${[...dupes].sort((a, b) => a - b).join(', ')}` });\n }\n const max = seen.size ? Math.max(...seen) : 0;\n const missing = [];\n for (let i = 1; i <= max; i++) if (!seen.has(i)) missing.push(i);\n if (missing.length) problems.push({ code: 'E', subject: 'flow', message: `step numbering has gaps: missing ${missing.join(', ')}` });\n\n // (F) a brick's stereotype must equal its drawer's stereotype\n for (const b of all) {\n const d = DRAWERS.find((x) => x.path === pkgPath(b.pkg));\n if (d && b.st !== d.st) {\n problems.push({\n code: 'F',\n subject: b.alias,\n message: `stereotype <<${b.st}>> mismatches drawer ${d.path} (expect <<${d.st}>>)`,\n });\n }\n }\n\n // (G) T3 idiom: a numbered call to a module brick must carry a\n // [[file#symbol]] link; a numbered return must carry none. Module bricks are\n // the bricks whose stereotype is not an exempt external/pack one.\n const modules = new Set(all.filter((b) => !EXEMPT_STEREOTYPES.has(b.st)).map((b) => b.alias));\n for (const a of arrows) {\n const target = a.target;\n const label = a.label;\n const hasLink = label.includes('[[');\n if (/(\\d+)\\s*·/.test(label) && modules.has(target) && !hasLink) {\n problems.push({ code: 'G', subject: `${a.source} -> ${a.target}`, message: `numbered call to module \"${target}\" lacks a [[file#symbol]] link (T3)` });\n }\n if (/\\d+\\s*⟵/.test(label) && hasLink) {\n problems.push({ code: 'G', subject: `${a.source} -> ${a.target}`, message: `numbered return to \"${target}\" must not carry a link (T3)` });\n }\n }\n\n // (I) a drawn edge between two MODULE bricks must be a real import in one\n // direction. A brick link on a `.mjs`/`.js` file on both ends is checked\n // against the first-party import graph; a by-path spawn or a stale map edge\n // is drift (mask it only with a justified @lint-ignore). Non-module targets\n // (.css/.svg/.png/.hbs/.json) and unresolved links are skipped — other checks\n // own them.\n const MODULE_FILE = /\\.(?:mjs|js)$/;\n const byAlias = new Map(all.map((b) => [b.alias, b]));\n const graph = buildImportGraph(repoRoot);\n const seenEdges = new Set();\n for (const a of arrows) {\n const src = byAlias.get(a.source);\n const dst = byAlias.get(a.target);\n if (!src || !dst || !src.file || !dst.file) continue;\n if (!MODULE_FILE.test(src.file) || !MODULE_FILE.test(dst.file)) continue;\n const key = `${a.source} -> ${a.target}`;\n if (seenEdges.has(key)) continue;\n seenEdges.add(key);\n const srcFile = path.resolve(pumlDir, src.file);\n const dstFile = path.resolve(pumlDir, dst.file);\n let bothExist = false;\n try {\n bothExist = fs.statSync(srcFile).isFile() && fs.statSync(dstFile).isFile();\n } catch {\n bothExist = false;\n }\n if (!bothExist) continue; // unresolved links are check (C)'s business\n const forward = graph.get(srcFile) ?? new Set();\n const backward = graph.get(dstFile) ?? new Set();\n if (!forward.has(dstFile) && !backward.has(srcFile)) {\n problems.push({ code: 'I', subject: key, message: 'drawn edge is not a real import in either direction' });\n }\n }\n\n // (J) one label grammar for every brick and drawer (KDV-CI-26): NAME, then the\n // business meaning, then `--` and the members — the `--` only when members\n // exist. Members never sit above the line; a `--` needs a meaning above it and\n // members below it; a linked #symbol must be one of those members.\n for (const b of labelBlocks(text)) {\n const lines = b.text.split('\\\\n');\n const separators = lines.filter((l) => l === '--').length;\n if (separators > 1) {\n problems.push({ code: 'J', subject: b.subject, message: 'more than one -- separator' });\n continue;\n }\n const sep = lines.indexOf('--');\n const above = sep === -1 ? lines.slice(1) : lines.slice(1, sep);\n const below = sep === -1 ? [] : lines.slice(sep + 1);\n if (above.some((l) => MEMBER_LINE.test(l))) {\n problems.push({ code: 'J', subject: b.subject, message: 'members must sit below the -- separator' });\n }\n if (sep === -1) continue;\n if (!above.some((l) => !MEMBER_LINE.test(l))) {\n problems.push({ code: 'J', subject: b.subject, message: 'the -- needs a meaning line above it' });\n }\n if (!below.length) {\n problems.push({\n code: 'J',\n subject: b.subject,\n message: 'the -- has no members below it (drop the -- when there are no members)',\n });\n continue;\n }\n if (b.symbol) {\n const sym = b.symbol.replace(/\\(\\)$/, '');\n const members = new Set();\n for (const ml of below) for (const tok of ml.split(' · ')) members.add(tok.replace(/\\(\\)$/, ''));\n if (!members.has(sym)) {\n problems.push({\n code: 'J',\n subject: b.subject,\n message: `the linked symbol '${sym}' is not listed among the members below --`,\n });\n }\n }\n }\n\n // (P1) a process colour: every arrow names its business process (or is grey glue)\n const palette = new Set([...PROCESSES.map((p) => p.color), STRUCTURAL_COLOR]);\n for (const a of arrows) {\n if (!a.color) problems.push({ code: 'P1', subject: `arrow ${a.source} -> ${a.target}`, message: 'has no process colour' });\n else if (!palette.has(a.color)) {\n problems.push({\n code: 'P1',\n subject: `arrow ${a.source} -> ${a.target}`,\n message: `colour ${a.color} is not in the process palette`,\n });\n }\n }\n\n // (P2) rank order: a numbered step carries a process colour, and the process\n // rank never decreases in draw order — steps are grouped by process.\n const byColor = new Map(PROCESSES.map((p) => [p.color, p]));\n const numbered = [];\n for (const a of arrows) {\n const s = a.label.match(/(\\d+)\\s*(?:·|⟵)/);\n if (s) numbered.push({ ...a, step: Number(s[1]) });\n }\n for (const a of numbered) {\n if (a.color === STRUCTURAL_COLOR) {\n problems.push({\n code: 'P2',\n subject: `step ${a.step}`,\n message: `(${a.source} -> ${a.target}) carries the structural colour ${STRUCTURAL_COLOR} — numbered arrows must use a process colour`,\n });\n }\n }\n let prev = null;\n for (const a of numbered) {\n const proc = byColor.get(a.color);\n if (!proc) continue;\n if (prev && proc.rank < prev.proc.rank) {\n problems.push({\n code: 'P2',\n subject: `step ${a.step}`,\n message: `step ${prev.step} (${prev.proc.name}, rank ${prev.proc.rank}) precedes step ${a.step} (${proc.name}, rank ${proc.rank}) — steps must be grouped by process rank`,\n });\n break;\n }\n prev = { step: a.step, proc };\n }\n\n // (P3) no orphan bricks: BFS from the actors over the drawn arrows (dashed\n // edges included); every non-exempt brick must be reachable.\n const reached = new Set(actorAliases(text));\n const edges = new Map();\n for (const a of arrows) {\n if (!edges.has(a.source)) edges.set(a.source, []);\n edges.get(a.source).push(a.target);\n }\n const queue = [...reached];\n while (queue.length) {\n for (const t of edges.get(queue.shift()) ?? []) {\n if (!reached.has(t)) {\n reached.add(t);\n queue.push(t);\n }\n }\n }\n for (const b of all) {\n if (EXEMPT_STEREOTYPES.has(b.st)) continue;\n if (!reached.has(b.alias)) problems.push({ code: 'P3', subject: `brick ${b.alias}`, message: 'is not reachable from any actor' });\n }\n\n // One truth per issue: collapse exact duplicates before masking.\n const seenKeys = new Set();\n const real = problems.filter((p) => {\n const k = formatProblem(p);\n if (seenKeys.has(k)) return false;\n seenKeys.add(k);\n return true;\n });\n\n // Apply the @lint-ignore masks (last match wins) and collect the M errors,\n // which are never suppressible.\n const { masks, errors: ignoreErrors } = parseIgnoreBlock(text);\n const suppressed = [];\n const kept = [];\n for (const p of real) {\n const key = `${p.code}: ${p.subject}`;\n let ignored = false;\n for (const mask of masks) {\n if (mask.regex.test(key)) {\n mask.used = true;\n ignored = !mask.negated;\n }\n }\n (ignored ? suppressed : kept).push(p);\n }\n for (const mask of masks) {\n if (!mask.used) ignoreErrors.push({ code: 'M', subject: mask.label, message: 'unused mask' });\n }\n\n return {\n problems: [...kept, ...ignoreErrors],\n suppressed: { count: suppressed.length, list: suppressed },\n ignoreErrors,\n };\n}\n\n// lintDiagram(text, opts) → formatProblem()ed problems ([] = clean). The string\n// API stays for callers/tests that read the DRIFT lines.\nexport function lintDiagram(text, opts) {\n return lintProblems(text, opts).problems.map(formatProblem);\n}\n\n// CLI: read the diagram, print problems, exit 1 on any. Silent when clean.\nexport function main({ puml = DEFAULT_PUML, pumlDir = path.dirname(puml), repoRoot = ROOT } = {}) {\n let text;\n try {\n text = fs.readFileSync(puml, 'utf8');\n } catch (e) {\n console.error(`workflow-arrows-lint: cannot read ${puml}: ${e.message}`);\n process.exit(1);\n return;\n }\n const { problems, suppressed } = lintProblems(text, { pumlDir, repoRoot });\n if (problems.length) {\n console.error(DRIFT_GUIDANCE);\n console.error(problems.map((p) => `DRIFT ${formatProblem(p)}`).join('\\n'));\n }\n if (suppressed.count > 0) console.error(`suppressed ${suppressed.count} (see @lint-ignore)`);\n if (problems.length) process.exit(1);\n}\n\nconst isMain = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;\nif (isMain) main();\nscripts/tooling/workflow-map/workflow-arrows-svg.mjsA small post-render step: after PlantUML writes the .svg, this injects a block that lights a whole\narrow (line, head, label) on hover. Plain-JS detail, but it is part of what makes the human render\nusable for long cross-cutting arrows.
#!/usr/bin/env node\n/**\n * CONTRACT: scripts/tooling/workflow-map/workflow-arrows-svg.mjs\n * ROLE: post-processes the rendered docs/workflow-arrows.svg to add the hover highlight\n * EXPORTS:\n * injectHover — adds the whole-arrow hover CSS block to an SVG string\n * parseHoverColor — reads `skinparam pathHoverColor` from the .puml\n * main — the CLI entry point\n * CONSUMES:\n * node:fs — read the .puml, rewrite the .svg\n * node:path — resolve the diagram files\n * node:url — find the repo root and detect the entry point\n * INVARIANTS:\n * — injection is idempotent: the block carries a marker and is replaced, never doubled\n * — the hover colour has one source: skinparam pathHoverColor in the .puml\n */\n// workflow-arrows-svg — the hover step for the code map (docs/workflow-arrows.svg).\n//\n// PlantUML's `skinparam pathHoverColor` emits only `path:hover { stroke: … }`: the\n// arrow line is stroke-width 1 (hard to hit), and its head is a <polygon> and its\n// label an <a><text> — neither recolours. So after rendering, we append a small\n// CSS block that lights the WHOLE arrow (`g.link:hover` — line, head, label),\n// thickens the line, and LINGERS on hover-out (a transition delay) so a long arrow\n// stays lit while the reader scrolls to its far end. Hover works only in a\n// CSS-capable viewer (a browser), never in a PNG or a static IDE preview.\n//\n// Usage: render the .puml, then `npm run workflow-arrows:svg` (see the doc).\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport { fileURLToPath, pathToFileURL } from 'node:url';\n\nconst ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');\nconst DEFAULT_SVG = path.join(ROOT, 'docs', 'workflow-arrows.svg');\nconst DEFAULT_PUML = path.join(ROOT, 'docs', 'workflow-arrows.puml');\n\n// A CSS comment marks the injected block so a re-run replaces it instead of doubling it.\nconst MARK = '/* workflow-arrows-hover */';\nconst LINGER_DEFAULT = 5;\n\n// parseHoverColor(puml) → the `skinparam pathHoverColor` value (or the default red).\nexport function parseHoverColor(puml) {\n const m = puml.match(/^\\s*skinparam\\s+pathHoverColor\\s+(\\S+)/im);\n return m ? m[1] : '#C62828';\n}\n\n// hoverCss(color, lingerSeconds) → the CSS block: whole-arrow highlight + linger.\nfunction hoverCss(color, lingerSeconds) {\n const t = `.6s ${lingerSeconds}s`;\n return [\n MARK,\n `g.link path,g.link polygon{transition:stroke ${t},fill ${t},stroke-width ${t}}`,\n `g.link:hover path{stroke:${color} !important;stroke-width:2;transition:none}`,\n `g.link:hover polygon{fill:${color} !important;stroke:${color} !important;transition:none}`,\n ].join('\\n');\n}\n\nconst escapeRe = (s) => s.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n\n// injectHover(svg, { color, lingerSeconds }) → the SVG with the hover block appended\n// inside its existing <style> (a fresh one is added when the render carries none).\nexport function injectHover(svg, { color = '#C62828', lingerSeconds = LINGER_DEFAULT } = {}) {\n // Replace any previous injection (marker up to the style's end) so re-runs converge.\n let out = svg.replace(new RegExp(`\\\\n?${escapeRe(MARK)}[\\\\s\\\\S]*?(?=]]></style>|</style>)`), '');\n const block = `\\n${hoverCss(color, lingerSeconds)}\\n`;\n if (out.includes(']]></style>')) return out.replace(']]></style>', `${block}]]></style>`);\n if (out.includes('</style>')) return out.replace('</style>', `${block}</style>`);\n return out.replace(/(<svg\\b[^>]*>)/, `$1<style type=\"text/css\"><![CDATA[${block}]]></style>`);\n}\n\n// CLI: read the .puml + .svg, inject the hover block, write the .svg back.\nexport function main({ svg = DEFAULT_SVG, puml = DEFAULT_PUML, color, lingerSeconds = LINGER_DEFAULT } = {}) {\n let pumlText;\n let svgText;\n try {\n pumlText = fs.readFileSync(puml, 'utf8');\n svgText = fs.readFileSync(svg, 'utf8');\n } catch (e) {\n console.error(`workflow-arrows-svg: ${e.message}`);\n process.exit(1);\n return;\n }\n const c = color || parseHoverColor(pumlText);\n const out = injectHover(svgText, { color: c, lingerSeconds });\n if (out === svgText) {\n console.log('workflow-arrows-svg: hover block already present');\n return;\n }\n fs.writeFileSync(svg, out);\n console.log(`workflow-arrows-svg: hover block written to ${path.relative(ROOT, svg)} (color ${c}, linger ${lingerSeconds}s)`);\n}\n\nconst isMain = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;\nif (isMain) main();\nscripts/tooling/quality-gates/req-coverage.jsThe requirements-machine coverage check, extended with the flow: pass: checkFlow, the frozen\nLEGACY anchor, and the hardened FLOW regex (the field must be delimited by ( or ;, so prose\nmentioning flow: is never mistaken for the field).
Note (the only deliberate edit): the sha256 literal in LEGACY is replaced by a placeholder.\nOn a fresh project your legacy set is empty; compute your own anchor and paste it in:
node -e \"const {createHash}=require('node:crypto'); console.log(createHash('sha256').update('').digest('hex'))\"\n#!/usr/bin/env node\n/**\n * CONTRACT: scripts/tooling/quality-gates/req-coverage.js\n * ROLE: reconciles requirement IDs between REQUIREMENTS.md and the tests, and enforces the flow-impact hook on every row\n * EXPORTS:\n * checkFlow — flow: problems for every row, against a frozen legacy exemption anchor\n * LEGACY — the frozen { count, sha256 } anchor of the grandfathered `flow: legacy` set\n * CONSUMES:\n * ../workflow-map/workflow-arrows-lint.mjs — the PROCESSES palette (one truth)\n * node:crypto — sha256 of the sorted legacy ID set (the frozen anchor)\n * node:fs — read the registry and the tests\n * node:path — join paths\n * node:url — find the repo root and detect the entry point\n * INVARIANTS:\n * — a ✅ row without a test, or a test ID absent from the registry, exits 1\n * — every row carries a valid flow: (`<process>[,…]` | none | legacy)\n * — the `flow: legacy` set must match LEGACY exactly, so it cannot silently grow\n */\n\n// scripts/tooling/quality-gates/req-coverage.js — reconcile requirement IDs between REQUIREMENTS.md and tests.\n// Exit 1 on: an ID used in a test but absent from the registry; a ✅ row with no test;\n// a row without a valid `flow:` field; the frozen `flow: legacy` exemption set changing.\n// The exemption set is anchored in code (LEGACY count + sha256), not a file, so a new\n// row cannot dodge the hook by writing `legacy` — that changes the set and fails loudly.\n// Prefix/suffix are project-specific: set PREFIX and TESTS_DIR below.\nimport { readFileSync, readdirSync, statSync, existsSync } from \"node:fs\"\nimport { createHash } from \"node:crypto\"\nimport { join } from \"node:path\"\nimport { fileURLToPath, pathToFileURL } from \"node:url\"\nimport { PROCESSES } from \"../workflow-map/workflow-arrows-lint.mjs\"\n\nconst ROOT = fileURLToPath(new URL(\"../../../\", import.meta.url))\nconst PREFIX = \"KDV\" // ← your registry prefix\nconst TESTS_DIR = join(ROOT, \"tests\")\n\n// LEGACY — the frozen anchor of the grandfathered `flow: legacy` set (rows that\n// predate the hook). `count` = number of such rows; `sha256` = hex digest of the\n// sorted legacy IDs joined by \"\\n\". Changing this set is a deliberate, reviewable\n// act: edit the constant only when the change is intentional.\nexport const LEGACY = {\n count: 0, // <- your grandfathered rows; a fresh project starts at 0\n sha256: \"<<fill in the anchor for your legacy set - see the note above>>\",\n}\n\n// Group codes may contain digits (e.g. KDV-A11Y), so the class is [A-Z0-9].\n// One grammar for both the coverage pass and the flow pass (one truth per row).\nconst ROW = new RegExp(`^-\\\\s*(✅|🟧|⬜|❓)\\\\s*\\\\*\\\\*(${PREFIX}-[A-Z0-9]+-\\\\d+)\\\\*\\\\*[^\\\\n]*`, \"gm\")\n// The optional flow: field. It MUST be delimited — preceded by `(` or `;` (the\n// reference block's separators) — so prose that merely mentions \"flow:\" (or a\n// `workflow:` token) is never mistaken for the field. The capture stops at `;`\n// (reference separator) and `)` (when the field is the last reference).\nconst FLOW = /[(;]\\s*flow:\\s*([^;)]+)/\nconst FLOW_NONE = \"none\"\nconst FLOW_LEGACY = \"legacy\"\n\n// isValidFlow(value, allowed) → true for `none`, `legacy`, or a comma-separated\n// list of palette process names (case-sensitive, trimmed). The keywords never mix\n// with names or each other: `none, Publish` is invalid because `none` is not a\n// palette name and the keyword branch short-circuits only for the bare keyword.\nfunction isValidFlow(value, allowed) {\n if (value === FLOW_NONE || value === FLOW_LEGACY) return true\n const names = value.split(\",\").map((s) => s.trim()).filter(Boolean)\n return names.length > 0 && names.every((n) => allowed.has(n))\n}\n\n// checkFlow(registryText, processNames, frozen) → the flow-impact problems\n// ([] = clean). EVERY row must carry a valid `flow:`; the rows declaring\n// `flow: legacy` are the grandfathered exemption set, which must match the frozen\n// anchor `{ count, sha256 }` exactly — otherwise a new row could dodge by writing\n// `legacy`. Pure over its arguments (sha256 via node:crypto).\nexport function checkFlow(registryText, processNames, frozen) {\n const allowed = new Set(processNames)\n const problems = []\n const legacyIds = []\n for (const m of registryText.matchAll(ROW)) {\n const id = m[2]\n const fm = m[0].match(FLOW)\n if (!fm) {\n problems.push(`requirement ${id} has no flow: field (name a process, 'none', or 'legacy')`)\n continue\n }\n const value = fm[1].trim()\n if (!isValidFlow(value, allowed)) {\n problems.push(\n `requirement ${id} has an unknown flow: '${value}' (allowed: ${[...allowed, FLOW_NONE, FLOW_LEGACY].join(\", \")})`,\n )\n continue\n }\n if (value === FLOW_LEGACY) legacyIds.push(id)\n }\n legacyIds.sort()\n const digest = createHash(\"sha256\").update(legacyIds.join(\"\\n\")).digest(\"hex\")\n if (legacyIds.length !== frozen.count || digest !== frozen.sha256) {\n problems.push(\n `the flow: legacy exemption set changed (frozen ${frozen.count}/${frozen.sha256.slice(0, 8)}…, ` +\n `now ${legacyIds.length}/${digest.slice(0, 8)}…) — a new requirement must name a process or 'none'; ` +\n `if the change is intentional, update LEGACY in req-coverage.js`,\n )\n }\n return problems\n}\n\nfunction main() {\n const registry = readFileSync(join(ROOT, \"REQUIREMENTS.md\"), \"utf8\")\n const rows = [...registry.matchAll(ROW)].map((m) => ({ status: m[1], id: m[2] }))\n\n // The tests directory may not exist yet on a fresh project — treat it as \"no tests\".\n const files = []\n if (existsSync(TESTS_DIR)) {\n ;(function walk(dir) {\n for (const name of readdirSync(dir)) {\n const p = join(dir, name)\n if (statSync(p).isDirectory()) walk(p)\n // Playwright specs (`*.e2e.js`) are registry tests too — they carry the\n // requirement ID as the first word of the test title exactly like vitest.\n else if (/\\.(test|spec|e2e)\\.[cm]?[jt]s$/.test(name)) files.push(p)\n }\n })(TESTS_DIR)\n }\n\n const tested = new Set()\n for (const f of files) {\n for (const m of readFileSync(f, \"utf8\").matchAll(new RegExp(`${PREFIX}-[A-Z0-9]+-\\\\d+`, \"g\"))) tested.add(m[0])\n }\n\n const known = new Set(rows.map((r) => r.id))\n const problems = []\n for (const id of [...tested].sort()) if (!known.has(id)) problems.push(`test uses unknown ID: ${id}`)\n for (const r of rows) if (r.status === \"✅\" && !tested.has(r.id)) problems.push(`✅ without a test: ${r.id}`)\n\n problems.push(...checkFlow(registry, PROCESSES.map((p) => p.name), LEGACY))\n\n if (problems.length) {\n console.error(\"req-coverage FAILED:\\n \" + problems.join(\"\\n \"))\n process.exit(1)\n }\n console.log(`req-coverage OK (${rows.length} rows, ${tested.size} IDs tested)`)\n}\n\nconst isMain = process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url\nif (isMain) main()\nAGENTS/workflow-arrows.mdThis is the file the agent reads: how to interpret the map, the palette, the drawers table, the\nlinted idioms, the checks, how to suppress a false positive, and how to maintain and render. Drop it\ninto your AGENTS/ and point at it from AGENTS.md (§6.6). If you keep only one file from this dump,\nkeep this one — the rest are its machinery.
# workflow-arrows — the workflow map (`docs/workflow-arrows.puml` → `.svg`)\n\nTwo files, one artifact:\n\n- **`docs/workflow-arrows.puml`** — the machine source: plain text, the thing you\n edit, checked by the linter.\n- **`docs/workflow-arrows.svg`** — the human render: generated from the `.puml`,\n the thing people look at. Never edit it by hand. A fresh project has no `.svg`\n until the map has content and is rendered once.\n\nThe map starts empty and grows with the code: add a drawer when a first-party code\ndirectory appears, a brick when a module appears, a numbered arrow when a\ncross-cutting flow appears. The linter (`scripts/tooling/workflow-map/workflow-arrows-lint.mjs`) keeps it\nfrom rotting, locally and in CI.\n\n## Why a trustworthy map\n\nCode maps usually rot: they show whatever modules someone happened to open last.\nThis one is linted against the code tree, so it either matches the code or the lint\ngoes red. That matters when you touch a cross-cutting flow: you can see the whole\npicture at once and extend the flow that already exists instead of adding a parallel\npath around it. A map you can trust is what prevents those workarounds.\n\nThink of the code as a park with a few main paths — the cross-cutting flows. A new\nfeature should widen a path or add a bench, not cut a flowerbed straight across one\nbecause that is the shortest line to the goal: the flowerbed \"works\" until someone\nwalks the path, and then it is just broken ground. A shortcut around a shared step\nis the same — it routes delivery around the step that owns the concern; locally\ngreen, globally a second truth that drifts. Widening the path is the work; cutting\nacross it is the bug.\n\n## How to read it\n\n- **Drawers** = first-party code directories, drawn as a `package \"<dir>\\n<why>\"`\n block; the header says why the directory exists. Externals (actors, the engine,\n GitHub, dev tools) are top-level bricks stereotyped `<<ext>>`.\n- A **brick** = one file, drawn with one label grammar (check J below):\n `NAME` → one or more lines of **what it does** (business meaning) → `--` →\n **members** (its exported symbols). The `--` exists **only** when there are\n members; a brick whose meaning line already names its one method needs no\n members line. It carries its drawer's stereotype and links its file\n (`[[../<path>#symbol <label>]]`, symbol optional).\n- **Numbered arrows** = the flow order `1..N`. Label line 1 is\n `N · callee.method()` — the API method **of the target brick** (the callee).\n Label line 2 (plain text) is **why** the call happens.\n- **Solid** `-->` = a call; **dashed** `..>` = a return or a push.\n- **Colour** = the business process (P1/P2 below): every arrow carries\n `-[#RRGGBB]->` from the palette, and the numbered flow is grouped by process\n rank, so all rank-1 steps come before rank-2, and so on. Grey `#9E9E9E` is\n structural glue (imports, assets), never a process and never a numbered step.\n- **No orphans**: every non-exempt brick must be reachable from an actor by\n following the drawn arrows (dashed included).\n- **Click targets**: a brick opens its file, a call label opens the callee method\n (in the `.svg` + the IntelliJ PlantUML plugin).\n\n## Process palette\n\n| # | Process | Colour | Covers |\n|---|---|---|---|\n| 1 | PR review | `#00897B` teal | a dump arrives as a validated PR |\n| 2 | Publish | `#1E88E5` blue | build → engine → artifact |\n| 3 | Notify | `#8E24AA` purple | mirroring / card posts |\n| 4 | Consume | `#43A047` green | machine + human reads |\n| 5 | Engineering | `#6D4C41` brown | local dev / tooling |\n\nThe table lives in `PROCESSES` (plus `STRUCTURAL_COLOR`) at the top of the linter.\n\n## The drawers (kodavr)\n\nA drawer is either **file-covered** (`cover: files`) or **dir-only** (`cover: dir`).\nFor a file-covered drawer every matching file must appear as exactly one brick, and\nevery brick must link a file in that drawer. Dir-only drawers need only be drawn;\ntheir bricks are illustrative.\n\n| Drawer | Stereotype | Coverage |\n|---|---|---|\n| `scripts/lib` | `<<lib>>` | files `.mjs` — the shared publishing engine |\n| `scripts/product` | `<<pack>>` | dir — the product processes |\n| `scripts/product/site-build` | `<<cli>>` | files `.mjs` — the site build entry point |\n| `scripts/product/pr-review` | `<<cli>>` | files `.mjs` — the PR surface: card + audit entry points |\n| `scripts/product/pr-review/audit` | `<<audit>>` | files `.mjs` — the deterministic audit engine |\n| `scripts/product/pr-review/audit/llm` | `<<audit>>` | files `.mjs` — the LLM audit layers |\n| `scripts/product/telegram` | `<<cli>>` | files `.mjs` — the Telegram mirror entry point |\n| `scripts/product/brand-media` | `<<cli>>` | files `.mjs` — the brand-image generators |\n| `scripts/tooling` | `<<pack>>` | dir — the development tooling |\n| `scripts/tooling/quality-gates` | `<<cli>>` | files `.mjs`, `.js` — the CI gates |\n| `scripts/tooling/workflow-map` | `<<cli>>` | files `.mjs` — the map's drift alarm + hover injection |\n| `scripts/tooling/dev-tools` | `<<cli>>` | files `.mjs` — local dev conveniences |\n| `input/controllers` | `<<ctrl>>` | files `.js` — engine-injected client controllers |\n| `input/templates` | `<<view>>` | dir — Handlebars layouts + partials |\n| `static/assets` | `<<asset>>` | dir — stylesheet, client JS, brand images |\n| `content/dumps` | `<<content>>` | dir — the dumps themselves |\n\nThe set lives in `DRAWERS` at the top of the linter. The `scripts/` tree is\ntwo-level — `scripts/<category>/<process>/` with categories `product` and\n`tooling` around the shared `lib/` engine; a category and a process folder are\nboth drawers. Add a directory there when a new first-party tree appears, and draw\nits block.\n\n## Linted idioms (T1–T6)\n\nThe linter pins these; every new brick or arrow must obey them.\n\n- **T1** — a brick's stereotype equals its drawer's stereotype (exempt: `<<ext>>`).\n- **T2** — a drawer's title first line is exactly the directory path.\n- **T3** — numbered **call** arrows carry a `[[file#symbol]]` link; **returns carry no link**.\n- **T4** — the step number is the label's first token: `N ·` for a call,\n `N ⟵` for a return.\n- **T5** — a link's `#symbol` must be declared in the target file.\n- **T6** — returns use `..>` and `⟵`.\n- **T7** — one label grammar for every brick and drawer: `NAME`, then the business\n meaning, then `--` and the members — the `--` only when members exist. Members\n never sit above the line, and a linked `#symbol` must be one of the members\n (enforced by check J, KDV-CI-26).\n\n## The linter\n\n`scripts/tooling/workflow-map/workflow-arrows-lint.mjs`, pure `lintDiagram({ text, pumlDir, repoRoot })`.\nRun it from the project root (silent, exit 0 when clean):\n\n```\nnpm run workflow-arrows:lint\n```\n\nIt also runs in CI (`validate.yml`, KDV-CI-12) and is pinned by\n`tests/unit/workflow-arrows.test.js`, so `npm test` covers the map too.\n\nChecks:\n\n- **(A)** drawer coverage both ways — declared drawers ↔ the configured first-party dirs.\n- **(B)** file coverage both ways for code drawers — every file is exactly one brick,\n every brick link exists, no file drawn twice.\n- **(C)** every `[[url]]` resolves relative to `docs/`.\n- **(D)** a link's `#symbol` is declared in the target file.\n- **(E)** step numbers are exactly `1..N`, unique and contiguous.\n- **(F)** a brick's stereotype equals its drawer's (T1).\n- **(G)** a numbered **call** to a module brick carries a `[[file#symbol]]` link;\n a numbered **return** carries none (T3).\n- **(I)** a drawn edge between two **module** bricks is a real import in one\n direction (KDV-CI-24): the linter builds the first-party import graph over\n `scripts/` + `input/` (static `from`, side-effect `import`, dynamic `import(...)`;\n relative specifiers resolved to `.mjs`/`.js`), and an edge whose two `.mjs`/`.js`\n bricks never import each other is drift. A **by-path** spawn (the engine injects\n `input/controllers/*` by path) or a **dynamic** call is a legitimate false\n positive — mask it with `@lint-ignore`. Non-modules (`.css`/`.svg`/`.png`/`.hbs`/\n `.json`) and unresolved links are other checks' business.\n- **(J)** every brick/drawer label follows one grammar (KDV-CI-26, T7): at most\n one `--`; the lines above it (besides the NAME) are business meaning, never\n members; a `--` has a meaning line above it and members below it; and a brick\n whose link carries a `#symbol` must list that symbol among the members below\n the line. The old `NAME / members / -- / meaning` shape is drift.\n- **(P1)** every arrow carries a process colour from the palette, or the\n structural grey (no colour, or an unknown colour, is drift).\n- **(P2)** a numbered step carries a process colour (never the structural grey)\n and the process rank is non-decreasing in draw order — steps grouped by process.\n- **(P3)** every non-exempt brick is reachable from an actor by the drawn arrows\n (dashed included) — no orphan bricks.\n- **(M)** the `@lint-ignore` block is well-formed (see below) — a bad mask is\n itself drift.\n\nP1–P3 are pinned independently of the hand-drawn map by synthetic diagrams in\n`tests/unit/workflow-arrows.test.js` (KDV-CI-22).\n\n### Suppressing a false positive (`@lint-ignore`)\n\nSome drawn edges are legitimately not imports: a `by-path` controller is spawned\nby path, a call is dynamic, a transitive chain is elided, an artifact is no\nmodule. A mask suppresses ONLY such a **cheap-validation** problem — the codes\n`I`, `P1`, `P2`, `P3` — and never a structural one (A–H, or the block's own `M`).\n**A mask is proof of a false positive, never a way to hide a structural gap.**\n\nEmbed the mask block in the `.puml` itself:\n\n```\n' @lint-ignore\n' [I] IGN -> CTRL_DUMPS # by-path: spawned by path, not imported\n' [P1] arrow * # transitive: the glue arrow elides the chain\n' @end\n```\n\n- Only lines between `@lint-ignore` and `@end` are read; a `'`-line with no\n `[CODE]` is a plain comment.\n- The glob matches the problem key `CODE: subject` gitignore-style: `*` any run,\n `?` one char, `!` un-ignores a key matched earlier (last match wins).\n- Every rule MUST carry `# <mechanism>: <reason>`; the mechanism is one of\n `by-path`, `dynamic`, `transitive`, `non-module` — the closed vocabulary that\n makes a mask assert *why* it is a false positive.\n- The guards are themselves `M` problems, never suppressible: a mask targeting a\n structural code, a mask with no reason, an unknown mechanism, an unused mask,\n or an `@lint-ignore` without `@end`.\n- Suppressed problems are reported, not hidden: the CLI prints\n `suppressed N (see @lint-ignore)` and exits 0 only when nothing unsuppressed\n remains. After a real code fix, remove the mask so it does not go unused.\n- Maskable codes are pinned as `MASKABLE_CODES` in the linter (`I, P1, P2, P3`;\n `I` is the module-edge check of KDV-CI-24).\n\n## When lint fails\n\nA red lint is the drift alarm, not an obstacle. Do this:\n\n1. **Read this file and the `DRIFT` lines** — they name what drifted.\n2. **Fix the diagram** so drawers, files, links, symbols, stereotypes and numbers\n match the code: the code is the truth, the map follows it.\n3. If the code change was **unintended**, fix the code instead.\n4. **Never** weaken or skip the check, and never erase bricks to silence it.\n5. **Re-render** the `.svg` after editing.\n\nThe linter prints this file's path in the guidance for exactly this reason.\n\n## Maintaining & rendering\n\n**Editing the `.puml` is not finished until `docs/workflow-arrows.svg` is re-rendered\nand committed in the SAME change** — source and render are one artifact; an\nunrendered `.puml` edit is an incomplete edit.\n\nRender (Smetana layout — no GraphViz needed):\n\n```\njava -jar <plantuml.jar> -tsvg -charset UTF-8 docs/workflow-arrows.puml\n```\n\nThen confirm the `.svg` holds no `Syntax Error`. Add the hover block (it is part of\nthe render, not an extra) and commit both files:\n\n```\nnpm run workflow-arrows:svg\n```\n\n- Links are relative **to `docs/`**:\n `[[../scripts/lib/build.mjs#buildProject <label>]]`. The label follows the URL\n after a **space** — not `{}`. No absolute paths, no `file://` (the IntelliJ plugin\n opens neither).\n- `====` is gone from drawers: one grammar everywhere — `NAME` → what it does →\n `--` → members; `--` draws the divider inside a brick and exists only when\n members follow (T7, check J).\n- **Add a module → add a brick** — otherwise a code drawer fails file coverage.\n- `npm run workflow-arrows:svg` injects the **hover block**: the whole arrow lights up\n (line, head, label) in the `.puml`'s `skinparam pathHoverColor` colour, and lingers\n ~5s after the pointer leaves — so a long arrow stays lit while you scroll to its far\n end. It shows only in a CSS-capable viewer (a browser), never in PNG or an IDE\n preview. The committed `.svg` must carry the block (pinned by KDV-CI-21).\n- **Commit `.puml` and `.svg` together** — source and render are one artifact.\nAGENTS.mdTwo touch points in the startup digest. First, a principle, so the rule is one of the project's values\nand not a footnote:
\n9. **Extend the flow, don't route around it.** A feature is woven into the existing flow that\n owns its concern — never a parallel path that bypasses the common step. Read the flow map\n (`AGENTS/workflow-arrows.md`) before changing a part.\nThen a structural pointer in the \"Structure\" section, next to the code map:
\n### Flow map — `docs/workflow-arrows.puml` (AGENTS/workflow-arrows.md)\n\nThe linted map of the code tree and the numbered cross-cutting flow. Read it before\nchanging a part so you extend the flow that already exists instead of adding a parallel\npath around it. How to read / maintain / lint / render — **AGENTS/workflow-arrows.md**;\nthe drift alarm is `npm run workflow-arrows:lint` (silent, exit 0 when clean).\nAnd the command, in the digest's command list:
\nnpm run workflow-arrows:lint # workflow-map drift alarm (silent when clean)\nAGENTS/requirements.mdThe registry's own protocol gains the flow-impact subsection, so the person (and agent) maintaining the\nregistry knows why the field exists and how the exemption is anchored:
\n## Flow impact — every requirement names its process\n\nEvery row carries a `flow:` field naming the business process(es) it extends or\ntouches, so the designer consults the workflow map (`docs/workflow-arrows.puml`)\nBEFORE writing code. The value is one of:\n\n- `none` — the requirement touches no business process;\n- a comma-separated list of palette process names — `PR review`, `Publish`,\n `Notify`, `Consume`, `Engineering` (the palette is exported by the map linter:\n one truth per entity);\n- `legacy` — the frozen pre-hook exemption (see below). Never write it on a new row.\n\n`npm run req` enforces it: a row without a valid `flow:` fails, and any row whose\n`flow:` value is unknown fails.\n\n**The exemption set is frozen in code.** Rows that predate the hook carry `flow:\nlegacy`; `req-coverage.js` exports `LEGACY = { count, sha256 }` — the anchor of\nthat exact set (count + sha256 of the sorted IDs). `npm run req` recomputes the\nactual legacy set and fails if it differs, so a new requirement cannot dodge the\nhook by writing `legacy`: that grows the set and trips the anchor. Changing the set\nis a deliberate, reviewable act — edit `LEGACY` in `req-coverage.js` only when the\nchange is intentional.\n{\n \"scripts\": {\n \"workflow-arrows:lint\": \"node scripts/tooling/workflow-map/workflow-arrows-lint.mjs\",\n \"workflow-arrows:svg\": \"node scripts/tooling/workflow-map/workflow-arrows-svg.mjs\",\n \"req\": \"node scripts/tooling/quality-gates/req-coverage.js\",\n \"validate\": \"node scripts/tooling/quality-gates/validate.mjs\",\n \"test\": \"vitest run\"\n }\n}\nRendering the .svg (Smetana layout — no GraphViz needed) is a manual step you run after editing the\n.puml, then the injector:
java -jar <plantuml.jar> -tsvg -charset UTF-8 docs/workflow-arrows.puml\nnpm run workflow-arrows:svg\nCommit the .puml and the .svg together — source and render are one artifact. An unrendered\n.puml edit is an incomplete edit (the convention doc says this, and it is the one rule that keeps\nthe two files from diverging).
This was built, not designed in one pass; the failures are part of the recipe.
\nI failed on the page → copy edge, which the code\ndid not import. The lesson is the check itself: an agent cannot catch a confidently-wrong edge by\nreading one file, so the map needs a mechanical truth check, not a promise to keep it updated.P3 exists because \"draw something\" without a flow produces decoration.-- and meaning below; half did the reverse. It was invisible to humans and confusing to a\nreader, so check J was added and the whole map transformed in one pass — a big mechanical edit\nthat a test then pinned.by-path/dynamic/transitive/non-module) and the\n\"unused mask is an error\" guard exist to make a mask a checkable claim.experimental, not claimed as a measured outcome.Rejected alternatives, recorded so you do not re-derive them:
\nI is one-directional: a drawn module-to-module edge must be a real import, not every\nimport must be drawn..mapignore of whole files: it removes the discipline. The mask is narrow\n(I, P1–P3), must name a mechanism, and reports itself.legacy. The frozen count + sha256 anchor makes that a loud, reviewable edit.From <project>:
npm run workflow-arrows:lint # the map matches the code (silent, exit 0 when clean)\nnpm run req # the registry: IDs covered AND every row names its process\nnpm test # includes the synthetic diagrams pinning P1-P3\nTo watch the mechanism bite, do the two red tests by hand:
\n.puml between two module bricks that do not import each other, and run\nnpm run workflow-arrows:lint — check I fails and names the edge (the map is lying).flow: field and run npm run req — it fails and names the row; add\nflow: legacy and it still fails (the anchor moved).AGENTS.md digest and the STATE.md checkpoint that the flow map hangs\noff.What it is. A reproduction-ready way to give an agent-driven repository a picture of its own\narchitecture that the agent will actually look at and can trust. It is two halves that only work\ntogether: a PlantUML flow map with one fixed convention (a drawer per code directory, a brick per\nmodule, one label grammar, every arrow coloured by the business process it belongs to, the numbered\nflow of cross-cutting steps), and a linter that checks the map against the code tree — so the map\nis either true or the build goes red. On top of that, a design-time hook in the requirements\nregistry makes every new requirement name the business process it touches, which forces the map to be\nconsulted before code is written. Every source file — the linter, the SVG hover injector, the\ncoverage script, the convention doc and the example map — is inlined.
\nWhy you would want it. Agents do not \"forget\" code they can read; they forget the shape of a\nsystem across sessions. Working on one file, the cheapest line to the goal often cuts across a shared\nstep, and that shortcut is locally green and globally a second source of truth that drifts. A diagram\nsitting in the prompt does not fix this: it rots, and a rotting map teaches the agent to ignore maps.\nThis setup answers the three questions that make a map useful to a machine: is it cheap to read\n(one grammar, helicopter altitude — not every plumbing edge), is it true (linted against the real\ncode, including a check that a drawn module-to-module edge is a real import), and is it used (a new\nrequirement cannot be written without naming the process it extends, so the map is opened first).\nThe failure that convinced me it works: the import check caught a drawn edge the map claimed and the\ncode did not have — the map was lying, and the linter said so.
\nWhat to watch out for. This is the companion to The requirements machine\n(https://kodavr.xyz/dumps/2026-09-18-opencode-requirements-machine/): the registry, the flow:-style\ndesign-time hook and the AGENTS.md digest come from there — apply it first, because the hook lives\ninside its coverage check. It is self-tested on one repository, not community-tested, and the\nprocess palette, drawer list and test runner are placeholders you set for your project. The\nhonest limit: the map provably matches the code (the linter is executable and pinned by tests), but\n\"the agent therefore designs better\" is the intended effect — designed for, not yet measured — which\nis why this is flagged experimental. Honesty labels: generated_by: agent, human_review: minimal,\ntrust_level: self-tested. Personal data was removed — see REDACTIONS.md.
(This is the human door into the raw dump. The body stays machine-first.)
\n" }