Repository navigation
Description
This was generated by AI during triage.
Current status (2026-09-29)
Inspected baseline: main@b64bb2f.
Status: ready for an interactive agent-authoring acceptance walkthrough. The workflow itself is shipped.
The authoring skill, draft validation, source-grounded preview, stable identity/source-change fixtures, and CLI are implemented. @jdylanmc/[email protected] now provides a real unrelated-project entry point; topo init --skills installs portable operation and story-authoring context. The installed-consumer regression covers a scripted source-change/repair journey, not manual agent acceptance.
Remaining acceptance
-
In a real Git repository, have the local agent inspect relevant source and author a focused story; validate and commit/preview it through separately authorized steps.
-
Exercise a later branch/source change; observe changed-anchor failure and repair it while preserving story identity and unrelated authored intent.
-
Retain before/after documents, source references, objective validation results, and locally viewable output as manual walkthrough evidence.
-
Record human semantic/visual observations distinctly from structural validation; valid anchors do not prove the explanation is accurate or complete.
A published-package consumer is now available without a Topocode checkout. This issue does not authorize changes to an unspecified target project; choose that repository and its write/commit boundaries before running the walkthrough. Do not substitute a scripted fixture, mocked model, or package install proof for the manual evidence. #42 is independent.
Evidence: portable operation skill, authoring skill, authoring guidance, and scripted consumer proof.
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.
The local topo-story-authoring skill, draft validation command, preview workflow, and executable before/after branch fixtures are implemented. Keep this issue for the FR-07 / AC-12 manual agent-authoring walkthrough explicitly left unresolved by the maintained specification.
Remaining scope
- Perform the manual local-agent workflow against a real repository and later branch change: inspect relevant source, author a focused story, validate, commit/preview through separately authorized steps, then repair changed anchors while preserving identity and unrelated intent.
- Retain before/after authored documents, source references, objective validation output, and locally viewable output as the walkthrough evidence.
- Do not substitute the existing scripted fixture or a mocked model for manual workflow evidence; successful structure/anchors still do not establish semantic accuracy or complete coverage.
Readiness and dependencies
The existing preview prerequisite is present on main. Remove the obsolete #42 blocking relationship; cross-machine reproducibility work is independent. No manual acceptance or new authoring execution is claimed by this cleanup.
Merged delivery evidence: #52, #78. These merge commits are ancestors of the inspected main revision.
Current source and regression evidence:
docs/product-spec.mddocs/story-authoring.md.agents/skills/topo-story-authoring/SKILL.mdpackages/cli/src/story-authoring.test.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-07, FR-01 incremental identity, S-1, CF-2, U-4 resolution.
What to build
Provide a supported local skill workflow by which a coding agent reads relevant source and existing stories, creates a focused explanation, and updates it alongside a branch's code changes. The agent uses the product's objective validation and preview loop to repair broken anchors while retaining document identity and unrelated authored intent. Humans review explanations rather than hand-authoring JSON. No mandatory hosted model service or implicit scan-time AI invocation is introduced.
Acceptance criteria
-
AC-12: A coding agent can create and update a story for a change on a branch via topo skills, without a required model-service integration.
-
Demonstrate both initial authoring and a later source change with identity-preserving story updates and correctly resolved evidence.
-
Keep explanations current through the agent workflow, not a new product staleness/coverage gate.
-
Make the workflow's limitation explicit: successful structure and anchors do not establish semantic accuracy or complete explanation coverage.
-
Keep authored story artifacts distinct from generated render/cache output and do not require humans to edit renderer JSON.
Verification and readiness
-
Perform the specification's manual agent-authoring walkthrough against a real fixture repository and a branch change.
-
Retain the before/after authored story, source references, objective CLI validation results, and locally viewable output as acceptance evidence.
-
Exercise malformed/moved source handling through the existing story/anchor tests; do not replace the manual workflow evidence with only a mocked model.
-
This workflow depends on the story contract and preview, not the later catalogue theme, navigation, bundle, or a mandatory provider service.
Readiness: Fully specified; needs the story/document preview path. Can proceed independently of catalogue, navigation, and bundle work once that prerequisite is available.
Open product decisions: None for this scoped slice. Return newly discovered material scope decisions to the human.
Blocked by
- Verify story-render reproducibility across runs and machines #42: Preview a source-grounded story with explicit anchor failures
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
test(story): allow CI walkthrough time
Merge pull request #52 from jdylanmc/jdylanmc/issue-46-authoring
[-]Create and evolve architecture stories through local topo authoring skills[/-][+]Complete manual agent story-authoring acceptance walkthrough[/+]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.
The local topo-story-authoring skill, draft validation command, preview workflow, and executable before/after branch fixtures are implemented. Keep this issue for the FR-07 / AC-12 manual agent-authoring walkthrough explicitly left unresolved by the maintained specification.
Remaining scope
Readiness and dependencies
The existing preview prerequisite is present on main. Remove the obsolete #42 blocking relationship; cross-machine reproducibility work is independent. No manual acceptance or new authoring execution is claimed by this cleanup.
Merged delivery evidence: #52, #78. These merge commits are ancestors of the inspected
mainrevision.Current source and regression evidence:
docs/product-spec.mddocs/story-authoring.md.agents/skills/topo-story-authoring/SKILL.mdpackages/cli/src/story-authoring.test.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 the walkthrough ready and pointed it at the now-published CLI-plus-skills entry point. Distinguished the completed scripted consumer/source-change proof from the still-required real agent and human acceptance walkthrough.
Evidence and preserved historical requirements are in the updated issue body. Baseline:
main@b64bb2f. No repository source or credential changes.