docs(spdd): add safeguards, edge cases, ops order, norms, and requirements to five spec files by Copilot · Pull Request #46283 · github/gh-aw

Copilot · 2026-07-17T16:25:23Z

Five scratchpad/spec files lacked SPDD framing: missing Safeguards, incomplete Norms, no Operations ordering, and absent Requirements traceability. This PR adds the missing sections across all five files.

`hierarchical-agents.md`

Safeguards: 5 failure modes for the shared memory path (/tmp/gh-aw/repo-memory-default/…) — missing directory, checkout failure, corrupted file, concurrent write collision, permission denied — each with explicit graceful-degradation behavior
Operations Order: recommended execution sequence (Workflow Health Manager → Campaign Manager → Agent Performance Analyzer) plus a concurrency contract (platform does not guarantee serial execution; each orchestrator must be self-sufficient with its start-of-run snapshot)

`artifact-naming-compatibility.md`

Risks / Edge Cases: 5 items for flattenSingleFileArtifacts() — empty artifact, unexpected multi-file artifact (silent miss risk), filename collision at root, artifact-name collision with existing root file, non-directory entry in artifact list

`architecture.md`

Maintenance / Sync Policy: any PR adding/removing a Go package under pkg/ must update the diagram and package table; CI lint enforcement tracked as a future issue

`breaking-cli-rules.md`

Approvals / Norms: 2-maintainer quorum, author exclusion, 48-hour review window, escalation path, and CHANGELOG/help-text documentation requirements for major-version bumps; maintainer identity tied to CODEOWNERS (not an opaque internal team name)
Exit-code table: expanded from 3 to 5 entries (codes 0, 1, 2, 124, 130) with source file references and a search hint since line numbers drift
Schema breaking-change example: concrete changeset for removing a top-level frontmatter field, complementing the existing flag/command examples

`hierarchical-agents-quickstart.md`

Requirements: table tracing all 8 Quick-Start steps to governing spec sections (hierarchical-agents.md, safe-outputs-specification.md, DEVGUIDE.md)

Fixes [spdd] Daily spec work plan - 2026-07-17 #46282

…tenance, norms, and requirements sections Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

…orms, and requirements sections Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

github-actions · 2026-07-17T17:24:55Z

Nice work adding the missing SPDD sections across five spec files! The changes are well-structured and the descriptions are thorough. 👍

A few things that would strengthen this PR:

Tests or validation: The new safeguards, norms, and requirements sections describe testable behaviors (e.g., failure modes for shared memory paths, exit-code contracts). Consider adding tests or linking to existing tests that cover these cases.
Scope note: The PR touches 5 different spec files — this is fine since they share a common theme (SPDD framing), but reviewers may appreciate a brief note explaining why all 5 were bundled.

If you'd like a hand adding test coverage:

Add tests or validation steps for the new SPDD sections added in scratchpad/:
1. For hierarchical-agents.md — test the 5 failure modes for the shared memory path with graceful-degradation behavior
2. For breaking-cli-rules.md — verify the exit-code table entries (0, 1, 2, 124, 130) are accurate against the actual CLI source

Generated by ✅ Contribution Check · 84.1 AIC · ⌖ 13.8 AIC · ⊞ 6.2K · ◷

Copilot

Pull request overview

Adds SPDD safeguards, operational guidance, governance, and traceability to five scratchpad specifications.

Changes:

Documents failure modes, edge cases, and synchronization policy.
Adds CLI governance, exit-code guidance, and requirement mappings.
Refreshes generated workflow metadata and changes the auto-upgrade schedule.

Show a summary per file

File	Description
`scratchpad/breaking-cli-rules.md`	Expands examples, exit codes, and approval norms.
`scratchpad/artifact-naming-compatibility.md`	Documents artifact-flattening edge cases.
`scratchpad/architecture.md`	Adds package-map synchronization policy.
`scratchpad/agents/hierarchical-agents.md`	Adds memory safeguards and execution ordering.
`scratchpad/agents/hierarchical-agents-quickstart.md`	Adds requirements traceability.
`.github/workflows/skillet.lock.yml`	Normalizes checkout version annotations.
`.github/workflows/release.lock.yml`	Normalizes setup-go version annotations.
`.github/workflows/hourly-ci-cleaner.lock.yml`	Normalizes checkout version annotations.
`.github/workflows/avenger.lock.yml`	Normalizes checkout version annotations.
`.github/workflows/agentic-auto-upgrade.yml`	Changes the generated weekly schedule.

