stack/skills/ms-archify/SKILL.md

name, description, disable-model-invocation

name	description	disable-model-invocation
ms-archify	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.	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 " 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.