OutlineDriven Architecture diagram
Contract
| Field | Bound contract |
|---|---|
| Trigger | The user asks to visualize an architecture as a self-contained HTML artifact with a hash-bound receipt, or supplies two architecture snapshots for delta comparison. |
| Authority | Reversible local: writes only the HTML artifact and JSON receipt or sidecar; rollback is deleting those files. No remote mutation. |
| Side effect | One HTML artifact and one JSON receipt or sidecar written to disk. |
| Done | Single: frozen schema-validated specification, self-contained interactive HTML artifact, and evidence receipt with all render checks passing. Delta: every comparable element classified into exactly one category, self-contained Before/Delta/After HTML artifact, and sidecar receipt written. |
Mode
Two render modes, discriminated by input count:
- Single (default): one architecture question or scope → schema-validated specification + interactive HTML artifact + evidence receipt.
- Delta: two already-authored architecture snapshots → classify every comparable element as added, removed, changed, or unchanged; render a Before/Delta/After HTML artifact + machine-readable sidecar receipt.
Pick delta when the user supplies both a before and an after snapshot and asks what changed. Otherwise single.
Refusals
- No remote, credential, publish, deploy, or irreversible mutation in either mode.
- No risk assessment, blast-radius estimate, runtime causality claim, or merge recommendation in delta output: the delta describes authored additions, removals, and modifications only.
- No partial artifact delivered as complete; a non-converged run returns blocked with the failing check named.
- No inferred or fabricated repository evidence in single mode; unverified claims are discarded or requested, never assumed.
Inputs
- Single mode: the user's architecture question or scope, any supplied facts, and an optional repository path or checkout.
- Delta mode: two already-authored architecture snapshots (before and after), each a JSON document conforming to the architecture contract; a working directory path for the output artifact and sidecar receipt; an optional label pair for the Before and After columns.
- The architecture schema and common schema that authoritatively type the intermediate specification are part of the workflow, not external skills.
Procedure: single mode
- Receive the user's question and any supplied facts. If a repository is named, bound scope to it before any mutation. Done when: scope is bounded or confirmed unbounded by user intent.
- For every repository-backed claim, verify it against the repository: entrypoints, runtime boundaries, transports, storage, deployment configuration; record origin, revision, blob identifiers, and cited lines. Discard any unverified claim. Done when: every claim is proven or discarded, none inferred.
- Build the typed architecture specification as JSON conforming to the architecture and common schemas. Done when: every component, boundary, relationship, and label is schema-valid.
- Freeze the specification and compute its hash. Done when: hash is recorded.
- Render one self-contained interactive HTML artifact from the frozen specification, all styles, scripts, and data inline, no external network reference, renders with network access unavailable. Done when: artifact is self-contained.
- Run the nine render checks: architecture-schema validation, common-schema validation, self-containment, no-network render, component coverage, relationship coverage, zero composition errors, zero composition warnings, receipt binds hashes. Done when: all nine pass.
- If any check fails, stop and report the failing check; do not widen scope or relax a check. Done when: failure is named or all checks pass.
- Optionally capture bounded visual-check screenshots and a contact sheet; report visual-review status truthfully. Done when: visual-review status is reported.
- Write the JSON evidence receipt binding specification hash, artifact hash, check results, and visual-review status. Done when: receipt is written.
Procedure: delta mode
- Read both snapshots. Validate each independently against the architecture contract (component identity, relationship identity, required fields). Done when: both validate, or the failing snapshot and constraint are named.
- Confirm comparability: each component and relationship carries a stable authored identity. Pair only by stable identity using conservative boundary keys (identity field plus type). Elements lacking stable identity are incomparable; fail closed. Done when: every element is paired or marked incomparable.
- Classify every comparable element into exactly one category: added (after-only), removed (before-only), changed (both, identity matches, ≥1 non-identity field differs), unchanged (both, all fields match). Done when: every comparable element has exactly one classification.
- For changed elements, record before and after field values per differing field. Do not infer cause, direction, or intent. Done when: field-level diffs recorded without inference.
- Assign an honest proof level: full when every element paired by stable identity and all fields compared; partial when any element was incomparable and excluded. State it in the output. Done when: proof level is stated.
- Render one self-contained Before/Delta/After HTML artifact, three sections (Before as authored, Delta as classified, After as authored), all CSS and JavaScript inlined, no external resource. Done when: artifact is self-contained with three sections.
- Write one machine-readable sidecar receipt (JSON): input snapshot identifiers, proof level, per-element classification list, deterministic hash of the classification set. Done when: receipt is written.
- Commit the HTML artifact and sidecar receipt as an atomic pair. If the commit fails, preserve previously trusted outputs and report the commit failure without overwriting them. Done when: pair is committed or failure is reported with prior outputs preserved.
- Assert no risk assessment, blast-radius estimate, runtime causality claim, or merge recommendation in any output. Done when: output describes authored additions, removals, and modifications only.
Failure and recovery
- Schema validation failure (either mode): do not emit the artifact; report the offending field and constraint. Roll back by discarding in-progress work and deleting files already written.
- Composition error or warning (single): re-derive layout from the frozen specification and re-run render checks; do not freeze a degraded delivery.
- Unverified repository claim (single): discard the claim or stop and request evidence; never infer or fabricate.
- Self-containment failure (either): re-inline the resource or stop; never declare self-contained when it is not.
- Render-check failure (single): stop with the blocked result naming the failing check; do not relax checks or widen scope.
- Incomparable inputs (delta): elements lack stable authored identity or boundary keys cannot pair them. Fail closed; report the incomparable element set. No classification emitted for incomparable elements; proof level is partial only if some elements were comparable, otherwise blocked.
- Determinism violation (delta): a second run over the same inputs produces a different classification set. Report the divergence; do not emit a result.
- Atomic commit failure (delta): preserve previously trusted outputs; report the commit error. Artifact and receipt remain on disk but are not marked trusted.
- Partial-result rule (either): no partial artifact or classification is delivered as complete; a non-converged run returns blocked.
Output
Single mode: a frozen schema-validated architecture JSON specification; one self-contained interactive HTML artifact; optionally bounded visual-check screenshots and a contact sheet; a JSON evidence receipt binding specification hash, artifact hash, nine render-check results, and truthful visual-review status. Terminal classification: delivered or blocked.
Delta mode: one self-contained Before/Delta/After HTML artifact; one machine-readable sidecar receipt (JSON) recording input identifiers, proof level, per-element classification, and a deterministic classification-set hash. Terminal classification: every comparable element classified, incomparable inputs failed closed, honest proof level stated, no unsupported risk or merge recommendation asserted.