From 7b238e401c1ef947361ed232c037cf0198991940 Mon Sep 17 00:00:00 2001 From: Danijel Martinek Date: Wed, 13 May 2026 17:02:39 +0200 Subject: [PATCH] docs(architecture): strip Plan-9/superpowers refs from HTML + wire orphan explainers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes the last two staleness threads from the docs audit: 1. data-flow-explainer.html had four "Plan-9" / "post-Plan-9" references in the masthead, lede, fix-up bullet, and bindDevSeed blurb. Stripped — the architecture is now just "vertical-feature". No content changes beyond the noun rename. 2. audit-and-compliance-explainer.html had a footer link to ../superpowers/specs/2026-05-11-audit-and-compliance-design.md (archived to .archive/ earlier). Replaced with a link to ADR-018, which is the durable design record. 3. data-flow-explainer.html + di-explainer.html were inter-linked with audit + conformance explainers, but had no markdown entry point — they were orphans from any guide or architecture doc. architecture/overview.md gains a new "Interactive explainers" section listing all four single-file HTML walkthroughs with one sentence each, so they're discoverable from the documented entry point. The four pages already cross-link to each other. Final state (verified by repo-wide grep): zero "Plan-N" / "Phase-N" / "docs/superpowers/" references in docs/ (excluding .archive/ which is gitignored). Legitimate `superpowers:brainstorming` skill refs in agent-first-workflow-and-conformance.md are preserved — those reference an external plugin, not a repo path. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/architecture/audit-and-compliance-explainer.html | 2 +- docs/architecture/data-flow-explainer.html | 8 ++++---- docs/architecture/overview.md | 11 +++++++++++ 3 files changed, 16 insertions(+), 5 deletions(-) diff --git a/docs/architecture/audit-and-compliance-explainer.html b/docs/architecture/audit-and-compliance-explainer.html index 46aa301..3a97d82 100644 --- a/docs/architecture/audit-and-compliance-explainer.html +++ b/docs/architecture/audit-and-compliance-explainer.html @@ -1517,7 +1517,7 @@ footer .colophon { vertical-feature-spec.md overview.md dependency-flow.md - 2026-05-11 · audit design spec + ADR-018 · audit & compliance
Guide
diff --git a/docs/architecture/data-flow-explainer.html b/docs/architecture/data-flow-explainer.html index a0d1ce4..30f9ae0 100644 --- a/docs/architecture/data-flow-explainer.html +++ b/docs/architecture/data-flow-explainer.html @@ -1476,12 +1476,12 @@ footer .colophon {
template-vertical / architecture / explainer - 2026-05-06 · post-Plan-9 + 2026-05-06

A guided tour
of one feature's
data flow.

-

An internal explainer for the post-Plan-9 architecture — written for the engineer who built it and just wants the mental model in one place. Click through the request flow, flip the DI binding mode, swap features. Real code from this repo, not a tutorial.

+

An internal explainer for the vertical-feature architecture — written for the engineer who built it and just wants the mental model in one place. Click through the request flow, flip the DI binding mode, swap features. Real code from this repo, not a tutorial.

@@ -2003,7 +2003,7 @@ footer .colophon {
  • Per-feature ownership — auth's errors don't leak into blog
    • Cons
      -
    • Every constructor must set this.name (R6) — easy to forget, was the systemic Plan-9 fix-up
      • +
    • Every constructor must set this.name — easy to forget, and the cause of opaque error names when omitted
    • InputParseError is duplicated per feature (~6 lines × 5) — by design, but feels redundant
    • Adding a new error class = update the feature's procedures.ts map too
    @@ -2210,7 +2210,7 @@ footer .colophon {
    di/bind-dev-seed.ts

    Dev-seed binder

    -

    bindDevSeed<F>(ctx: BindContext) — unbinds the empty mock, rebinds a populated mock (post-Plan-9).

    +

    bindDevSeed<F>(ctx: BindContext) — unbinds the empty mock, rebinds a populated mock.

    Pros
    • Dev mode shows realistic data without Payload running — design review, storybook, offline work all just work
      • diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 0f019d5..8e23728 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -133,3 +133,14 @@ Each feature owns its own InversifyJS `Container` + symbol table. No shared symb ## Spec reference `docs/architecture/vertical-feature-spec.md` is the canonical design. + +## Interactive explainers + +Four single-file HTML walkthroughs sit alongside this overview. They're self-contained (no build step) and best viewed locally in a browser. + +- [`data-flow-explainer.html`](./data-flow-explainer.html) — request and event flow through one feature, with the DI binding mode toggle and feature swap controls. +- [`di-explainer.html`](./di-explainer.html) — the full container + symbols + binder lifecycle. +- [`feature-conformance-explainer.html`](./feature-conformance-explainer.html) — companion to ADR-020-adjacent conformance design (also linked from `agent-first-workflow-and-conformance.md` and `runbook.md`). +- [`audit-and-compliance-explainer.html`](./audit-and-compliance-explainer.html) — companion to ADR-018 (also linked from `dependency-flow.md` and `guides/audit-and-compliance.md`). + +The four pages cross-link to each other; entering any of them surfaces the others.