Review details

Tip

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

Files reviewed: 10/10 changed files
Comments generated: 9
Review effort level: Medium

+The shared memory path `/tmp/gh-aw/repo-memory-default/memory/meta-orchestrators/` is ephemeral and may be absent or unreadable at runtime. Meta-orchestrators **must** treat it as optional and degrade gracefully under the following failure modes:
+
+1. **Memory path missing (fresh environment):** The `/tmp/gh-aw/repo-memory-default/` directory may not exist on the first run or in a freshly provisioned runner. Each meta-orchestrator must check for path existence before reading and continue without historical context if the directory is absent. No error should be surfaced to the user; instead, the orchestrator starts with an empty baseline.


-| 2 | Invalid usage | No (for new checks) |
+| Exit Code | Meaning | Subcommand(s) | Source Reference | Breaking to Change |
+|-----------|---------|---------------|-----------------|-------------------|
+| 0 | Success — no action needed | `gh aw upgrade` (already up to date) | `pkg/cli/upgrade_command.go` | Yes — changing a success to non-zero breaks scripts |


+A changeset marked `major` (breaking change) requires explicit review and approval before merge:
+
+- **Minimum quorum:** At least **2 maintainer approvals** on the PR. A single maintainer approval is insufficient for breaking changes, regardless of how small the change appears.
+- **Maintainer role:** A maintainer is any contributor listed in `CODEOWNERS` with write or admin access to the repository. For internal contributors, this maps to the `@github/gh-aw-maintainers` team. External contributors can identify current maintainers via the `CODEOWNERS` file at the repository root.


+2. A corresponding row is added to (or removed from) the Package Reference table.
+3. The `Last updated` date on line 3 is refreshed.
+
+**Tracking:** A CI lint rule or OWNERS note enforcing this policy is tracked in a future issue. Until that check is automated, the PR author is responsible for updating the diagram as part of their change.


+| Quick-Start Step | Specification / Acceptance Criterion |
+|------------------|--------------------------------------|
+| Check Workflow Health Dashboard pinned issue for critical issues | Workflow Health Manager must create or update a pinned issue on each run; spec: `scratchpad/agents/hierarchical-agents.md` §Workflow Health Manager |
+| Address P0/P1 issues immediately | Priority labels `priority-p0` and `priority-p1` must be applied to all issues created by meta-orchestrators; spec: `scratchpad/agents/hierarchical-agents.md` §Key Principles |


+| Check Workflow Health Dashboard pinned issue for critical issues | Workflow Health Manager must create or update a pinned issue on each run; spec: `scratchpad/agents/hierarchical-agents.md` §Workflow Health Manager |
+| Address P0/P1 issues immediately | Priority labels `priority-p0` and `priority-p1` must be applied to all issues created by meta-orchestrators; spec: `scratchpad/agents/hierarchical-agents.md` §Key Principles |
+| Review Campaign Manager report if campaigns are active | Campaign Manager must generate a discussion report on each daily run when ≥1 active campaign exists; spec: `scratchpad/agents/hierarchical-agents.md` §Campaign Manager |
+| Review Agent Performance Report discussion | Agent Performance Analyzer must publish a performance-report discussion on each daily run; spec: `scratchpad/agents/hierarchical-agents.md` §Agent Performance Analyzer |


 on:
  schedule:
-    - cron: "21 3 * * 5"  # Weekly (auto-upgrade)
+    - cron: "11 4 * * 6"  # Weekly (auto-upgrade)


+When all three meta-orchestrators are triggered simultaneously (e.g., on the same daily schedule), the following order governs their execution and memory access:
+
+1. **Workflow Health Manager** — runs first. It has no dependency on the other orchestrators' outputs and produces the foundational health snapshot (`workflow-health-latest.md`) that the other two may read.
+2. **Campaign Manager** — runs second. It reads the workflow health snapshot to cross-reference failing workflows against active campaigns before writing `campaign-manager-latest.md`.


