From 68068953330cf2e659f9e6c09bc6a3c3f8f1a628 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 25 Jul 2026 14:06:30 +0000 Subject: [PATCH] docs: consolidate developer specifications into instructions file (v9.22) Weekly tone/consistency maintenance pass over scratchpad/ and specs/. - Fixed 1 previously-missed tone issue in breaking-cli-rules.md:220 (removed subjective 'easy to identify' clause; stated concrete schema-validation-error behavior). - Rescanned scratchpad/ (63 spec files) and specs/ (10 files): otherwise clean of marketing/subjective language. - Bumped dev.md to v9.22 (2026-07-25) and appended a Document History entry. Co-Authored-By: Claude Opus 4.8 (1M context) --- scratchpad/breaking-cli-rules.md | 2 +- scratchpad/dev.md | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/scratchpad/breaking-cli-rules.md b/scratchpad/breaking-cli-rules.md index 2f7393463c2..41a71dfab18 100644 --- a/scratchpad/breaking-cli-rules.md +++ b/scratchpad/breaking-cli-rules.md @@ -217,7 +217,7 @@ Remove deprecated top-level `defaults` field from 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. +- Run `gh aw compile` after updating; if `defaults:` is still present, compilation fails with a schema validation error that reports the offending workflow. **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. ``` diff --git a/scratchpad/dev.md b/scratchpad/dev.md index ffe4752062f..b6f7366395f 100644 --- a/scratchpad/dev.md +++ b/scratchpad/dev.md @@ -1,7 +1,7 @@ # Developer Instructions -**Version**: 9.21 -**Last Updated**: 2026-07-18 +**Version**: 9.22 +**Last Updated**: 2026-07-25 **Purpose**: Consolidated development guidelines for GitHub Agentic Workflows This document consolidates specifications from the scratchpad directory into unified developer instructions. It provides architecture patterns, security guidelines, code organization rules, and testing practices. @@ -2977,6 +2977,7 @@ These files are loaded automatically by compatible AI tools (e.g., GitHub Copilo --- **Document History**: +- v9.22 (2026-07-25): Maintenance tone scan — fixed 1 previously-missed tone issue in `scratchpad/`: `breaking-cli-rules.md` (1 fix: "compilation will fail with a schema validation error if `defaults:` is still present, making affected workflows easy to identify" → "if `defaults:` is still present, compilation fails with a schema validation error that reports the offending workflow" line 220 — the trailing "easy to identify" clause is subjective editorializing of a diagnostic the schema validation error already provides; removing the vague "easy" and stating the concrete behavior matches the v9.10 "Extensive test suite validates" → "Test suite validates" drop-the-qualifier pattern; this instance sat inside an example changeset code fence, which is why prior passes read past it). Re-ran the strong-marketing scan (`powerful`/`seamless`/`effortless`/`blazing`/`cutting-edge`/`state-of-the-art`/`world-class`/`revolutionary`/`game-changing`/`battle-tested`/etc.) and the subjective-intensifier scan (`leverage`/`comprehensive`/`extensive`/`robust`/`sophisticated`/`elegant`/`deep dive`/`amazing`/`intuitive`/`magical`/`supercharge`/etc.) across the rest of `scratchpad/`: no further source-text matches; the only remaining directory hits are inside this file's own Document History (which records prior fixes) and the two legitimate `no magic` negations in `mdflow.md` (line 229) and `mdflow-comparison.md` (line 553, "No magic mapping"), unchanged since v9.18. Re-scanned the `specs/` directory (10 top-level files) and found it clean of new strong-marketing and vague "simply/easy-to-use" language; the only intensifier matches remain the deliberately-retained normative and conformance-taxonomy items, all reserved for a spec owner and unchanged in wording from v9.21: the IS-04..IS-09 MUST clause "comprehensive input sanitization" (`security-architecture-spec-validation.md` line 89) and its paired ✅ VERIFIED status echoing that wording (line 154); the "Production-ready security"/"Production-ready deployment" conformance-level names in the RFC-2119 taxonomies (`security-architecture-spec.md` line 144, `security-architecture-spec-summary.md` line 22, `replace-label-spec.md` line 108); and `replace-label-spec.md` line 383's "simply adds", which is normative prose meaning "merely adds", not marketing. Git history in the analysis sandbox was shallow (only `ec4cabb`, "Refresh update-time container digests and enforce commit-age cooldowns (#47990)", visible); prior-state comparison was reconstructed from this Document History. Cache-memory at `/tmp/gh-aw/cache-memory/` was again not accessible from the analysis sandbox this run. Coverage: unchanged from v9.21 (63 scratchpad spec files + 10 specs files = 73 files; `dev.md` and `README.md` excluded as non-spec, and `specs/forecast-compliance-fixtures/README.md` excluded as non-spec content). - v9.21 (2026-07-18): Maintenance tone scan — `scratchpad/` clean (0 tone issues across all 63 spec files). The strong-marketing scan (`powerful`/`seamless`/`effortless`/`blazing`/`cutting-edge`/`state-of-the-art`/`world-class`/`revolutionary`/`game-changing`/`battle-tested`/`first-class`/`out-of-the-box`/etc.) and the subjective-intensifier scan (`leverage`/`comprehensive`/`extensive`/`robust`/`sophisticated`/`elegant`/`deep dive`/etc.) returned no source-text matches; the only directory hits are inside this file's own Document History (which records prior fixes) and the two legitimate `no magic` negations in `mdflow.md` (line 229) and `mdflow-comparison.md` (line 553), unchanged since v9.18. A supplementary sweep for `great`/`amazing`/`intuitive`/`magical`/`supercharge`/etc. surfaced nothing new. Re-scanned the `specs/` directory (10 top-level files) and found it clean of new strong-marketing and vague "simply/easy-to-use" language; the only intensifier matches remain the deliberately-retained normative and conformance-taxonomy items, all reserved for a spec owner and unchanged in wording from v9.20: the IS-04..IS-09 MUST clause "comprehensive input sanitization" (`security-architecture-spec-validation.md` line 89, drifted +4 lines from v9.20's line 85) and its paired ✅ VERIFIED status echoing that wording (line 154, drifted +4 from v9.20's line 150); and the "Production-ready security"/"Production-ready deployment" conformance-level names in the RFC-2119 taxonomies (`security-architecture-spec.md` line 144, `security-architecture-spec-summary.md` line 22, `replace-label-spec.md` line 108), plus `replace-label-spec.md` line 383's "simply adds", which is normative prose meaning "merely adds", not marketing. The only commit touching `scratchpad/`/`specs/` since v9.20 (`6d80d52`, "auto-triage: add safe-outputs/copilot component labels, fix partial-triage gap") re-synced the full spec tree — the +4 line drift in `security-architecture-spec-validation.md` originates there — without introducing new tone violations. Cache-memory at `/tmp/gh-aw/cache-memory/` was not accessible from the analysis sandbox this run; historical context was reconstructed from this Document History instead. No tone issues introduced since v9.20. Coverage: 63 scratchpad spec files + 10 specs files = 73 files (unchanged from v9.20; the `specs/forecast-compliance-fixtures/README.md` fixture is excluded as non-spec content). - v9.20 (2026-07-11): Maintenance tone scan — `scratchpad/` clean (0 tone issues across all 63 spec files). The strong-marketing scan (`powerful`/`seamless`/`effortless`/`blazing`/`cutting-edge`/`state-of-the-art`/`world-class`/`revolutionary`/etc.) and the subjective-intensifier scan (`leverage`/`comprehensive`/`extensive`/`robust`/`sophisticated`/`elegant`/`deep dive`/etc.) returned no source-text matches; the only directory hits are inside this file's own Document History (which records prior fixes) and legitimate technical usage such as the `unlock` workflow step and `unlock-issue.cjs` script name in `layout.md` (lines 134, 523). Re-scanned the `specs/` directory (10 files) and found it clean of strong-marketing and vague "simply/easy-to-use" language; the only intensifier matches remain the deliberately-retained normative and conformance-taxonomy items, all unchanged from v9.19 and reserved for a spec owner: the IS-04..IS-09 MUST clause "comprehensive input sanitization" (`security-architecture-spec-validation.md` line 85) and its paired ✅ VERIFIED status echoing that wording (line 150, drifted +1 line from v9.19's line 149 due to an edit above it); the "Production-ready security" / "Production-ready deployment" conformance-level names in the RFC-2119 taxonomies (`security-architecture-spec.md` line 144, `security-architecture-spec-summary.md` line 22, `replace-label-spec.md` line 108); and `replace-label-spec.md` line 383's "simply adds", which is normative prose meaning "merely adds", not marketing. Verified the v9.18 `security-architecture-spec.md` "Example 6: Comprehensive Sanitization"→"Combined Threat Sanitization" fix persists. The only commit touching `scratchpad/`/`specs/` since v9.19 (`79c42da`, "Add colorwriter specification tests") re-synced the full spec tree without introducing new tone violations. Corrected this file's stale header metadata, which lagged at Version 9.18 / 2026-06-20 while the Document History had already advanced to v9.19. Cache-memory at `/tmp/gh-aw/cache-memory/` was not accessible from the analysis sandbox this run; historical context was reconstructed from this Document History instead. No tone issues introduced since v9.19. Coverage: 63 scratchpad spec files + 10 specs files = 73 files (unchanged from v9.19; the `specs/forecast-compliance-fixtures/README.md` fixture is excluded as non-spec content). - v9.19 (2026-06-27): Maintenance tone scan — `scratchpad/` clean (0 tone issues; the strong-marketing scan — `powerful`/`seamless`/`effortless`/`blazing`/`cutting-edge`/etc. — and the subjective-intensifier scan — `leverage`/`comprehensive`/`extensive`/`robust`/`sophisticated`/`elegant`/`deep dive`/etc. — returned no source-text matches, the only directory hits being inside this file's own Document History, which records prior fixes). Re-scanned the `specs/` directory and found it clean of strong-marketing and vague "simply/easy-to-use" language; the only intensifier matches there are the two deliberately-retained normative items in `security-architecture-spec-validation.md` — the IS-04..IS-09 MUST clause "comprehensive input sanitization" (line 84) and its paired ✅ VERIFIED status echoing that wording (line 149) — which carry normative meaning and are reserved for a spec owner (unchanged since v9.16). Also left untouched, as before: the "Production-ready security" conformance-level name in the RFC-2119 taxonomy (`security-architecture-spec.md` line 144, `-summary.md` line 22); and `replace-label-spec.md` line 383's "simply adds", which is normative prose meaning "merely adds", not marketing. No tone issues introduced since v9.18. Coverage: 63 scratchpad spec files + 10 specs files = 73 files (one more specs `.md` than v9.18's 9, all clean; the `specs/forecast-compliance-fixtures/README.md` fixture is excluded as non-spec content).