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

[github-actions]

Summary

Daily SPDD spec work plan reviewing 5 ADR specifications (indices 50–54 of 719). All five are Draft status and span memory architecture (ADR-27479), refactoring hygiene (ADR-27523), schema migration (ADR-27626), security domain alignment (ADR-27639), and access-mode unification (ADR-27707). Several have weak or missing REASONS Canvas sections — particularly around Safeguards and Norms — and lack explicit Sync Follow-up tasks linking spec changes to implementation files.

Priority Work Queue

P0 — Spec gaps requiring immediate attention:

• ADR-27479 (Comment Memory): Safeguards and Norms are in narrative only; Part 2 lacks standalone normative sections with MUST constraints mapped to source files.
• ADR-27626 (sandbox.agent.version): Norms section missing entirely; numeric-type normalization risk is noted in Consequences but not covered by normative MUST/MUST NOT.

P1 — Structural improvements:

• ADR-27523 (actionpins helpers): Part 2 lacks an Operations sequencing constraint for initWarnings call ordering.
• ADR-27639 (allowed-domains parity): No Sync Follow-up tasks; reference docs not updated to reflect the new dual scope of safe-outputs.allowed-domains.
• ADR-27707 (tools.github.mode): Ambiguous edge case when tools.github.mode: local and tools.github.type: remote coexist — no MUST tie-break rule.

P2 — Maintenance:

• All five ADRs remain in Draft status; formal acceptance decisions are overdue.

SPDD Checklist

• [/spdd-generate] ADR-27479: Add a normative ### Safeguards section to Part 2 of docs/adr/27479-comment-memory-file-based-agent-memory-with-github-persistence.md with MUST constraints for the 16 KiB per-file and 48 KiB total limits, cross-referencing actions/setup/js/comment_memory_helpers.cjs. Done when Part 2 has a standalone Safeguards heading with at least 2 MUST items.
• [/spdd-generate] ADR-27479: Add a normative ### Norms section to Part 2 of the same file specifying that the size-cap constants in comment_memory_helpers.cjs MUST stay aligned with this spec and with setup_comment_memory_files.test.cjs. Done when both file paths are referenced in the Norms section.
• [/spdd-generate] ADR-27626: Add a normative ### Norms section to docs/adr/27626-sandbox-agent-version-and-network-firewall-migration.md with MUST constraints covering numeric YAML type normalization for all int and float variants. Done when the section addresses at least 4 distinct YAML numeric types.
• [/spdd-analysis] ADR-27626: Add a MUST NOT constraint clarifying that the codemod MUST NOT emit a version key when migrating network.firewall: false or "disable" forms. Done when the normative Codemod Migration section explicitly forbids a version key for the disable case.
• [/spdd-generate] ADR-27523: Add an ### Operations section to Part 2 of docs/adr/27523-extract-pure-helpers-in-actionpins.md stating that initWarnings MUST be called before any write to ctx.Warnings within any code path in ResolveActionPin. Done when the Operations section has at least 1 MUST sequencing constraint.
• [/spdd-sync] ADR-27639: Update docs/src/content/docs/reference/safe-outputs.md to add a note that safe-outputs.allowed-domains affects both input sanitization (the sanitized activation step) and output sanitization. Done when the reference doc contains a sentence describing the dual scope.
• [/spdd-reasons-canvas] ADR-27707: Add a MUST tie-break rule to docs/adr/27707-unify-github-access-mode-under-tools-github-mode.md for the case where tools.github.mode is local or remote and tools.github.type is also set. Done when one MUST rule in Part 2 resolves which field wins for MCP transport selection.
• [/spdd-reasons-canvas] ADR-27707: Add an ### Entities section listing tools.github.mode, tools.github.type, and features.cli-proxy as formal entities with their value domains and invariants. Done when all three entities are described.
• [/spdd-sync] All 5 ADRs: Change status from Draft to Accepted (or open a blocking question) in each file. Done when no ADR in this batch retains Status: Draft without a linked blocker.
• [/spdd-analysis] ADR-27639: Confirm that TestComputeTextStepIncludesAllowedDomainsEnv (or equivalent) tests GH_AW_ALLOWED_DOMAINS in the compiled sanitized activation step, separate from output-side tests. Done when the test location is identified and verified in the test suite.

Per-Spec Findings

ADR-27479 — Comment Memory (Accepted)

REASONS Canvas assessment:

