feat(plans): adopt awaits: field; declare storage-foundation awaits gitsheets v1.0

.claude/CLAUDE.md

@@ -60,13 +60,17 @@ specs:                   # spec files in THIS repo that this plan implements
 upstream-specs:          # (optional) specs in OTHER repos this plan consumes
   - gitsheets:specs/behaviors/transactions.md
   - gitsheets:specs/api/errors.md
+awaits:                  # (optional) external blockers — releases, decisions, deliveries
+  - "JarvusInnovations/gitsheets@v1.0 — Repository / Sheet / openStore API"
 issues: [128, 129]       # related GitHub issues (optional)
 pr: 42                   # merged PR once done (optional)
 ---
 ```
 
 `specs:` is for specs we own — the spec-drift-auditor matches them against implementation. `upstream-specs:` is for specs owned by dependencies (e.g., gitsheets) that this plan consumes; they're informational only and the spec-drift-auditor doesn't check them. Use the `<repo>:<path>` form so it's obvious where to look.
 
+`awaits:` captures external blockers — upstream library releases, vendor deliveries, partner decisions. Each entry is a one-line free-form pointer (URL, `repo@tag`, "vendor X delivery", etc., with a trailing em-dash clause for the *why* so the entry self-explains when grep surfaces it). The three structural fields (`depends:`, `upstream-specs:`, `awaits:`) are **orthogonal axes**, not mutually exclusive categories — the same upstream relationship can carry multiple. The example above is the canonical case: gitsheets appears in `upstream-specs:` (the specs we'll implement against) *and* in `awaits:` (the v1.0 release we're waiting for). Different axes of the same upstream. `awaits:` is also independent of `status:`: a `planned` plan can carry `awaits:` from day one; a `blocked` plan should always have `awaits:` populated to say why (the scripts warn if `status: blocked` is set with neither `awaits:` nor unfinished `depends:`). Resolution is just deleting the entry when the awaited thing happens. `plans-next` never lists a plan with non-empty `awaits:` under "Ready" — it surfaces in an "Awaiting external" section. Full convention: [`agent-skills/skills/specops/references/plans-protocol.md`](https://github.com/JarvusInnovations/agent-skills/blob/main/skills/specops/references/plans-protocol.md#external-blockers).
+
 A plan's body follows the template in [plans/README.md](../plans/README.md): Scope, Implements, Approach, Validation, Risks/unknowns, Notes, Follow-ups. The Validation section is the load-bearing part — it converts "in-progress" to "done."
 
 **Plans are not specs.** They're project-management artifacts. Plans rot fast — once a plan is `done`, it's a historical record; don't keep editing it. The `spec-drift-auditor` reads `specs/`, not `plans/`.

plans/README.md

@@ -20,6 +20,7 @@ Per-plan frontmatter is the source of truth for both **status** (`status:`) and
 - To find what's in flight: `grep -l '^status: in-progress' plans/*.md`
 - To find what's done: same, with `done`
 - To trace dependencies: `grep '^depends:' plans/*.md` or read the plan whose name you care about
+- External blockers (`awaits:` field) are surfaced by `plans-next` in their own "Awaiting external" section — see [the plans protocol's External blockers section](https://github.com/JarvusInnovations/agent-skills/blob/main/skills/specops/references/plans-protocol.md#external-blockers)
 
 ## What plans are NOT
 

plans/storage-foundation.md

@@ -13,6 +13,8 @@ upstream-specs:
   - gitsheets:specs/behaviors/transactions.md
   - gitsheets:specs/behaviors/validation.md
   - gitsheets:specs/behaviors/normalization.md
+awaits:
+  - "JarvusInnovations/gitsheets@v1.0 — consumed via Repository / Sheet / openStore TypeScript API (https://github.com/JarvusInnovations/gitsheets/milestone/1)"
 issues: []
 ---