Skip to content

Re-author the 11 stale Archify artifacts #785

Closed

Description

@JSdotNet

While upgrading Archify I found 11 diagram artifacts already out of date on main, several because diagrams were inserted into the runtime-view chapter and shifted every ordinal after them. The new session will re-author them against their current mermaid and make the re-render advice in the diagrams README safe.

Context

In the Backlog repo, node tools/diagrams/archify-artifacts.mjs verify reports 11 stale artifacts on main: .devbook/domain/context-map.md #1, .devbook/domain/inbox/flow.md #1, .devbook/domain/tasks/flow.md #2, .devbook/arc42/05-building-block-view.md #6, .devbook/arc42/06-runtime-view.md #3ΓÇô#7, .devbook/arc42/07-deployment-view.md #3, .devbook/tech/technology-graph.md #1. In 06-runtime-view.md, diagrams were inserted (PR #702 era), so spec filename ordinals no longer match fence positions. Fence #4 is now a sequenceDiagram but its spec is 06-runtime-view.4.lifecycle.json, fence #7 is a stateDiagram-v2 but its spec is .7.sequence.json, and the index maps the current fence #8's hash to spec 5 (the spec actually authored from it). Fences #9ΓÇô#11 have no spec. Work: (1) for each stale diagram, compare the current mermaid fence with its spec and re-author the spec where the diagram changed; for 06-runtime-view, rename/renumber specs to match current fence ordinals (one spec per chapter+ordinal) before rendering. Follow tools/archify/SKILL.md, which requires reading a matching example first. (2) Render each with node tools/diagrams/archify-artifacts.mjs render <spec> only once the spec genuinely reflects its fence, since render re-keys the index to whatever fence sits at the ordinal. (3) Fix tools/diagrams/README.md "Re-rendering after editing a specification": it recommends rendering every spec by path, which silently marks stale artifacts current and can reassign an artifact to the wrong fence when ordinals have moved; tools/archify/UPSTREAM.md "Updating" explains the hazard. Consider making render refuse when the fence at the ordinal differs from the one the existing index entry recorded, unless the spec is newer. Keep meta.animation: "trace" on every spec (ArchifyArtifactMotionTests). Finish with verify clean. Route through delivery:flow-code per CLAUDE.md (spec/artifact work under .devbook/_archify is generated-artifact housekeeping; any chapter prose edit goes through flow-spec).


Filed automatically from a Claude Code suggested task.

Activity

  1. added
    documentationImprovements or additions to documentation
    triagedClassified by the issue sweep
    on Sep 28, 2026
  2. JSdotNet commented on Sep 30, 2026

    @JSdotNet
    OwnerAuthor

    Closed by the issue sweep as already fixed: commit fdfa61e ("Re-author the 11 stale Archify artifacts and make render refuse a wrong re-key"), PR #787 (merge 663fdf5), is on main. It renumbered the 06-runtime-view specs to current fence ordinals, re-authored the listed artifacts, and made render refuse a fence mismatch. Note: node tools/diagrams/archify-artifacts.mjs verify on main (9dce776) now reports one different artifact stale, .devbook/arc42/05-building-block-view.md #4, which was not among this issue's eleven. That is later drift and is listed in today's sweep brief.

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

    documentationImprovements or additions to documentationtriagedClassified by the issue sweep

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions