Repository navigation
Description
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 (
decisionlabel) and its comment pinning the preserved packet at merge8643d83e06ccbb34aa1e1ceb088039a637fb2562. - Preserved POC packet:
experiments/archify-wrapper/{README,VISION,FINDINGS,PROVENANCE,PLAN}.md. - Implementation grounding read from
mainon 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/ingestbehaviour 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.topocache. - 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] --portalready 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/siteis 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.
- Authoring is local and agent-assisted. Humans do not hand-author JSON (Plan agent-authored architectural whiteboards #35).
- No mandatory model service (carried forward, CF-2).
- Must separate repeatable rendering of a frozen document from non-deterministic agent interpretation (Plan agent-authored architectural whiteboards #35).
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 underarchify/(verified: the copy closure is clean, nothing outside that directory is required). LICENSE,THIRD_PARTY_NOTICES.md, and thebrand-marks/attribution and trademark disclaimer are retained verbatim.- The fork point (
d673e83) and the 214 SHA-256 file hashes already recorded inexperiments/archify-wrapper/upstream-files.jsonare 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:
- Building topo — this repository.
- 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.jsonatd673e83declares{"name":"archify","version":"2.17.0-dev.1","private":true,...}.private: trueprevents publication; there is no upstream package to depend on. - The package lives in an
archify/subdirectory and the repository root has nopackage.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.orgreturns200. The earlier HTTP000was 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 onmainyet (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:
- Contribute upstream first. Prefer an upstream PR over a local change.
- 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".
- 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[].hrefis genuinely rejected — a hard schemaadditionalPropertiesfailure, 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-coreis 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 namearchify, 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 namedarchifyexists. (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 servecommand 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:checkpasses with the vendored@topo/diagram-corepackage present, withOFL-1.1in 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/scannerfixturescript). - 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.mjsandyarn licenses:check; these are already enforced inyarn 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
000was transient, andregistry.npmjs.orgreturns200. 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 integratedpackages/*build. FR-09 makes it a workspace package, which is where this assumption gets tested for real; notescripts/run-workspaces.mjscovers onlypackages/*(CON-05). - A-2 Composing the new site into the existing
topo serveoutput 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 anarchify/subdirectory under a root with nopackage.json, so the git-URL fallback named here also fails. The npm registry is reachable (200); the earlier000was 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
d673e83was 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
- 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.
- Plan agent-authored architectural whiteboards #35 vs C2. Plan agent-authored architectural whiteboards #35 frames Archify as the renderer;
mainalready ships an in-house WebGL renderer. Reconciled by CON-04 (keep both, one index). - No estimates exist anywhere in the backlog, so only a structural dependency order is available — never a schedule.
docs/adr/and rootCONTEXT.mddo not exist. No architecture decision records were available to ground against.- 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 DiscoveryrevisionTrail. - 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
hrefroute 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:
- The
OFL-1.1allowlist 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. - 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
jdylanmc commentedon Sep 19, 2026
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.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.
docs(spec): preserve unresolved requirements
jdylanmc commentedon Sep 24, 2026
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.