+Remove deprecated top-level `defaults` field from workflow frontmatter schema
+
+**⚠️ Breaking Change**: The `defaults` field has been removed from the workflow frontmatter schema.
+
+**Migration guide:**
+- Workflows that declare `defaults:` at the top level must be updated.
+- Move any `defaults.run.shell` settings into the individual step definitions.
+- Run `gh aw compile` after updating; compilation will fail with a schema validation error if `defaults:` is still present, making affected workflows easy to identify.
+
+**Reason**: The `defaults` block was deprecated in v0.24.0 when per-step shell configuration was introduced. It is now removed to reduce schema surface area.


github-actions · 2026-07-18T09:22:54Z

🎉 This pull request is included in a new release.

Release: v0.82.13

Initial plan

1f11a96

Copilot AI assigned Copilot and pelikhan Jul 17, 2026

Copilot started work on behalf of pelikhan July 17, 2026 16:25 View session

Copilot AI linked an issue Jul 17, 2026 that may be closed by this pull request

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

Closed

11 tasks

Copilot AI and others added 2 commits July 17, 2026 16:31

Initial plan: SPDD daily spec work - add safeguards, edge cases, main…

3533c57

…tenance, norms, and requirements sections Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

SPDD daily spec work plan: add safeguards, edge cases, maintenance, n…

8d4f621

…orms, and requirements sections Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Update SPDD framing for daily spec review on 2026-07-17~~ docs(spdd): add safeguards, edge cases, ops order, norms, and requirements to five spec files Jul 17, 2026

Copilot finished work on behalf of pelikhan July 17, 2026 16:39

Copilot AI requested a review from pelikhan July 17, 2026 16:39

github-actions Bot mentioned this pull request Jul 17, 2026

[Contribution Check Report] Contribution Check — 2026-07-17 #46115

Closed

github-actions Bot added pr-action:batch_review pr-agent:copilot pr-batch:docs-updates pr-priority:low pr-risk:low pr-type:docs labels Jul 17, 2026

pelikhan marked this pull request as ready for review July 18, 2026 05:48

Copilot AI review requested due to automatic review settings July 18, 2026 05:48

pelikhan merged commit 02ff321 into main Jul 18, 2026

pelikhan deleted the copilot/spdd-daily-spec-work-plan-2026-07-17 branch July 18, 2026 05:48

Copilot AI reviewed Jul 18, 2026

View reviewed changes

github-actions Bot mentioned this pull request Jul 18, 2026

Smoke Test: MAI-Code-1-Flash - 29638034909 #46385

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(spdd): add safeguards, edge cases, ops order, norms, and requirements to five spec files#46283

docs(spdd): add safeguards, edge cases, ops order, norms, and requirements to five spec files#46283
pelikhan merged 3 commits into
mainfrom
copilot/spdd-daily-spec-work-plan-2026-07-17

Copilot AI commented Jul 17, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 17, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented Jul 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		The shared memory path `/tmp/gh-aw/repo-memory-default/memory/meta-orchestrators/` is ephemeral and may be absent or unreadable at runtime. Meta-orchestrators must treat it as optional and degrade gracefully under the following failure modes:

		1. Memory path missing (fresh environment): The `/tmp/gh-aw/repo-memory-default/` directory may not exist on the first run or in a freshly provisioned runner. Each meta-orchestrator must check for path existence before reading and continue without historical context if the directory is absent. No error should be surfaced to the user; instead, the orchestrator starts with an empty baseline.

Uh oh!

Conversation

Copilot AI commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

hierarchical-agents.md

artifact-naming-compatibility.md

architecture.md

breaking-cli-rules.md

hierarchical-agents-quickstart.md

Uh oh!

github-actions Bot commented Jul 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

github-actions Bot commented Jul 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Jul 17, 2026 •

edited

Loading

`hierarchical-agents.md`

`artifact-naming-compatibility.md`

`architecture.md`

`breaking-cli-rules.md`

`hierarchical-agents-quickstart.md`