[spdd] Daily spec work plan - 2026-07-17

[github-actions]

Summary

Daily SPDD review of 5 scratchpad/spec files (indices 19–23 of 92): hierarchical-agents-quickstart, hierarchical-agents, architecture, artifact-naming-compatibility, and breaking-cli-rules. Overall these docs are informative and reasonably structured, but all five lack formal SPDD framing: missing explicit Safeguards, incomplete Norms sections, absent formal Operations ordering, and no Sync hooks to keep docs aligned with implementation changes.

Priority Work Queue

P0

• scratchpad/agents/hierarchical-agents.md — Shared memory path (/tmp/gh-aw/repo-memory-default/memory/meta-orchestrators/) is hardcoded but not validated; no safeguard or constraint documents what happens if the path is missing.
• scratchpad/artifact-naming-compatibility.md — Missing Safeguards section: no mention of what happens when flattenSingleFileArtifacts() encounters an unexpected multi-file artifact where single-file was expected (silent data loss risk).

P1

• scratchpad/architecture.md — No Sync notes; diagram was last updated 2026-07-06 but the package table may drift from code without a stated policy.
• scratchpad/breaking-cli-rules.md — SPDD Norms section absent: no guidance on who approves a major-version bump or what quorum is needed.

P2

• scratchpad/agents/hierarchical-agents-quickstart.md — Missing Requirements traceability: no statement mapping Quick-Start steps to feature specs or acceptance criteria.
• scratchpad/breaking-cli-rules.md — Exit code table lists only 3 codes; spec doesn't cover code 3+ or distinguish between gh aw compile vs gh aw run contexts.

SPDD Checklist

• /spdd-analysis : Document preconditions for shared-memory paths; add failure modes if the memory branch is absent or unreadable. Done when a Safeguards subsection exists covering at least 3 failure modes.
• /spdd-analysis : Enumerate edge cases for (empty artifact, unexpected extra file, collision). Done when a Risks / Edge Cases subsection is added with at least 3 items.
• /spdd-reasons-canvas : Add a Sync note declaring ownership and the trigger that must refresh the diagram (e.g., any new package merged to main). Done when a Maintenance section with sync trigger is present.
• /spdd-reasons-canvas : Add an Approvals / Norms section stating review quorum for major-version changes. Done when the section names at least one role (e.g., maintainer) and minimum approval count.
• /spdd-generate : Expand exit-code table to cover codes used by all subcommands, referencing actual Go source constants. Done when the table covers ≥ 5 codes with source references.
• /spdd-generate : Add a Requirements section tracing each Quick-Start step to a spec or acceptance criterion. Done when every step has a reference link or spec ID.
• /spdd-sync : Create a CI lint rule (or OWNERS note) that flags PRs adding new packages without updating the diagram. Done when a note in the doc references the lint target or a tracking issue.
• /spdd-sync : Add a pointer to the actual test file paths so the spec stays linked to code. Done when each test name in the doc includes a Go file path.
• /spdd-analysis : Clarify the Operations order — which meta-orchestrator runs first when all three fire simultaneously? Add explicit run-order or concurrency contract. Done when an Operations Order subsection is present.
• /spdd-generate : Add a concrete example changeset for a schema breaking change (currently only flag and command examples are shown). Done when a schema-change example is present under Changeset Format for Breaking Changes.

Per-Spec Findings

scratchpad/agents/hierarchical-agents-quickstart.md (index 19)

Analysis

• Goals: Explain the three meta-orchestrators to repo maintainers, workflow authors, and campaign owners.
• Missing Constraints: No stated precondition for shared-memory write permissions; no rate-limit or quota guard mentioned.
• Ambiguous: "Adjust safe output limits" section doesn't specify new defaults or ranges — leaves authors guessing.

REASONS Canvas

• Requirements: ❌ No traceability to underlying feature spec
• Entities: ✅ Three orchestrators clearly named
• Approach: ✅ Quickstart flow is readable
• Structure: ⚠️ "Getting Help" reference links are relative paths that may break
• Operations: ⚠️ Daily/weekly/monthly cadence listed but no conflict resolution if multiple cadences collide
• Norms: ❌ No ownership/approval norms stated
• Safeguards: ❌ Troubleshooting section exists but doesn't cover security/permission failures

scratchpad/agents/hierarchical-agents.md (index 20)

Analysis

• Goals: Technical reference for hierarchical agent architecture.
• Risks: Hardcoded memory path — if tmp path changes, all coordination silently breaks.
• Ambiguous: "Non-Intrusive" principle conflicts with meta-orchestrators that call (a write action).

REASONS Canvas

• Requirements: ❌ No link to requirements document
• Entities: ✅ Architecture diagram present
• Approach: ✅ Discovery → Analysis → Decide → Execute flow is clear
• Structure: ✅ Well-organized with headers
• Operations: ⚠️ No explicit run-order contract for concurrent meta-orchestrators
• Norms: ❌ Missing governance/approval norms
• Safeguards: ❌ Memory-path failures, auth failures not covered

scratchpad/architecture.md (index 21)

Analysis

• Goals: Visual package map with last-updated timestamp (2026-07-06).
• Risks: No stated owner or update trigger — diagram will drift from code.
• Missing: No version pinning or "accurate as of" commit SHA.

REASONS Canvas

• Requirements: ⚠️ Purpose stated but not linked to any spec
• Entities: ✅ All packages listed with layers
• Approach: ✅ Diagram + table provides good coverage
• Structure: ✅ Clean layout
• Operations: ❌ No update policy
• Norms: ❌ No authorship/ownership noted
• Safeguards: ❌ No note on what to do when diagram is stale

scratchpad/artifact-naming-compatibility.md (index 22)

Analysis

• Goals: Explain backward/forward compat between old (pre-v5) and new (v5+) artifact names.
• Risks: silently handles unexpected files — no error path documented.
• Missing: No schema or type definition for the artifact format itself.

REASONS Canvas

• Requirements: ✅ Old vs new naming clearly specified
• Entities: ✅ Tables cover all known artifact types
• Approach: ✅ Step-by-step download process explained
• Structure: ✅ Compatibility matrix is clear
• Operations: ⚠️ Test section names test functions but omits file paths
• Norms: ⚠️ No note on who owns the constants used
• Safeguards: ❌ No edge-case coverage for flattening failures

scratchpad/breaking-cli-rules.md (index 23)

Analysis

• Goals: Define breaking change criteria for CLI maintainers/contributors.
• Risks: Exit-code table is incomplete; schema-change example is missing from Changeset Format section.
• Missing: No stated governance (who approves major bumps).

REASONS Canvas

• Requirements: ✅ Clear categories with examples
• Entities: ✅ Decision tree present
• Approach: ✅ Comprehensive with contributor checklist
• Structure: ✅ Well-structured
• Operations: ⚠️ Deprecation "at least one minor release" is vague — no exact version window defined
• Norms: ❌ No approval quorum stated
• Safeguards: ⚠️ No mention of what happens when a breaking change ships without a major bump

Sync Follow-ups

• ****: Sync with directory on every PR that adds or removes a Go package — consider a CI check.
• ****: Keep in sync with package — any rename of , , or must trigger a doc update.
• ****: Sync with quarterly — verify that all listed examples still match actual version numbers.
• ****: Sync the shared-memory file list with actual files written by each meta-orchestrator after each major meta-orchestrator change.

Context

Field	Value
Files reviewed	, , , ,
Rotation index	19–23 of 92 spec-relevant files
Next run starts at	index 24
Workflow run	§29595486699

References:

• §29595486699

Generated by 📋 Daily SPDD Spec Planner · 26.3 AIC · ⌖ 7.81 AIC · ⊞ 4.8K · ◷

• expires on Jul 20, 2026, 8:25 AM UTC-08:00