[docs] Consolidate architecture diagram and guard policies into dev.md (v3.4)

[github-actions]

Analyzed 63 markdown files in scratchpad/ (2 new since 2026-02-28 run). 0 tone issues and 0 formatting issues found. 2 new spec files incorporated into scratchpad/dev.md.

Changes Made

scratchpad/dev.md — version v3.3 → v3.4 (+67 lines, 2074 → 2139)

New: Package Structure section (Core Architecture)

Sourced from scratchpad/architecture.md (last updated 2026-03-01). Added a layered package reference table:

• Entry Points: cmd/gh-aw and cmd/gh-aw-wasm
• Core: pkg/cli, pkg/workflow, pkg/parser, pkg/console
• Shared: pkg/constants, pkg/types
• Utilities: 12 utility packages listed

New: GitHub MCP Guard Policies section (MCP Integration)

Sourced from scratchpad/guard-policies-specification.md. Covers:

• Frontmatter syntax (repos + min-integrity fields)
• Repository pattern options ("all", "public", array of owner/repo patterns)
• Integrity levels (none | reader | writer | merged)
• Validation location in codebase
• Extensibility for future MCP servers

Supporting updates

• 2 new Related Documentation links (architecture.md, guard-policies-specification.md)
• Document history entry for v3.4

Coverage

✅ 100% — all 62 spec files documented (63 analyzed: 62 spec + 1 test artifact)

Validation

✅ Markdown syntax valid
✅ 9 Mermaid diagrams retained
✅ All code blocks have language tags
✅ Technical tone consistent throughout

References:

• §22555874720

Generated by Developer Documentation Consolidator

• expires on Mar 4, 2026, 12:04 AM UTC

[Copilot]

Pull request overview

Updates scratchpad/dev.md to v3.4 by consolidating additional architecture and MCP policy specifications into the unified developer instructions.

Changes:

• Added a “Package Structure” section summarizing the layered package layout (entry points, core/shared packages, utilities).
• Added a “GitHub MCP Guard Policies” section documenting repos/min-integrity frontmatter and where validation occurs.
• Added related-documentation links and a v3.4 document history entry.

Comments suppressed due to low confidence (3)

scratchpad/dev.md:124

• The section says the package structure has "three tiers" (entry points, core, utilities), but it also introduces a separate "Shared Definitions" grouping. This is internally inconsistent—either update the text to describe four groupings (entry points/core/shared/utilities) or fold shared definitions into one of the three tiers so the description matches the table that follows.

The codebase uses a layered package structure with three tiers: entry points, core packages, and utilities.

**Entry Points**: `cmd/gh-aw` (main CLI binary) and `cmd/gh-aw-wasm` (WebAssembly target)

**Core Packages**:

| Package | Description |
|---------|-------------|
| `pkg/cli` | CLI command implementations and subcommands |
| `pkg/workflow` | Workflow compilation engine and orchestration |
| `pkg/parser` | Markdown frontmatter and YAML parsing |
| `pkg/console` | Terminal UI and styled output rendering |

**Shared Definitions**:

scratchpad/dev.md:134

• This path is misleading in the context of scratchpad/dev.md: architecture.md lives in the same directory, so the accurate relative reference would be ./architecture.md (or just architecture.md). As written, scratchpad/architecture.md implies a nested scratchpad/scratchpad/ path.

This issue also appears on line 1730 of the same file.

See `scratchpad/architecture.md` for the full package dependency diagram.

scratchpad/dev.md:1730

• Similar to the earlier architecture reference, this points to scratchpad/guard-policies-specification.md even though the file is already in scratchpad/. Consider changing the reference to ./guard-policies-specification.md (or guard-policies-specification.md) to avoid implying a nested scratchpad/scratchpad/ path and to match the link style used in the Related Documentation section.

See `scratchpad/guard-policies-specification.md` for the full specification including type hierarchy and error message reference.

---

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