Skip to content

Specification: Storybook-for-architecture whiteboard MVP #40

Closed as not planned
2 of 6 issues completed
Closed as not planned

Description

@jdylanmc

Current status (2026-09-19)

Current ready-for-agent specification and next implementation scope. Production story integration, @topo/diagram-core, story indexing, bundle output, and story-authoring skills are not landed. The existing serve command is a reuse seam, not completed composed-site delivery. The lint prerequisite / AC-14 is now delivered by PR #39. Acquisition and U-4/U-5 decisions remain settled; no implementation child tickets have yet been published.

Evidence: PR #39; packages/cli/src/main.ts; #40 FR-01 through FR-09.

Original issue text is preserved below. This update records current delivery status without erasing historical decisions. #40 governs the next architecture-story MVP; it does not imply that the broader historical roadmap is implemented.


Storybook-for-architecture whiteboard MVP: Requirements specification

Source and alignment

Discovery artifact: .joe-mode/discovery-result.json, revision 4, ALIGNED.
Owner: singleton backlog-manager Discovery role (agent d72faa16), under PM 4eb11882, in a human-started Joe-mode session. The .joe-mode/ directory is git-excluded (.git/info/exclude), so this specification restates every decision it depends on rather than relying on that path.

Human alignment evidence: direct conversation with the repository owner on 2026-09-16 (10:03–16:32 -04:00). Verbatim answers are preserved in discovery-result.json#humanAlignment for D1, D2, D3, D4, the licensing-notice question, and grounding conflicts C1, C2, C3.

