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

[github-actions]

Summary

Reviewed 5 ADRs (indices 45–49) covering: pkg/workflow helper file organization (ADR-27325), parser utility test strategy (ADR-27327), compile-all frontmatter filtering (ADR-27387), safe-outputs.needs extensibility (ADR-27476), and comment-memory cross-run persistence (ADR-27479). All five ADRs are in Draft status and require implementation verification, conformance review, and sync follow-ups. Key gaps: missing REASONS canvas coverage, weak or absent safeguards sections, and no test-strategy linkage for ADR-27476/27479.

Priority Work Queue

P0 — Conformance gaps

• ADR-27387 Normative §Error Handling rule 1 has no corresponding test: I/O errors during frontmatter filter must propagate as compile-time errors.
• ADR-27476 Validation rules 1 & 2 lack negative test coverage in known test files.

P1 — Safeguards & norms weaknesses

• ADR-27479 has no safeguard against prompt-size blowup from unbounded memory files.
• ADR-27325 lacks a norms section enforcing the file-organization precedent (no lint or CI guard defined).

P2 — Status promotion and sync

• All five ADRs remain in Draft; none have been promoted to Accepted after implementation.
• Sync follow-up tasks missing for ADR-27327 (test naming collision prevention) and ADR-27476 (schema update tracking).

SPDD Checklist

• [/spdd-analysis ADR-27325] Confirm engine_api_targets.go exists in pkg/workflow/ and awf_helpers.go no longer contains extractAPITargetHost; update ADR status from Draft → Accepted if conformant.
• [/spdd-generate ADR-27325] Add a CI lint rule or grep-based check that rejects engine-API-target helpers in awf_helpers.go to enforce the file-organization norm durably.
• [/spdd-analysis ADR-27327] Verify pkg/parser test files use IsWorkflowSpec (exported) not isWorkflowSpec; confirm TestIsNotFoundError collision is resolved; update status if conformant.
• [/spdd-generate ADR-27387] Add a unit test in pkg/workflow/compile_file_operations_test.go (or equivalent) that triggers an os.ReadFile error during frontmatter filtering and asserts a compile-time error is returned (covers Normative §Error Handling rule 1).
• [/spdd-reasons-canvas ADR-27476] Fill in the missing REASONS canvas sections: Safeguards (what happens if needs cycle is introduced?) and Norms (schema version bump policy for safe-outputs.needs additions).
• [/spdd-generate ADR-27476] Add negative tests for validateSafeOutputsNeeds in the relevant test file: assert compile errors for (a) built-in job name reference and (b) undeclared job name reference.
• [/spdd-reasons-canvas ADR-27479] Add Safeguards entry: define a maximum memory file size and total memory directory size cap to prevent prompt-size and GitHub comment-size overflow.
• [/spdd-generate ADR-27479] Implement or file a task for the memory-size cap described above; add corresponding validation to the pre-agent setup step that truncates or errors on oversized memory files.
• [/spdd-sync ADR-27479] Update the W3C-style safe-outputs specification (referenced in the ADR Consequences) to include the comment_memory type, end-to-end data flow, and the memory-size safeguard.
• [/spdd-sync ADR-27476] Confirm main_workflow_schema.json reflects the safe-outputs.needs field and that IDE-integration documentation references the updated schema.

Per-Spec Findings

ADR-27325 — Organize pkg/workflow Helpers by Semantic Responsibility

Status: Draft | REASONS gaps: Safeguards absent (no CI enforcement of file-org rule), Norms section weak (pattern stated but not enforced).

• ✅ Requirements: clear decision and rationale.
• ✅ Entities: engine_api_targets.go, awf_helpers.go, config_helpers.go named explicitly.
• ✅ Approach: extract-and-deduplicate pattern well described.
• ⚠️ Structure: file count increase acknowledged but no navigation guide or convention doc updated.
• ✅ Operations: behavior-preserving refactor, signatures unchanged.
• ⚠️ Norms: states the pattern but provides no automated guard (lint/grep) to prevent regression.
• ❌ Safeguards: no CI check defined to enforce that awf_helpers.go stays free of API-target helpers.

ADR-27327 — Parser Utility Test Strategy

Status: Draft | REASONS gaps: Safeguards section absent; no coverage metric or CI threshold defined.

• ✅ Requirements: test-through-exported-API and table-driven requirements clearly stated.
• ✅ Entities: affected test files named (import_remote_nested_test.go).
• ✅ Approach: rationale for rejecting private-helper testing well documented.
• ✅ Structure: naming uniqueness rule specified.
• ✅ Operations: require.ErrorContains usage mandated.
• ⚠️ Norms: no minimum table row count per predicate (only a qualitative "at minimum").
• ❌ Safeguards: no coverage threshold or CI gate ensuring exported-API test coverage is maintained.

ADR-27387 — Filter Non-Frontmatter Markdown During compile-all

Status: Draft | REASONS gaps: Error handling test missing; debug-log SHOULD not enforced.

• ✅ Requirements: filter logic precisely defined (first-line --- check).
• ✅ Entities: compile_file_operations.go and compile_pipeline.go both named.
• ✅ Approach: strict bytes comparison, BOM exclusion documented.
• ✅ Structure: composable filter step, getMarkdownWorkflowFiles left unchanged.
• ⚠️ Operations: os.ReadFile error propagation is a MUST but has no corresponding test case identified.
• ✅ Norms: caching MAY is noted.
• ⚠️ Safeguards: silent-skip risk for malformed frontmatter acknowledged but no authoring-time warning defined.

ADR-27476 — Extend safe_outputs Job Dependencies via safe-outputs.needs

Status: Draft | REASONS gaps: Safeguards (cycle detection) and Norms (schema bump policy) sections absent.

• ✅ Requirements: explicit needs-declaration pattern clearly specified.
• ✅ Entities: main_workflow_schema.json, validateSafeOutputsNeeds, validateSafeJobNeeds named.
• ✅ Approach: merge-and-deduplicate with compile-time validation.
• ✅ Structure: import-merge behavior specified.
• ⚠️ Operations: no mention of what happens when safe-outputs.needs creates a dependency cycle in the compiled workflow.
• ❌ Norms: no schema version bump convention defined.
• ❌ Safeguards: cycle-detection requirement absent; no mention of actionlint post-compile validation.

ADR-27479 — Comment Memory: File-Based Agent Memory with GitHub Persistence

Status: Draft | REASONS gaps: Safeguards (size limits, accidental edit) weakly covered; Norms (memory_id naming) incomplete.

• ✅ Requirements: memory materialization and auto-sync flow fully specified.
• ✅ Entities: /tmp/gh-aw/comment-memory/, XML marker format, memory_id pattern defined.
• ✅ Approach: file-edit-based memory decouples agent from persistence.
• ✅ Structure: pre-agent setup + post-turn sync lifecycle described.
• ⚠️ Operations: no retry or conflict-resolution policy for concurrent comment upserts.
• ⚠️ Norms: memory_id pattern specified but no maximum length or reserved-word exclusion.
• ❌ Safeguards: no maximum memory file size, no total directory size cap, no limit on number of memory slots — all of which could blow up prompt size or GitHub comment limits.

Sync Follow-ups

• ADR-27325: After implementation confirmed, update docs/adr/27325-*.md status to Accepted; add cross-reference to any new CONTRIBUTING.md or file-org convention doc.
• ADR-27327: Add a note to the ADR linking to the test files modified; confirm go test ./pkg/parser/... passes with the renamed test function.
• ADR-27387: After I/O-error test is added, update ADR status; add a note in the compile-all user documentation about silent-skip behavior for non-frontmatter files.
• ADR-27476: After schema update, bump schema version and update any IDE/editor integration references; add actionlint post-compile validation note to ADR.
• ADR-27479: Sync the W3C-style safe-outputs spec document with the comment_memory type; document the memory-size cap in the agent prompt guidance section of the ADR.

Context

• Files reviewed: docs/adr/27325-organize-workflow-helpers-by-semantic-responsibility.md, docs/adr/27327-parser-utility-test-strategy.md, docs/adr/27387-filter-non-frontmatter-markdown-during-compile-all.md, docs/adr/27476-extend-safe-outputs-dependencies-via-needs-field.md, docs/adr/27479-comment-memory-file-based-agent-memory-with-github-persistence.md
• Rotation index: 44 → 49 (of 688 total files)
• Run: §30024508515

Generated by 📋 Daily SPDD Spec Planner · sonnet46 · 30.8 AIC · ⌖ 6.76 AIC · ⊞ 4.9K · ◷

• expires on Jul 26, 2026, 8:24 AM UTC-08:00