• Requirements: Well-covered. Size cap requirements are present in narrative.
• Entities: Implicit — comment-memory XML block, memory_id, /tmp/gh-aw/comment-memory/ directory are named but not listed as formal entities with invariants.
• Approach: Decision rationale and three rejected alternatives are thorough.
• Structure: Memory file layout described in prose; a path-to-purpose table would sharpen it.
• Operations: Ordering (materialize before agent run, sync after each turn) is described but scattered across Narrative and Normative sections.
• Norms: Present in Narrative ### Norms subsection but not formally in Part 2 normative text.
• Safeguards: Size-cap safeguards appear in narrative but Part 2 has no matching ### Safeguards heading — risks being overlooked in implementation reviews.

Open questions:

• No constraint on how sync failures are surfaced (silent skip vs. warning vs. hard error).
• No limit on the number of memory slots per managed comment.

ADR-27523 — Extract Pure Helpers in actionpins (Draft)

REASONS Canvas assessment:

• Requirements: Implicitly covered (testability, nil-guard elimination).
• Entities: Three helper functions named; input/output signatures not specified.
• Approach: Concise and appropriate scope.
• Structure: No structural spec for test file naming convention.
• Operations: No sequencing constraint on when initWarnings must be called.
• Norms: Logging side-effect noted in Consequences; not codified as a normative SHOULD.
• Safeguards: None — acceptable for an internal refactor.

Open questions:

• Should tests that call countPinKeyMismatches suppress log output, or is test noise acceptable?

ADR-27626 — sandbox.agent.version Migration (Draft)

REASONS Canvas assessment:

• Requirements: Codemod coverage is well-specified for all 5 value forms.
• Entities: Fields named but not described as schema entities with types and value domains.
• Approach: Two alternatives considered with clear reasoning.
• Structure: No before/after schema mapping table.
• Operations: Codemod execution order not specified.
• Norms: Entirely absent.
• Safeguards: Numeric type risk is noted in Consequences but not given a formal constraint.

Open questions:

• If a workflow has both network.firewall and an existing sandbox.agent block, the MUST NOT add rule applies — but what if only sandbox.agent.version is missing from the existing block?

ADR-27639 — Allowed-Domains Activation Parity (Draft)

REASONS Canvas assessment:

• Requirements: Input/output parity requirement is clearly stated.
• Entities: sanitized step, GH_AW_ALLOWED_DOMAINS, helper functions named but not listed as formal entities.
• Approach: Two rejected alternatives with solid reasoning.
• Structure: No spec on the env-var assembly block structure in generated YAML.
• Operations: No ordering spec for env-var emission.
• Norms: Missing. No naming convention for sanitization helpers.
• Safeguards: Security motivation is in Context but no formal constraint on behavior with malformed domain values.

Open questions:

• What happens if safe-outputs.allowed-domains contains an invalid value (wildcard, non-domain string)? Should the compiler error, warn, or pass it through?

ADR-27707 — tools.github.mode Unification (Draft)

REASONS Canvas assessment:

• Requirements: Three access modes identified; backward compatibility requirements present.
• Entities: Fields named but value domains not formally listed.
• Approach: Two alternatives rejected with clear rationale.
• Structure: No mode×type matrix table.
• Operations: Codemod idempotency stated; resolution order when both mode and type exist is ambiguous.
• Norms: Missing. No norm on updating reference docs when new mode values are added.
• Safeguards: No constraint on compiler behavior for unknown tools.github.mode values.

Open questions:

• When tools.github.mode: local and tools.github.type: remote coexist, which wins for MCP transport? The spec does not resolve this.
• No MUST on warning message format for unrecognized mode values.

Sync Follow-ups

• After ADR-27479 Safeguards section update: verify actions/setup/js/comment_memory_helpers.cjs exports constants importable by tests without running the full setup script.
• After ADR-27707 precedence clarification: update docs/src/content/docs/reference/github-tools.md or tools.md to include a mode×type precedence table.
• After ADR-27639 scope note added to reference docs: scan docs/src/content/docs/reference/environment-variables.md for GH_AW_ALLOWED_DOMAINS and confirm the input-sanitization scope is documented.
• After all Drafts are accepted: add a ### Sync Notes subsection to each ADR listing implementation files that must stay aligned with the normative spec.

Context

Field	Value
Files reviewed	5 (indices 50–54 of 719 total)
Rotation index after run	54
Run URL	§30165115988

Files: docs/adr/27479-comment-memory-file-based-agent-memory-with-github-persistence.md, docs/adr/27523-extract-pure-helpers-in-actionpins.md, docs/adr/27626-sandbox-agent-version-and-network-firewall-migration.md, docs/adr/27639-unify-activation-sanitize-allowed-domains.md, docs/adr/27707-unify-github-access-mode-under-tools-github-mode.md

References:

• §30165115988

Generated by 📋 Daily SPDD Spec Planner · sonnet46 · 40.4 AIC · ⌖ 5.68 AIC · ⊞ 4.9K · ◷

• expires on Jul 28, 2026, 8:18 AM UTC-08:00