jason.woltje
3ea385223e
ms-archify (evidence-based architectural mapping), ms-sdlc, ms-proactive-agent, ms-goal, ms-grill-me, ms-frontend-design.
303 lines
16 KiB
Markdown
303 lines
16 KiB
Markdown
---
|
|
name: ms-archify
|
|
description: Architectural mapping with evidence — trace a system as built or as planned, render it with Archify, get it reviewed by an independent seat, and run gap analysis between the two.
|
|
disable-model-invocation: false
|
|
---
|
|
|
|
# Mosaic Archify
|
|
|
|
A map is a claim. The code (as built) or the plan document (as planned) is
|
|
the truth. This skill is the method that keeps the two aligned so that a
|
|
picture can be trusted by someone who did not draw it. Archify is the
|
|
renderer; it proves that a page is well formed. It proves nothing about
|
|
whether the edges are true. That part is human work, done the way described
|
|
here.
|
|
|
|
Use this skill for: an as-built map of a subsystem, a planned map of a design
|
|
document, a gap map between the two, an extensibility review of a roadmap,
|
|
or any inspection where the deliverable is "here is how the values actually
|
|
flow, with citations."
|
|
|
|
Do not use it for a sketch nobody will review. A map without a reviewer is a
|
|
drawing, not evidence.
|
|
|
|
## Roles
|
|
|
|
Three seats, never collapsed into one:
|
|
|
|
- **Author** traces, specifies, renders, and submits. The author never
|
|
approves their own map.
|
|
- **Reviewer** is a different agent seat. The reviewer opens every citation
|
|
and rules per edge: confirmed, wrong, or unsupported. The reviewer does not
|
|
fix the map and does not draw.
|
|
- **Lead** (the human) accepts or sends back. Design decisions are the
|
|
lead's; the lane records facts and recommendations, never rulings of its
|
|
own.
|
|
|
|
Other agents are sources, not seats. Ask the developer who built the thing
|
|
for facts ("where does this value cross into the container?"), record the
|
|
answer with a timestamp, and cite the file they point you to, not their
|
|
message. Two brains beat one; one brain deciding it is in charge is the
|
|
failure mode.
|
|
|
|
## Lane layout
|
|
|
|
One directory per mapping effort, under the fleet lanes tree:
|
|
|
|
```
|
|
METHOD.md the cycle and its amendments (this skill, specialised)
|
|
TASKS.md monotonic ledger: proposed -> accepted -> in-progress -> done / declined
|
|
COMMS.md append-only record of every message sent and received, with timestamps
|
|
comms/ full bodies of review requests and verdicts
|
|
DECISIONS.md the lead's rulings, by question number
|
|
FINDINGS.md what the tools were measured to do, and adoption rules
|
|
spec/ <map>.architecture.json and <map>.EVIDENCE.md
|
|
out/ delivered HTML, deliver.json, visual-check.json, screenshots
|
|
run/ live preview state: pid files, logs, README.md naming the current spec
|
|
```
|
|
|
|
Rules for these files:
|
|
|
|
- TASKS.md is monotonic. A task is `done` only with a deliver receipt and a
|
|
reviewer verdict from a seat other than the author, both cited in the line.
|
|
- COMMS.md is append-only. A mistake in an entry is corrected by a new
|
|
entry that names the old one. Never edit history.
|
|
- Messages to agents carry no secrets. Neither do files in the lane.
|
|
|
|
## The cycle
|
|
|
|
1. **Scope.** Name the map, its kind (as-built or planned), and the source
|
|
of truth: a commit SHA of the repository, or a plan document at a commit.
|
|
Write the SHA into the spec's subtitle. Never cite a working tree without
|
|
a SHA.
|
|
2. **Trace.** Follow values, not names. Start at an input (a file, a flag,
|
|
an environment variable) and record every hop until it takes effect.
|
|
Write the trace as a table before drawing anything. Rules below.
|
|
3. **Specify.** One component per real thing. One edge per hop that crosses
|
|
a component boundary. The full citation for each edge and each gap goes
|
|
in the evidence ledger; the map carries short conclusions and the ledger
|
|
hash.
|
|
4. **Render.** `validate` until clean, `deliver` for the receipt,
|
|
`visual-check` for the browser gate. Show the candidate on the lane's
|
|
live preview, nowhere else.
|
|
5. **Review.** Send the reviewer the spec hash, the ledger hash, the
|
|
artifact hash, and the receipt. The reviewer replies per edge in
|
|
COMMS.md. A verdict is either APPROVED or NOT APPROVED with the list of
|
|
failed items; there is no partial approval.
|
|
6. **Verdict.** The lead accepts or sends back. Accepted maps get a TASKS.md
|
|
line with the receipt and the verdict as evidence.
|
|
7. **Re-derive on change.** Any commit that touches a cited file
|
|
invalidates the map. Re-trace the affected edges only; do not redraw.
|
|
|
|
## Tracing rules (where every past review round was lost)
|
|
|
|
- **Name the boundary before the citation.** Every hop crosses a write
|
|
(`writeOnce`, `mv`, `mkdir`), an exec (`exec`, `spawnSync`,
|
|
`docker compose run`), or an env interpolation (`${VAR}` in compose,
|
|
`export`). The citation must include the line where the boundary is
|
|
crossed, not only the line where the value is computed. Six review rounds
|
|
on one map found zero false claims and six citations one hop short.
|
|
- **Cite every hop.** Definition, transformation, and write or exec. A
|
|
citation that replaces an earlier one keeps the hop the earlier one proved.
|
|
- **Distrust names.** A node called "policy" is a label. `MOSAIC_TOOLS` set
|
|
on one line and read by the adapter on another is a fact.
|
|
- **Prefer receipts the system already writes**: run records, env files,
|
|
exit codes, logs. If a hop leaves no receipt, that is itself a finding and
|
|
belongs on the gaps card.
|
|
- **External behaviour is HYPOTHESIS.** A claim about what another program
|
|
does (a harness reading a file, a provider API, a bind mount's inode
|
|
behaviour) that no repository file proves is written with the word
|
|
`HYPOTHESIS` in the item. Measuring it in a container image or on the host
|
|
turns it into a measurement, recorded in its own ledger section; it does
|
|
not become a repository fact. The reviewer rules on whether the label is
|
|
honest, not on the claim.
|
|
- **"Could not trace" beats an expected edge.** When you cannot find where a
|
|
value crosses a boundary, write that down and stop. Never draw the edge
|
|
you expect to exist.
|
|
- **Never read secret values.** Auth files, tokens, and key material are
|
|
reported as present or absent, with mode and owner. Tests that need a
|
|
credential are run by the seat that owns it, or with a throwaway value.
|
|
|
|
## Planned maps and gap maps
|
|
|
|
- A plan document is cited like code: `<file>:<line>` at a commit. A plan
|
|
that exists nowhere on the host cannot be mapped; decline the task and say
|
|
so in TASKS.md.
|
|
- Every planned map carries an **Extensibility test** card: each path a new
|
|
harness, provider, or surface would touch, by file. The map passes only
|
|
when no listed path is a one-off script.
|
|
- A **gap map** puts as-built and planned side by side. Use
|
|
`archify compare architecture <base.json> <head.json>` with the as-built
|
|
spec as base. Each gap item cites both sides: what the code does at its
|
|
commit, what the plan says at its commit. A gap with no plan-side citation
|
|
is a finding about the plan, not a gap.
|
|
- When a surface must not exceed another (a GUI must not do what the CLI
|
|
cannot), that rule is a card on the map of the governing surface, cited to
|
|
the decision that set it.
|
|
|
|
## The evidence ledger
|
|
|
|
Cards cannot hold evidence. Measured: three 90-character items per card
|
|
overflow Archify's containment gate at 1440x900; the same page with no cards
|
|
fits exactly; Archify's own example passes with two or three items of about
|
|
35 characters. So:
|
|
|
|
- The ledger lives in `spec/<map>.EVIDENCE.md`, next to the spec, and is
|
|
the trace table itself, written once. It is part of the reviewed
|
|
candidate: a verdict names the spec, ledger, and HTML hashes, and a changed
|
|
ledger is a new revision. Its header names the map, the commit or plan
|
|
revision under review, and the ledger's own revision number, never the
|
|
spec hash (the spec contains the ledger hash, so that would be circular).
|
|
- Sections: the path as built (numbered), one item per edge (`E1..En`), one
|
|
per gap (`G1..Gn`), findings the map exposes, a `Plan findings` section
|
|
(`P1..Pn`) on gap maps for things the code does that the plan does not
|
|
mention, and anything measured outside the repository (`X1..Xn`). Every
|
|
item is `<file>:<line>` at the named commit. Every X item names the
|
|
environment it was measured in (image tag, or host and date) so it can be
|
|
repeated. Revisions are marked in place (`[rev 2]`) and the markers stay
|
|
after approval, because the approved ledger is frozen by its hash.
|
|
- Cards carry short conclusions, about three items of about 35 characters
|
|
as a guideline; the visual-check gate is the rule. The map's subtitle
|
|
points at the ledger.
|
|
- **Binding**: a fixed `Evidence ledger` card, same three items (ledger
|
|
path, full 64-character SHA-256, item counts) in the same position on
|
|
every map. The deliver receipt hashes the spec and the HTML, so it covers
|
|
the ledger transitively; a changed ledger changes the spec hash and voids
|
|
the receipt. The reviewer runs `sha256sum` on the ledger and compares it
|
|
with the item in the spec JSON (not the HTML, which the receipt already
|
|
binds). Never truncate the hash; change the layout instead. A ledger that
|
|
is not bound is not part of the candidate, and a reviewer is right to
|
|
refuse it on procedure even when every item is confirmed. When a wrapper
|
|
later mints a combined receipt, the card stays: the receipt is for
|
|
tooling, the card is for a human with a terminal.
|
|
- **Re-derive check**: the ledger is the authoritative list of cited paths.
|
|
At the start of every map and before every verdict the author runs
|
|
`git diff --name-only <commit>..HEAD` against those paths and records the
|
|
result in COMMS.md. A stale map keeps its status with an appended
|
|
"stale since <sha>" note; the re-trace arrives as the next revision.
|
|
- **Re-packaging an approved map** under a new render rule is not a
|
|
re-trace: move the confirmed citations into the ledger unchanged, bump the
|
|
revision, keep the previously approved output on disk, append a note to
|
|
the task line. The reviewer verifies the binding and that the ledger items
|
|
equal the approved citations, then writes a new verdict; the old verdict
|
|
stands for what it named.
|
|
|
|
## Archify, as measured
|
|
|
|
Facts about the renderer that cost time to learn. Verify against the pinned
|
|
version before relying on any of them.
|
|
|
|
- Run from a pinned checkout at a recorded commit with
|
|
`ARCHIFY_UPDATE_CHECK_DISABLED=1`. The update checker does a network GET
|
|
and writes cache below `~/.cache`; both stay off. No updater state outside
|
|
the data root.
|
|
- Commands used: `validate architecture <spec> --json`,
|
|
`deliver architecture <spec> <out.html> --quality showcase --json`,
|
|
`visual-check <out.html> --json`, `preview architecture <spec>`,
|
|
`compare architecture <base> <head>`. Type is always `architecture` for
|
|
these maps.
|
|
- The deliver receipt runs nine checks: single SVG, finite SVG, orthogonal
|
|
arrows, label route clearance, relationship crossings, relationship
|
|
corridors, container border runs, route rhythm, legend clearance. Then a
|
|
composition and desktop readability pass: every text node must project to
|
|
at least 6px at a 1440 viewport (scale 930/1200). Long sublabels on small
|
|
nodes fail this; shorten the text, do not widen the map.
|
|
- `visual-check` opens a real browser and requires the page to fit without
|
|
scrolling at 1440x900, 1600x1000, 1920x1080, and 2048x1320. It needs Chrome
|
|
on the host. Keep browser checks host-side; do not add a browser to
|
|
workers.
|
|
- Page height at 1440 is header plus a fixed diagram block plus one row of
|
|
cards, and the row is as tall as its tallest card. Measured: a title over
|
|
about 30 characters wraps to a second line (31px); a card item over about
|
|
34 characters wraps (16px per extra line). Three cards fit when the title
|
|
is one line and no card has more wrapped lines than the ledger card,
|
|
whose 64-character hash always wraps once. When the gate fails by less
|
|
than 50px, shorten the title and the longest items; do not remove cards.
|
|
When it fails by hundreds of pixels, evidence is on the cards and belongs
|
|
in the ledger.
|
|
- The canvas is a 1200x720 viewBox. A component plus the boundary padding
|
|
(36) must stay inside it or the boundary clips.
|
|
- Connections: set `fromSide` and `toSide` and let the router choose the
|
|
path. Explicit `via` waypoints disable automatic port spread, snap ports
|
|
to side midpoints, and require the final segment to be perpendicular to
|
|
`toSide`; they cause more overlaps than they fix. Place labels with
|
|
`labelAt` or `labelSegment` plus `labelDy`. An edge shorter than about
|
|
40px cannot carry a label.
|
|
- Source-evidence links render only for GitHub URLs. For any other forge,
|
|
citations are text in the ledger; do not imply verified links.
|
|
- The preview server binds a random loopback port on every start. If a LAN
|
|
proxy fronts it, restart the proxy with the new port and update
|
|
`run/README.md`. `/state` on the preview returns the generation counter
|
|
and the last verified hash; report both when you switch the candidate.
|
|
|
|
## Showing the candidate
|
|
|
|
The lead reviews on the lane's live preview and on nothing else. Do not
|
|
publish the map through another channel because it is convenient. Changing
|
|
the review channel without being asked is the fastest way to lose the
|
|
lead's trust in the whole cycle. When a new revision is ready: restart the
|
|
preview on the new spec, restart the proxy, update `run/README.md`, report
|
|
the URL and the generation number.
|
|
|
|
## Review protocol
|
|
|
|
Request body (in `comms/`, referenced from COMMS.md):
|
|
|
|
- Map name, revision number, commit under review.
|
|
- SHA-256 of the spec, the ledger, and the delivered HTML; the deliver
|
|
result (checks passed) and the visual-check result.
|
|
- For a re-submission: every finding from the last verdict and what changed
|
|
for it, by item number.
|
|
- The live preview URL and generation.
|
|
|
|
Reviewer conduct: open every cited location at the named commit; run the
|
|
suites that touch the mapped area; confirm, reject, or mark unsupported per
|
|
item; check the ledger hash against the card; never read a secret value;
|
|
reply in COMMS.md with the verdict and the failed items only. A procedural
|
|
failure (an unbound ledger, a missing receipt) is reported as NOT APPROVED
|
|
even when the content is confirmed, and the reply says which it is.
|
|
|
|
Author conduct on a verdict: fix the failed items in the ledger and spec,
|
|
bump the revision, re-deliver, re-check, and resend the whole candidate.
|
|
Never argue an item in the reply; if the reviewer is wrong, the citation
|
|
that proves it goes in the ledger.
|
|
|
|
## Sending to other agents
|
|
|
|
Use the fleet send tool (`ms-communications`). Its exit codes: 0 delivered,
|
|
1 target not found, 2 submitted but unconfirmed, 3 usage. An rc of 2 is not
|
|
a delivery. Capture the target pane and look for your text before recording
|
|
delivery; a target mid tool call will not have taken it, and the record must
|
|
say "unconfirmed" until it did. Never record rc=0 from memory.
|
|
|
|
## Adoption rules for the renderer
|
|
|
|
From the isolated evaluation, still binding until a wrapper exists:
|
|
|
|
- Pin an exact release and its SHA-256; verify both before use.
|
|
- Update checks off, network off by default.
|
|
- Repository mounted read-only; writes only to the workspace for the spec,
|
|
ledger, HTML, and receipts.
|
|
- `validate` and `deliver` receipts required; `visual-check` on the host
|
|
review path when browser evidence is asked for.
|
|
- Fail closed on a missing package, identity mismatch, failed validation,
|
|
or an unsupported source-evidence mode.
|
|
- A generic install-by-copy script is not an import boundary for a
|
|
renderer's codebase. Do not adopt through it.
|
|
|
|
## Definition of done
|
|
|
|
A map is done when all of these hold:
|
|
|
|
1. The spec names the commit or plan revision it describes.
|
|
2. Every edge and gap has a ledger item with `<file>:<line>`, or the word
|
|
HYPOTHESIS, or the words "could not trace".
|
|
3. The ledger hash is on the map and matches.
|
|
4. The deliver receipt passes all checks and the visual check passes on all
|
|
four viewports.
|
|
5. A reviewer seat other than the author has written APPROVED in COMMS.md
|
|
for those exact hashes.
|
|
6. The lead has accepted, and TASKS.md cites the receipt and the verdict.
|
|
|
|
Anything short of that is a candidate, and is described as one.
|