Repository navigation
Description
This was generated by AI during triage.
Current status (2026-09-29)
Inspected baseline: main@b64bb2f.
Status: ready for an agent; cross-machine reproducibility remains unverified.
The source-grounded story path, explicit failure behavior, atomic publication, renderer substitution coverage, and same-environment repeat-render checks are delivered. The relevant product now uses pristine Archify 3.0.0 via exact @jdylanmc/[email protected]; the CLI is also publicly installable as @jdylanmc/[email protected].
Remaining acceptance
-
Compare the same frozen story, source revision, renderer pin, and dependency set across repeated runs and distinct machines/environments. Record the actual environment identities and comparison inputs.
-
Preserve observable output comparisons; describe actual differences and the resulting supported/unsupported guarantees rather than assuming byte identity.
-
Retain existing validation, substitution, and no-partial-publication behavior.
Passing Linux/macOS smoke runs, cross-platform font fixes, public installation, or two renders in one environment do not establish this comparison. No upstream-suite or license-policy decision in #41 needs to block collecting reproducibility evidence. Do not reinstate obsolete native dependencies.
Evidence: reproducibility contract, adapter tests, installed-consumer regression, and maintained requirements.
Previous issue text and original requirements (historical; current disposition is above)
Reconciled status (2026-09-27)
Inspected baseline: main@c8e22ec. Maintained intent: docs/product-spec.md.
Disposition: remains open for the scope below.
Renderer-neutral authored stories, real source anchors, actionable failures, committed/dirty-source distinctions, substitute-renderer coverage, atomic publication, and same-environment repeat-render equivalence are shipped. Keep this issue for NFR-03 / AC-03 cross-machine reproducibility evidence explicitly retained by the maintained specification.
Remaining scope
- Exercise the same frozen story, source revision, renderer pin and dependency set across runs and machines; record the actual environments and comparison.
- Retain observable output comparisons and explicitly document differences or unsupported guarantees. Two renders in one process/environment are not cross-machine evidence.
- Preserve existing source-validation, renderer-substitution and no-partial-publication behavior.
Readiness and dependencies
The implemented story/renderer path is available on main. Remove the obsolete #41 blocking relationship: #41 now tracks separate pristine-copy/upstream-suite/license commitments, not a missing renderable package. This cleanup does not assert that cross-machine acceptance has occurred.
Merged delivery evidence: #49, #55, #78. These merge commits are ancestors of the inspected main revision.
Current source and regression evidence:
docs/product-spec.mddocs/story-preview.mdpackages/diagram-core/test/diagram-core.test.mjspackages/cli/src/story-preview.tspackages/story/src/index.ts
Existing exact-main CI is successful. This reconciliation inspected current code, committed regression coverage and merged history; it does not claim a new test run, manual walkthrough, visual acceptance, cross-machine experiment, or approval of paused work.
Historical issue scope (preserved; current disposition and readiness are above)
Parent
#40 - Specification: Storybook-for-architecture whiteboard MVP.
Source revision: 2026-09-19T12:09:45Z; complete specification body SHA-256 1965e96d069d64a85cb7850abde9d91249874a7cf1bd2e0b38197262a86827de.
Requirements: FR-01, FR-02, FR-08, NFR-03, S-1, S-3, S-E1, S-E3, S-E4.
What to build
Take one committed authored story through topo's supported CLI path to a locally viewable rendered explanation served by the existing server. Establish the durable renderer-independent document contract, resolve its code anchors against real source, and translate only at the rendering boundary. The story is authored data, not generated graph output or cache, and can be incrementally edited without unnecessarily replacing its identity. Keep the existing explorer usable; a complete corpus landing page is a later slice.
Acceptance criteria
-
AC-01: A committed story renders with source anchors resolved to real locations. Store path/symbol/symbol-scoped-pattern anchors, not renderer line ranges or renderer-owned document identity.
-
AC-02: Missing file, missing symbol, unresolvable pattern, and invalid document produce objective actionable CLI failures naming the document and unresolved anchor. Do not silently render misleading evidence.
-
AC-03: Rendering the same frozen story twice produces equivalent output through the pinned renderer; document the comparison and do not claim unmeasured universal byte identity.
-
AC-13: Missing/unavailable renderer or rendering failure fails the build clearly and emits no partial artifact.
-
AC-15: A contract-respecting substitute renderer can render the same story without rewriting that story, demonstrating the adapter boundary rather than depending on Archify's internal schema.
-
Retain the existing dirty-source versus committed-revision distinctions. Do not add a heuristic staleness/coverage gate, invoke a model during static generation, overwrite authored intent, or remove existing enrichment expiry behavior.
Verification and readiness
-
Use real fixture repositories for successful and broken path/symbol/pattern resolution and dirty/revision behavior.
-
Assert emitted artifacts, observable failures, and exit codes, including no partial publication.
-
Use a contract-only substitute renderer for adapter tests, plus the real pinned renderer for the actual story preview and render-twice case.
-
Use the existing real CLI/server/browser seam to demonstrate the story is viewable without replacing the explorer workflow.
Readiness: Fully specified; waits for the usable pinned renderer package on the delivery base. Precise anchor-to-renderer source mapping is implementation acceptance work, not permission to weaken the agreed anchor model.
Open product decisions: None for this scoped slice. Return newly discovered material scope decisions to the human.
Blocked by
- Complete pinned Archify upstream-suite evidence and license-policy reconciliation #41: Render a pinned, licensed architecture artifact through @topo/diagram-core
A closed prerequisite alone is insufficient: its implementation must be available on this delivery's agreed base.
Boundaries
-
Scope is Specification: Storybook-for-architecture whiteboard MVP #40, not the broader historical Roadmap: deferred architecture and engineering-health capabilities #1 roadmap. Preserve existing scanner, explorer, curated views, and enrichment behavior.
-
No hosting, authentication, deployment, public npm publication, human sketch canvas, or mandatory model service.
-
No heuristic staleness or explanation-coverage gate. Structural/source validation does not prove semantic truth.
-
Use the existing unit/script/browser verification seams and keep the repository regression gates. No documentation gate is added.
-
The source snapshot for this breakdown has AC-14 already delivered by PR chore(lint): add correctness baseline #39. Begin implementation from a base containing that merged change.
-
Keep the preserved prototype unchanged. Do not silently edit the vendored renderer or substitute an unapproved upstream version.
-
The implementation owner chooses local code structure within the agreed contracts; return newly discovered material product choices to the human.
Delivery grouping
Intentionally separate coherent deliveries, one eventual PR per child; not one parent-wide implementation PR. No delivery is launched by publication.
No assignee or exclusive ownership is claimed. Publication does not authorize worker dispatch, implementation, merge, or parent closure.
Assembled acceptance
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.
Activity
Merge pull request #49 from jdylanmc/jdylanmc/issue-42-story-preview
[-]Preview a source-grounded story with explicit anchor failures[/-][+]Verify story-render reproducibility across runs and machines[/+]jdylanmc commentedon Sep 27, 2026
Backlog reconciliation (2026-09-27)
Inspected baseline:
main@c8e22ec. Maintained intent:docs/product-spec.md.Disposition: remains open for the scope below.
Renderer-neutral authored stories, real source anchors, actionable failures, committed/dirty-source distinctions, substitute-renderer coverage, atomic publication, and same-environment repeat-render equivalence are shipped. Keep this issue for NFR-03 / AC-03 cross-machine reproducibility evidence explicitly retained by the maintained specification.
Remaining scope
Readiness and dependencies
The implemented story/renderer path is available on main. Remove the obsolete #41 blocking relationship: #41 now tracks separate pristine-copy/upstream-suite/license commitments, not a missing renderable package. This cleanup does not assert that cross-machine acceptance has occurred.
Merged delivery evidence: #49, #55, #78. These merge commits are ancestors of the inspected
mainrevision.Current source and regression evidence:
docs/product-spec.mddocs/story-preview.mdpackages/diagram-core/test/diagram-core.test.mjspackages/cli/src/story-preview.tspackages/story/src/index.tsExisting exact-main CI is successful. This reconciliation inspected current code, committed regression coverage and merged history; it does not claim a new test run, manual walkthrough, visual acceptance, cross-machine experiment, or approval of paused work.
jdylanmc commentedon Sep 29, 2026
Backlog reconciliation (2026-09-29)
Kept ready-for-agent and updated the frozen baseline to the shipped Archify 3.0.0/npm path. Public installation and platform smoke coverage are not being counted as the required cross-machine comparison. No new execution or acceptance is claimed.
Evidence and preserved historical requirements are in the updated issue body. Baseline:
main@b64bb2f. No repository source or credential changes.