Supporting sources:

  • Planning anchor Plan agent-authored architectural whiteboards #35 (decision label) and its comment pinning the preserved packet at merge 8643d83e06ccbb34aa1e1ceb088039a637fb2562.
  • Preserved POC packet: experiments/archify-wrapper/{README,VISION,FINDINGS,PROVENANCE,PLAN}.md.
  • Implementation grounding read from main on 2026-09-16 (discovery-result.json#groundingEvidence, items G-1…G-6).
  • Prior chart artifact .joe-mode/chart-result.json.

Derivation statement: this specification derives from Discovery revision 4 only. Routes proposed in revisions 1–2 (pinned-commit fetch, vendored subtree, doc-gating CI, staged hosted preview) were superseded by the owner's answers and are retained in the Discovery artifact as evidence, not as requirements.

Amendment (Discovery revision 6). After publication, an acquisition investigation produced new evidence that reverses one earlier conclusion: the npm-dependency route of CON-02 is not available, because upstream Archify declares "private": true and has never been published. The vendored route is therefore reinstated on evidence and by explicit owner decision — it is no longer "superseded". U-1 and U-5 are resolved, U-2 is decided, and N-6 is narrowed. Every reversal is marked in place below. Earlier wording is preserved in the Discovery artifact's revisionTrail, not silently rewritten.

Not carried in: anything in #35's "remaining work" list that the owner did not decide. Those stay open, below.


Purpose and outcomes

Problem. The repository can generate a repo-map explorer from a scan, but there is no supported way to author, organise, browse, or package small code-grounded architectural explanations. The POC proved the experience is valuable; it did not produce a product surface. #35 records the gap as a missing authoring workflow, not a missing capability.

Intended outcome. "Storybook is to designers as topo is to architects." Many small, source-anchored architecture documents ("stories"), composed into a generated, categorised, customisable static site that can be served locally and bundled for deployment by its owner.

Product contribution. The owner's words: "Our contribution is the scaffolding and organization around these things." Rendering is an implementation detail behind an adapter.

Success measures. Not quantified by the owner and not invented here. The qualitative bar from alignment: an owner can author stories locally with agent assistance, browse them through one generated landing page, run the site locally, and bundle static output that they can deploy and protect themselves. No latency, bundle-size, or coverage target is agreed. See NFR-06.


Users and scenarios

Actor Goal
Repository owner / engineer Understand and explain their own architecture; review a change through explanations rather than routine implementation reading.
Coding agent (local) Author and evolve stories against the changes in a PR, using topo skills.
Consumer of the bundle Deploy the static output somewhere, optionally behind their own authentication. Out of scope to build, in scope not to block.

S-1 Author a story locally (primary). An engineer, working with a coding agent on a branch, asks the agent to produce or update an architecture story describing the change. The agent writes a .topo document anchored to real source. No hand-authored JSON.

S-2 Browse the corpus. The engineer runs the local site and lands on a generated index that categorises every document in the repository and lets them open any one of them.

S-3 Review a change. A reviewer opens a story, reads the explanation, and drills into the cited source, returning to the wider context.

S-4 Package for deployment. The owner runs a bundle command and obtains plain static files they can upload anywhere (e.g. a blob store) to produce a URL.

S-5 Customise. The owner adjusts categorisation, theming, or composition of their site without forking topo — the Storybook configuration model.

Edge / failure scenarios

  • S-E1 Broken anchor. A story references a file, symbol, or pattern that no longer exists. The failure must be objective and reported, not silently rendered.
  • S-E2 Empty corpus. A repository with no authored stories still produces a coherent site (the generated explorer alone).
  • S-E3 Renderer unavailable. The Archify dependency cannot be resolved or fails to render a document; the build must fail with an actionable message rather than emit a broken artifact.
  • S-E4 Dirty tree. Existing scan/ingest behaviour already distinguishes dirty working trees from committed revisions (packages/cli/src/main.ts). Story authoring must not weaken that distinction.

Functional requirements

FR-01 — Story (authored architecture document)

A story is one small, focused, source-anchored architecture document, committed to the repository.

  • Anchors are (path, symbol, pattern). Renderer line ranges are derived at render time, not stored (carried forward from decision Decided: anchoring rule — (path, symbol, pattern), never line numbers #10; no conflicting evidence found — 5 of 8 POC references were path-only and all 8 passed native Git verification).
  • Stories are authored, distinct from the generated logical-architecture output (packages/cli/src/pipeline.ts, site-bundle.ts) and from .topo cache.
  • Documents carry enough identity to survive incremental agent edits.
  • The durable document contract must not be expressed in a particular renderer's IDs or schema (Plan agent-authored architectural whiteboards #35, ownership boundary).

Source: D1/C-9 Storybook model; #35 "agent authoring and the committed document contract"; CF-1.

FR-02 — Render adapter

Rendering is reached through an adapter boundary.

  • Archify renders authored stories.
  • The existing in-house WebGL renderer (packages/site/src/renderers/webgl.ts) is retained and continues to render the generated explorer.
  • The adapter must let a renderer be replaced, forked, or added without reshaping the scaffolding. The benchmark harness already assumes multiple renderers (benchmarks/benchmark-options.mjs:3, defaultRenderers = ["webgl"]).
  • Archify is reached only through @topo/diagram-core (FR-09). The adapter boundary and the package boundary together are what make the future swap to upstream's published package cheap.

Source: C2 answer ("I suppose we can keep that"); C-10; FC-1.

FR-03 — Generated landing page

A generated landing page is the product front door.

  • It categorises and showcases all documents in the repository.
  • It indexes both document kinds: authored stories and the generated explorer. The explorer becomes an entry in the index rather than a separate application.
  • It is generated from what is committed; it is not hand-maintained.

Source: D1 answer — "we need a 'landing page' that categorizes up and shows off all our archify documentation"; C2 answer.

FR-04 — Serve command

An npm/CLI command runs the composed site locally on a port.

  • topo serve [root] --port already exists and serves .topo/cache/site (default port 4173, packages/cli/src/main.ts:84-96). This requirement is satisfied by composing the new site into the existing command, not by adding a second server.
  • Local serving is the authoring feedback loop for S-1.

Source: D4 answer — "some sort of npm command to 'launch the site' which is like a static site running on a port"; grounding G-1.

FR-05 — Bundle command

A new npm/CLI command emits the site as deployable static files.

  • Output is plain static files with no server runtime assumption — the contract that keeps consumer hosting, blob upload, public URLs, PR previews, and authentication possible.
  • Output carries the licensing notices of NFR-01.
  • No such command exists today; .topo/cache/site is a scan-produced cache (grounding G-2). This is the principal new CLI surface.

Source: D4 answer — "an npm command to 'bundle and package the site' — which we could run and then upload to a blob store".

FR-06 — Customisation and extension surface

The generated site is customisable and extensible by its owner, in the manner Storybook is configured, themed, and extended.

  • Sufficient for a consumer to adapt categorisation, presentation, and composition.
  • Sufficient for a consumer to place their own authentication in front of the bundled output.
  • MVP scope is deliberately minimal (see Assumptions, A-3).

Source: C-9 — "make it customizable and extensible ... use storybook as your foundational inspiration"; D4 auth remark.

FR-07 — Agent-assisted local authoring workflow

Topo skills enable a coding agent to create and evolve stories locally against the changes in a PR.

Source: owner — "You should be able to generate one against your PR's changes ... with AI assistance. You'll be doing this locally"; CF-2.

FR-08 — Objective anchor validation as a product capability

Broken anchors (missing file, missing symbol, unresolvable pattern, invalid document) are detected and reported as objective failures by the topo CLI.

  • This is a product capability that consumers may invoke, not a gate on this repository's CI. See CON-03.
  • Heuristic freshness and explanation-coverage policy is explicitly not specified here (see U-4).

Source: C-8 two-systems correction; #35 "PR explanation and freshness".

FR-09 — Vendored renderer package @topo/diagram-core (NEW)

A workspace package @topo/diagram-core is the only name the rest of topo imports for architecture rendering.

  • It holds an unmodified copy of upstream Archify at commit d673e83 — all 214 pinned files, every one of which lives under archify/ (verified: the copy closure is clean, nothing outside that directory is required).
  • LICENSE, THIRD_PARTY_NOTICES.md, and the brand-marks/ attribution and trademark disclaimer are retained verbatim.
  • The fork point (d673e83) and the 214 SHA-256 file hashes already recorded in experiments/archify-wrapper/upstream-files.json are committed as the integrity baseline, so the copy can be proven byte-identical to upstream and later diffed cleanly against a newer upstream.
  • The copy is not modified (see CON-07 patch policy). This discipline is what keeps the later swap to upstream's published package a swap rather than a merge.
  • The package is not published under the name archify — that name is both taken by an unrelated package and upstream's identity.

Source: owner decision recorded in CON-02; name confirmed "yeah topo/diagram-core is fine"; brand-mark retention recorded in Discovery correction (Simple Icons 16.28.0 artwork is CC0, and upstream's own README disclaims trademark and endorsement).


Nonfunctional requirements

NFR-01 — Licensing notices in generated artifacts (agreed)

Generated and bundled output embeds third-party bytes and must carry explicit notices:

  • MIT — Archify viewer runtime.
  • SIL OFL 1.1 — embedded JetBrains Mono subsets.

Producing and then distributing the artifact is redistribution regardless of whether the bytes enter Git history. Existing machinery: scripts/dependency-notices.mjs --site already runs inside yarn build (grounding G-5); extend it rather than invent a parallel mechanism.

Owner approval: "yeah that's fine. Our contribution is the scaffolding and organization around these things." Scope of approval is notices in output. Revised: the original exclusion of "vendoring source into history" no longer holds — vendoring is now explicitly decided (CON-02, FR-09), which makes notice retention an obligation on the committed copy as well as on generated output. Modifying or renaming fonts remains outside this approval.

NFR-02 — Licence allowlist change (agreed)

ALLOWED_LICENSES in scripts/dependency-notices.mjs:15-26 does not currently include OFL-1.1, and yarn licenses:check enforces it (scripts/check-licenses.mjs). OFL-1.1 is to be added, and the embedded font retained.

The alternative — dropping the embedded font for a system monospace stack, avoiding OFL entirely — was presented and not chosen.

Owner: "sure ... I guess it's fine, i don't care really and don't understand the implications. Just creating myself a tool." Recorded as approval of this narrow allowlist change only. It is not informed legal review and must not be cited to widen licensing scope later.

NFR-03 — Reproducibility of rendered output

Identical committed documents must render identically across runs and machines. Concretely: the renderer is fixed by the vendored copy at commit d673e83, verified against the recorded 214 file hashes (FR-09). This is stricter than the lockfile pin the published version of this requirement assumed. See CON-02.

NFR-04 — Host-agnostic output

Bundled output must not assume a particular host, server, base path behaviour aside from documented configuration, or authentication mechanism.

NFR-05 — Performance (measured evidence only, no target)

POC fixture measurements: approximately 807 KB for the example overview and 2.16 MB for the delta artifact, with viewer payloads duplicated per artifact (#35). These are measured fixture sizes, not agreed budgets. No performance target is agreed. If payload duplication across many stories becomes a problem, that is a new decision, not an assumed requirement.

NFR-06 — Unknown quality attributes

Accessibility, security, privacy, reliability, and operability targets were not discussed and are not invented here. Owner: this is a personal tool first — "Just creating myself a tool. If someone else wants to use it fine." Owner owns these if they later matter. Note: packages/site/src/renderers/renderer.ts already exposes an accessibleLabel helper, so some accessibility intent exists in current code; it is not a specified MVP requirement.


Constraints and agreed decisions

CON-01 — Two systems, not one (decided)

There are two distinct systems and they must not be conflated:

  1. Building topo — this repository.
  2. Consuming topo — the owner (and others) generating documents locally and later wiring their own CI to deploy previews.

Owner: "There are 2 things here: the build out of topo (what you are working on) and my future usage of it (which you should be aware of but not over optimize on)." Do not over-optimise for the owner's future preview pipeline.

CON-02 — Archify acquisition policy (REVISED — decided)

This requirement is reversed from its published form. Archify enters as a vendored workspace package, @topo/diagram-core, holding an unmodified copy of upstream at commit d673e83.

Why the npm route is unavailable (evidence):

  • Upstream archify/package.json at d673e83 declares {"name":"archify","version":"2.17.0-dev.1","private":true,...}. private: true prevents publication; there is no upstream package to depend on.
  • The package lives in an archify/ subdirectory and the repository root has no package.json, so a plain git-URL dependency does not resolve either. The fallback named in U-1 does not work.
  • The npm registry is not blocked. registry.npmjs.org returns 200. The earlier HTTP 000 was transient and U-1's premise was wrong.
  • Name-collision trap: public [email protected] is an unrelated package by a different author. Depending on the name would silently pull the wrong code.
  • Upstream tracks publication as open issue #408, "Publish archify to the npm registry."

The vendored package is a swappable seam, not a fork of intent. The rest of topo imports only @topo/diagram-core. Today that package contains the copy; once #408 lands, its body becomes a thin re-export of the published package and the copy is deleted. Swap cost stays confined to one package.

Owner: "I think we evolve into a yarn workspace and literally copy what they have ... take it over, it's a great foundation to build on ... and then we control our own destiny", and on the swap-back plan: "what if we 'hard fork' for now into a yarn workspace, and then later once they figure out their packaging we can have that workspace just export their package for us?" Package name confirmed: "yeah topo/diagram-core is fine."

Superseded by this revision: the caret-range npm dependency and its delegated version-tolerance decision. The owner's earlier "you're managing it" delegation is satisfied by the pinned copy, which is stricter than any caret range.

CON-03 — This repository's CI (decided)

CI for topo-code keeps all existing checks and adds the linter. Today CI runs yarn test:regression = yarn check (typecheck → build → test → licenses:check) plus Playwright browser tests (.github/workflows/ci.yml).

  • Add: the linter.
  • Add: the upstream test suite that travels with the vendored copy (132 test files under @topo/diagram-core). Owner: "upstream test files: yes." These are the cheapest standing proof that the vendored copy is intact and functional. Two real costs are accepted: added CI time, and toolchain glue, because the tests are written for upstream's runner rather than this repository's Vitest setup.
  • Add: the integrity check of FR-09 (copy matches the recorded 214 hashes).
  • Add no documentation gates. Anchor validation is FR-08, a product capability, not a CI gate here.
  • ESLint is already in flight as Add minimal ESLint checks for coordinated delivery #38 / PR chore(lint): add correctness baseline #39 (chore/eslint-baseline). Do not duplicate or re-scope it. No ESLint configuration exists on main yet (grounding G-6).

Owner: "For your CI, for the topo repo, what I want: run unit tests, run the linter" + "yeah sounds good for CI" confirming that this means adding the linter while keeping existing checks.

CON-04 — Existing surfaces retained

The in-house WebGL renderer and the generated explorer are kept, indexed by the one landing page. Recorded as a soft keep — the owner's phrasing was tentative ("I suppose we can keep that"). No new investment in it is specified, and its long-term future is open (U-3).

CON-05 — Platform

Node >=22, Yarn 4.18.0, ESM, TypeScript, Vite, Vitest, Playwright, workspace layout packages/*. Note: scripts/run-workspaces.mjs covers only packages/*, so experiments/ is outside the workspace runner.

CON-06 — Preserve POC evidence

The preserved POC under experiments/archify-wrapper/ is historical evidence. Do not overwrite captures to make a later result look original (#35).

CON-07 — Patch policy for the vendored copy (NEW — decided)

Changes to the vendored copy follow a strict order:

  1. Contribute upstream first. Prefer an upstream PR over a local change.
  2. If blocked, keep an explicit, listed patch set applied on top of the pristine copy, so the eventual swap to upstream's package stays evaluable — each patch must be individually justifiable as "still needed" or "landed upstream".
  3. Never silent in-place edits. An unlisted modification inside the copy converts the future swap into a merge and defeats CON-02.

Owner: "patch policy seems reasonable."

CON-08 — Inter-document navigation is implemented wrapper-side (NEW — decided; resolves U-5)

Node-to-document drill-down requires no upstream change and no schema modification. Two distinct limits were conflated in #35:

  • components[].href is genuinely rejected — a hard schema additionalProperties failure, exit 1 (experiments/archify-wrapper/evidence/native-node-hyperlink-unsupported-1789503797231.json). That route stays closed.
  • But the missing focus propagation is unimplemented, not impossible. FINDINGS.md:125-127: "Selection updates the iframe URL, not the wrapper URL ... The POC does not implement parent-child context synchronization."

The wrapper and iframe are same-origin, and browser.mjs:41-45 already reads frame.url(). The mechanism: mirror the iframe focus permalink into the wrapper URL and restore it on load, mapping node id → document through topo's own index. #35 already assigns topo ownership of inter-document navigation, so this sits on our side of the boundary and preserves CON-07.

Watch, do not block: upstream PRs #398 (authored node explanations in the semantic passport) and #413 (Architecture Atlas navigation) overlap this area and may later offer a better mechanism.


Non-goals

Explicitly excluded from this MVP:

  • N-1 Hosting the bundled site; uploading to a blob store; producing public preview URLs; PR preview pipelines. Consumer scope.
  • N-2 Authentication or login protecting assets or previews. Consumer scope — must remain possible (FR-05, NFR-04), not built.
  • N-3 Any documentation gate in this repository's CI (CON-03).
  • N-4 A human sketch / FigJam-style canvas (Plan agent-authored architectural whiteboards #35 explicitly defers it).
  • N-5 Manual JSON authoring UX.
  • N-6 REVISED. Vendoring Archify into @topo/diagram-core is now decided and in scope (CON-02, FR-09). What remains excluded: modifying the vendored copy outside the CON-07 patch policy, modifying or renaming the fonts, publishing anything under the name archify, and maintaining a divergent long-term fork as a goal. The intent is a copy we can swap back out, not a fork we must maintain.
  • N-7 Reimplementing ordinary diagramming infrastructure that already exists outside topo-code (Plan agent-authored architectural whiteboards #35).
  • N-8 Heuristic freshness / explanation-coverage enforcement policy (U-4).

Supportability constraint: N-1 and N-2 must remain achievable by a consumer. The bundle output shape (FR-05, NFR-04) is the contract that guarantees it.


Acceptance criteria

  • AC-01 An authored story committed to a repository is rendered by the site with its source anchors resolved to real locations, without any stored line ranges. (FR-01, CF-1)
  • AC-02 A story whose anchor no longer resolves produces an objective, actionable failure naming the document and the unresolved anchor — it is not silently rendered. (FR-08, S-E1)
  • AC-03 Rendering a given frozen document twice produces equivalent output; the renderer in use is fixed by the vendored copy. (NFR-03, CON-02)
  • AC-04 REVISED. The rest of topo reaches Archify only through @topo/diagram-core; no other package imports the vendored tree directly, and no dependency on a registry package named archify exists. (CON-02, FR-09)
  • AC-05 A generated landing page lists every authored story and the generated explorer, organised into categories, with no hand-maintained index file. (FR-03)
  • AC-06 A repository containing zero authored stories still produces a coherent site. (S-E2)
  • AC-07 The existing topo serve command serves the composed site on the default port and on an explicit --port. (FR-04, G-1)
  • AC-08 A bundle command emits static files that render correctly when served by any plain static file server, with no topo process running. (FR-05, NFR-04, S-4)
  • AC-09 Bundled output contains MIT and SIL OFL 1.1 notices covering the embedded viewer and font bytes. (NFR-01)
  • AC-10 yarn licenses:check passes with the vendored @topo/diagram-core package present, with OFL-1.1 in the allowlist. (NFR-02)
  • AC-11 An owner can change categorisation and presentation of their site through a supported configuration surface, without modifying topo package source. (FR-06, S-5)
  • AC-12 A coding agent can create and update a story for a change on a branch via topo skills, with no model service required. (FR-07, CF-2, S-1)
  • AC-13 Failure to resolve or render through the Archify adapter fails the build with an actionable message and emits no partial artifact. (FR-02, S-E3)
  • AC-14 CI runs the existing checks plus the linter, and adds no documentation gate. (CON-03)
  • AC-15 A renderer can be swapped or added behind the adapter without changing story documents. (FR-02, FC-1)
  • AC-16 The vendored copy verifies byte-identical against the 214 recorded upstream hashes for d673e83, and the check fails loudly if any file drifts. (FR-09, CON-07)
  • AC-17 The upstream test suite that travels with the vendored copy runs in CI and passes. (CON-03)
  • AC-18 LICENSE, THIRD_PARTY_NOTICES.md, and the brand-mark attribution and trademark disclaimer are present verbatim in the vendored package. (FR-09, NFR-01)
  • AC-19 Selecting a node that maps to another document updates the wrapper URL, and loading that URL restores the same focus — without modifying the vendored copy. (CON-08, S-3)

Testing and verification expectations

Doctrine applied: test-seams (sha256 460b6410…), domain (7ebf5265…), documentation (54a88537…), loaded and verified via .agents/skills/doctrine/scripts/doctrine.mjs.

Prefer existing seams — all three already exist in this repository:

Seam Mechanism Prior art
Per-package unit tests vitest run every packages/*/package.json
Repo-level script tests node --test scripts/run-workspaces.test.mjs, scripts/dependency-notices.test.mjs
Real browser behaviour Playwright packages/site test:browser, playwright.config.mjs

Expectations

  • Outcomes over conversations. Assert rendered output, emitted files, and exit codes. Do not assert renderer call sequences or adapter internals. (test-seams / Prefer outcomes over conversations)
  • Adapter contract tests (AC-13, AC-15) verify the contract, using a substitute renderer that models only that contract — not a partial mock of Archify. (test-seams / Choose doubles by role; Reject test-only architecture)
  • Anchor resolution and failure (AC-01, AC-02) are behavioural tests over real fixture repositories, following the existing scanner fixture approach (packages/scanner fixture script).
  • Bundle output (AC-08) is verified by serving the emitted directory with a plain static server and asserting it renders — the strongest available evidence for "no server assumption". Playwright is the existing seam for this.
  • Licensing (AC-09, AC-10) extends scripts/dependency-notices.test.mjs and yarn licenses:check; these are already enforced in yarn check.
  • Reproducibility (AC-03) compares two renders of one frozen document. Treat byte-identity as a question to settle during implementation, not an assumed requirement — asset hashing may make equivalence the honest assertion.
  • Business language. Tests name stories, anchors, categories, bundles — not internal class shapes. (domain / Test in business language)

Manual checks

  • AC-11 (customisation) and AC-12 (agent authoring) need at least one manual walkthrough; neither is fully mechanisable at MVP.

Limitations

  • ubuntu-latest / Node 22 behaviour of the Archify render path is unverified; the Discovery spike (Spike A) that would verify it was specified and deliberately not run. With the vendored copy this is now verified by CI itself the first time AC-17 runs.
  • Corrected: the published version of this specification stated that the npm registry was unreachable from the authoring machine. That was wrong — the HTTP 000 was transient, and registry.npmjs.org returns 200. See CON-02 for the actual blocker.
  • Integrity verification (AC-16) and the upstream suite (AC-17) are new CI seams. The upstream tests target upstream's runner, so the glue needed to run them under this repository's toolchain is unmeasured.

Assumptions and unresolved decisions

Assumptions (labelled, not facts)

  • A-1 Archify's rendering is reachable from Node in this workspace layout. Supported by the POC, which ran from experiments/archify-wrapper/, not by an integrated packages/* build. FR-09 makes it a workspace package, which is where this assumption gets tested for real; note scripts/run-workspaces.mjs covers only packages/* (CON-05).
  • A-2 Composing the new site into the existing topo serve output path is cheaper than adding a second server. Based on G-1; not measured.
  • A-3 A minimal Storybook-style configuration surface satisfies FR-06 for MVP. The Storybook analogy is easy to over-build; breadth beyond configuration + theming + categorisation is assumed out.

Unresolved — does not block starting

  • U-1 RESOLVED (premise was wrong). Archify is not published and cannot be: upstream declares "private": true, and the package sits in an archify/ subdirectory under a root with no package.json, so the git-URL fallback named here also fails. The npm registry is reachable (200); the earlier 000 was transient. Public [email protected] is an unrelated package. Superseded by CON-02 / FR-09.
  • U-2 DECIDED. Vendoring is authorised (CON-02, FR-09) with a swap-back intent, bounded by the CON-07 patch policy. MIT permits this with notice retention. The Reserved Font Name question for JetBrains Mono remains unverified but moot, because the fonts are not modified. Whether topo ever becomes a true long-term fork is still the owner's call and is not decided here.
  • U-3 Long-term future of the WebGL explorer. CON-04 is a soft keep. Whether the two surfaces eventually converge, or the explorer is retired, is open. Owner: repository owner.
  • U-6 Upstream tracking cadence (NEW). Upstream is very active — 64,710 stars, pushed the same day this was written, and our pin d673e83 was already ~9 commits behind within a day. Whether to track upstream periodically or freeze until #408 publishes is undecided and deliberately not blocking: the pin is stable either way, and AC-16 makes drift visible.

Resolved — previously blocked readiness

  • U-4 CLOSED — there is no staleness policy. Owner: "no staleness. topo should always represent current state. It's up to agents to keep them up to date with changes they make." Freshness is an agent responsibility, not a product gate. FR-08's objective failures (missing file, missing symbol, unresolvable pattern, invalid document) are the whole of the validation surface. N-8 stands: no heuristic freshness or coverage enforcement is built. Plan agent-authored architectural whiteboards #35's pending question is answered and should be updated when Plan agent-authored architectural whiteboards #35 is next revised.
  • U-5 RESOLVED — a wrapper-side fix exists. See CON-08. The owner's challenge ("are you sure about this? There's always a simple fix. You just haven't found it yet.") was correct: two limits had been conflated, and the blocking one is unimplemented rather than impossible. No upstream change, no schema change, and no fork are required. S-3 and inter-document navigation are unblocked.

Traceability

Requirement Source decision Acceptance Verification
FR-01 Story unit D1/C-9; CF-1 (#10) AC-01 vitest + fixture repo
FR-02 Render adapter C2; C-10; FC-1 AC-13, AC-15 contract tests w/ substitute renderer
FR-03 Landing page D1 answer AC-05, AC-06 vitest + Playwright
FR-04 Serve D4 answer; G-1 AC-07 existing CLI tests
FR-05 Bundle D4 answer; G-2 AC-08 Playwright over static server
FR-06 Customisation C-9 AC-11 manual + config tests
FR-07 Agent authoring owner S-1; CF-2 AC-12 manual walkthrough
FR-08 Anchor validation C-8; #35; U-4 closed AC-02 vitest + fixture repo
FR-09 @topo/diagram-core CON-02 owner decision AC-04, AC-16, AC-18 hash-integrity check
NFR-01 Notices owner approval AC-09, AC-18 dependency-notices.test.mjs
NFR-02 Allowlist C1 answer AC-10 yarn licenses:check
NFR-03 Reproducibility CON-02 AC-03 render-twice test
CON-03 CI C3 answer; owner "yes" AC-14, AC-17 CI config review
CON-07 Patch policy owner "seems reasonable" AC-16 integrity check + review
CON-08 Navigation U-5 resolution AC-19 Playwright URL round-trip

Coverage gaps and conflicts recorded

  1. Plan agent-authored architectural whiteboards #35 vs C-8. Plan agent-authored architectural whiteboards #35 states "CI consumes/checks the committed documents and publishes a PR-specific static preview." The owner's later answers moved both to consumer scope (CON-01, CON-03, N-1). This specification follows the later human decision. Plan agent-authored architectural whiteboards #35's wording is superseded on that point and should be updated when Plan agent-authored architectural whiteboards #35 is next revised.
  2. Plan agent-authored architectural whiteboards #35 vs C2. Plan agent-authored architectural whiteboards #35 frames Archify as the renderer; main already ships an in-house WebGL renderer. Reconciled by CON-04 (keep both, one index).
  3. No estimates exist anywhere in the backlog, so only a structural dependency order is available — never a schedule.
  4. docs/adr/ and root CONTEXT.md do not exist. No architecture decision records were available to ground against.
  5. This specification reversed itself on acquisition. The published version required an npm dependency (CON-02) and excluded vendoring (N-6). New evidence — upstream's "private": true — made that route impossible, and the owner then decided on the vendored workspace package. The reversal is marked in place rather than hidden; the original wording survives in the Discovery revisionTrail.
  6. Plan agent-authored architectural whiteboards #35's drill-down framing is partly superseded. Plan agent-authored architectural whiteboards #35 treats node-to-document navigation as blocked by the schema. Only the href route is blocked; focus propagation was simply never implemented (CON-08). Update Plan agent-authored architectural whiteboards #35 when next revised.

Structural dependency order (not a schedule)

FR-09 @topo/diagram-core  (new first chokepoint — nothing renders until the copy lands)
      └─> FR-01 story unit
                └─> FR-02 render adapter   (chokepoint)
                          └─> FR-03 landing page
                                    ├─> FR-04 serve   (mostly existing)
                                    ├─> FR-05 bundle  (principal new surface)
                                    └─> FR-06 customisation
FR-01 ───────────────────────────> FR-07 agent authoring   (parallel)
FR-03 ───────────────────────────> CON-08 inter-document navigation (needs an index)
NFR-02 allowlist ────────────────> required before FR-09 lands in CI
#38 / PR #39 ESLint ─────────────> independent lane, do not duplicate

Independent candidate slices (no dependency on FR-09, can start in parallel): NFR-02 allowlist, and the FR-05 bundle-output contract work that is renderer-agnostic.


Readiness

This specification is ready-for-agent.

Every reason readiness was previously withheld is now closed:

Blocker Disposition
U-4 freshness/coverage policy Closed by owner decision — no staleness policy; agents keep documents current.
U-5 drill-down mechanism Resolved by evidence — wrapper-side fix, no upstream or schema change (CON-08).
U-1 Archify npm publication Superseded — publication is impossible upstream (private: true); replaced by the vendored package (CON-02, FR-09).

Remaining unresolved items — U-3 (WebGL explorer's long-term future) and U-6 (upstream tracking cadence) — are deliberately non-blocking: neither changes the shape of the MVP, and neither gates any requirement.

Scope ready for breakdown: FR-01 … FR-09, NFR-01, NFR-02, CON-07, CON-08.

Two caveats carried into delivery, neither blocking:

  1. The OFL-1.1 allowlist approval (NFR-02) is the owner's explicit choice but not informed legal review — "i don't care really and don't understand the implications." It must not be cited to widen licensing scope later.
  2. CON-04's retention of the WebGL explorer is a soft keep ("I suppose"), not an investment commitment.

Marking this specification ready authorises breakdown into tickets. It does not dispatch Ship, approve any PR, or authorise a code change outside the scope above.

Activity

  1. jdylanmc commented on Sep 19, 2026

    @jdylanmc
    OwnerAuthor

    Approved implementation breakdown

    Breakdown published from this specification. This comment supersedes the earlier dated status note that no implementation child tickets had been published. The six implementation slices are listed below with their actual issue references and blocking edges. AC-14 is already delivered by PR #39; all other acceptance criteria are assigned to the children. #40 remains the open specification/rollup, not a competing implementation assignment. Child ready-for-agent labels mean fully specified, not dependency-unblocked or authorized to dispatch. Separate coherent deliveries are intended; prerequisites must be completed and present on each consumer's agreed base. No implementation, agent dispatch, orchestration, or PR creation was started by this breakdown.

    Specification source: 2026-09-19T12:09:45Z, body SHA-256 1965e96d069d64a85cb7850abde9d91249874a7cf1bd2e0b38197262a86827de.

    Issue Slice Blocked by Primary acceptance
    #41 Render a pinned, licensed architecture artifact through @topo/diagram-core None AC-04, AC-10, AC-16, AC-17, AC-18
    #42 Preview a source-grounded story with explicit anchor failures #41 AC-01, AC-02, AC-03, AC-13, AC-15
    #43 Browse and customize a generated story catalogue alongside the explorer #42 AC-05, AC-06, AC-07, AC-11
    #44 Follow linked stories and restore node focus from wrapper URLs #43 AC-19
    #45 Bundle the composed architecture site for plain static hosting #43 AC-08, AC-09
    #46 Create and evolve architecture stories through local topo authoring skills #42 AC-12

    The complete parent acceptance remains all AC-01 through AC-19 over the assembled state. Independent child completion is not a claim that the full MVP is shipped. The final delivery owner verifies the complete local authoring, composition, linked navigation, and static bundle journey once all prerequisite changes are on the agreed base. Parent closure and merges remain human-owned.

    Initially dependency-unblocked: #41. All children are unassigned.

  2. jdylanmc commented on Sep 24, 2026

    @jdylanmc
    OwnerAuthor

    Maintained specification now lives at https://github.com/jdylanmc/topo-code/blob/main/docs/product-spec.md. PR #78 migrated issue #40 into repository documentation. Closing #40 as superseded by repository documentation, not because all original requirements are fulfilled. Unresolved renderer commitments remain tracked by #41; the specification also lists other open composition/extensibility, cross-machine reproducibility, and manual-verification requirements that are not assigned to #41.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions