[architecture] Update architecture diagram - 2026-04-19

[github-actions]

Updates scratchpad/architecture.md with a refreshed ASCII architecture diagram generated from a full rebuild against commit f7e3992.

Changes

• Redraws the diagram with cleaner layer boundaries and grouped utilities (Rendering / Data / Files+Git / Others)
• Promotes pkg/actionpins to show its direct dependency from pkg/workflow
• Reclassifies pkg/stats as a utility package (consumed by pkg/cli, not a standalone core service)
• Updates the run reference link and date

Related

Full diagram details in the architecture issue created alongside this PR.

Generated by Architecture Diagram Generator · ● 1.1M · ◷

• expires on Apr 26, 2026, 9:06 AM UTC

[github-actions]

Hey @github-actions 👋 — thanks for the automated architecture diagram refresh! The redrawn ASCII layout with cleaner layer boundaries and the reclassification of pkg/stats as a utility package are both nice improvements.

One small flag from the checklist:

• No test changes — the diff touches only scratchpad/architecture.md, a pure documentation file, so this is expected and not a real concern. That said, if the diagram generator script itself lives in the repo, it may be worth ensuring that script has its own test coverage.

If you'd like to address the script coverage gap, here's a ready-to-use agent prompt:

Find the script or workflow that generates scratchpad/architecture.md (look in scripts/, .github/workflows/, and actions/).
If it contains any logic beyond shelling out to external tools, add unit tests covering:
1. The happy path — a valid codebase produces a well-formed architecture.md.
2. An edge case — a missing or empty package directory is handled gracefully.
Place the tests alongside the script following existing test file conventions.

Generated by Contribution Check · ● 1.7M · ◷

[Copilot]

Pull request overview

Updates scratchpad/architecture.md with a refreshed ASCII architecture diagram and an updated package reference, based on a new generator run.

Changes:

• Refreshes the ASCII architecture diagram layout and grouping (Rendering / Data / Files+Git / Others).
• Updates the “Last updated” date and generator run link.
• Revises package reference entries (notably promoting pkg/actionpins under pkg/workflow and reclassifying pkg/stats as a utility).

Show a summary per file

File	Description
scratchpad/architecture.md	Updates the architecture diagram and package reference metadata/descriptions to reflect the latest generated view of dependencies.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 1/1 changed files
• Comments generated: 5

[Copilot]

The diagram implies pkg/parser is only reached via pkg/workflow (pkg/cli → pkg/workflow → pkg/parser), but pkg/cli directly imports pkg/parser in many files (e.g., pkg/cli/commands.go). Consider adding a direct pkg/cli → pkg/parser edge (or otherwise adjusting the diagram) so direct dependencies are accurately represented.

Suggested change

	│ └──────────┬───────────────┘ └───────────┬─────────────┘ └──────────────────────────┘ │
	│ │ │ │
	│ └──────────┬───────────────┘ └───────────┬─────────────┘ └────────────▲─────────────┘ │
	│ │ │ │ │
	│ └────────────────────────────────────────────────────────────────▶│ │

[Copilot]

This merged connector suggests pkg/agentdrain depends on pkg/console, but pkg/agentdrain does not import pkg/console (while pkg/actionpins does). Update the arrows/layout so the diagram doesn’t imply an agentdrain → console dependency that doesn’t exist.

[Copilot]

pkg/parser is described as only doing “Markdown frontmatter parsing and content extraction”, but the package also performs YAML parsing/validation (e.g., uses goccy/go-yaml and has YAML import helpers). Consider expanding this description to reflect the YAML-related responsibilities as well.

Suggested change

	| pkg/parser | Core | Markdown frontmatter parsing and content extraction |
	| pkg/parser | Core | Markdown frontmatter parsing, content extraction, and YAML parsing/validation helpers |

[Copilot]

The table claims pkg/logger has “zero overhead”, but constructing a logger and calling Print/Printf still incurs some overhead even when disabled (early return avoids formatting/output, but not the call itself). Consider rewording to something like “minimal overhead when disabled” or restoring the previous phrasing to avoid overstating the guarantee.

Suggested change

	| pkg/logger | Utility | Namespace-based debug logging with zero overhead |
	| pkg/logger | Utility | Namespace-based debug logging with minimal overhead when disabled |

[Copilot]

pkg/gitutil is described as “Git and GitHub API utility functions”, but the package appears to focus on git CLI helpers plus GitHub-related string/error parsing (no GitHub API client calls). Consider rewording to “Git and GitHub-related utilities” (or similar) to avoid implying it wraps the GitHub API.

Suggested change

	| pkg/gitutil | Utility | Git and GitHub API utility functions |
	| pkg/gitutil | Utility | Git and GitHub-related utility functions |