From e5ea4db911a65cead6d9be7df00a61b25d82fb90 Mon Sep 17 00:00:00 2001 From: Kawa Date: Mon, 13 Apr 2026 10:02:10 +0200 Subject: [PATCH] docs(08): capture phase context --- .planning/STATE.md | 16 ++- .../08-nyquist-validation-track/08-CONTEXT.md | 104 ++++++++++++++++++ 2 files changed, 111 insertions(+), 9 deletions(-) create mode 100644 .planning/phases/08-nyquist-validation-track/08-CONTEXT.md diff --git a/.planning/STATE.md b/.planning/STATE.md index 0c2dddc..70b270c 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,17 +2,15 @@ gsd_state_version: 1.0 milestone: v1.1 milestone_name: Hardening & Validation -status: pending -last_updated: "2026-04-13T12:00:00Z" -last_activity: "2026-04-13 — v1.1 roadmap created (Phases 8–11)" +status: Pending (roadmap approved, plans not yet drafted) +stopped_at: Phase 8 context gathered +last_updated: "2026-04-13T08:02:01.226Z" +last_activity: 2026-04-13 — v1.1 roadmap created, 15/15 requirements mapped across Phases 8–11 progress: total_phases: 4 completed_phases: 0 total_plans: 0 completed_plans: 0 - percent: 0 -current_phase: 8 -current_phase_name: Nyquist Validation Track --- # Project State @@ -70,6 +68,6 @@ Full decision log in PROJECT.md Key Decisions table. Milestone v1.0 decisions ar ## Session Continuity -Last session: 2026-04-13 — v1.1 roadmap creation -Stopped at: Roadmap written, requirements traceability updated, awaiting `/gsd:plan-phase 8` -Resume file: `.planning/ROADMAP.md` +Last session: 2026-04-13T08:02:01.223Z +Stopped at: Phase 8 context gathered +Resume file: .planning/phases/08-nyquist-validation-track/08-CONTEXT.md diff --git a/.planning/phases/08-nyquist-validation-track/08-CONTEXT.md b/.planning/phases/08-nyquist-validation-track/08-CONTEXT.md new file mode 100644 index 0000000..ae5f55e --- /dev/null +++ b/.planning/phases/08-nyquist-validation-track/08-CONTEXT.md @@ -0,0 +1,104 @@ +# Phase 8: Nyquist Validation Track - Context + +**Gathered:** 2026-04-13 +**Status:** Ready for planning + + +## Phase Boundary + +Retro-fit a Nyquist-compliant validation record across all 7 v1.0 phases, aggregate pass/fail into a single milestone index, and triage any gaps into v1.1 defects or explicit deferrals. Pure audit of shipped code — no new product features, no refactors, no runtime validation (that's Phase 10). + + + + +## Implementation Decisions + +### File strategy & schema +- **Upgrade existing `{NN}-VALIDATION.md` in place** for each of the 7 v1.0 phases. Do NOT create a parallel file. +- Preserve the current execution-sampling sections (Sampling Rate, Per-Task Verification Map, Wave 0 Requirements, Manual-Only Verifications) — they are historical record. +- **Add a new top-level section `## Nyquist Record`** containing one row per phase success criterion from ROADMAP.md / milestones/v1.0-ROADMAP.md. +- Row shape: `| # | Success Criterion | Observable Check | Evidence | Status | Notes |` + - Exactly **one observable check per success criterion** (Nyquist rule — no hand-wavy "code looks right"). + - Evidence cell is a markdown link or inline reference (see Evidence types below). +- **Frontmatter:** flip `nyquist_compliant: false → true` only when every row has Status = pass or explicit-deferred; add `nyquist_audited: YYYY-MM-DD` and `nyquist_auditor: `. + +### Evidence types (what counts) +Accepted, in priority order: +1. **Test evidence** — `pytest ::` plus the file path:line where it lives. Trust a recorded-green run from commit X; do NOT require live re-run. +2. **Commit evidence** — commit SHA + file path:line for code-only checks (e.g., "UAC self-elevation guard present at install.ps1:12-20"). +3. **File-artifact evidence** — path to a generated artifact (e.g., a sample `.intunewin` byte-layout fixture). +4. **Manual-check evidence** — link to a dated note in the phase's `VERIFICATION.md` describing what was observed. Only allowed when no automated path exists. +- **Not accepted:** "code review says it works", "see comments in file", vague prose. +- Re-running tests live is NOT required. A green pytest run recorded in the commit log counts. + +### Gap triage & index rollup +- **Gaps live as rows in the index**, not in a separate DEFECTS.md file. Keeping gap tracking co-located with the pass/fail rollup is the whole point of the index. +- Each gap row gets status ∈ {`fail-fix-v1.1`, `deferred-v1.2`, `wont-do`} and a mandatory `rationale` cell. +- `fail-fix-v1.1` rows MUST link to the fixing phase (9, 10, or 11) — if no phase owns the fix, the roadmap is wrong and must be amended before Phase 8 closes. +- `deferred-v1.2` / `wont-do` rows MUST have written rationale; no empty cells. +- Index file: **`.planning/milestones/v1.0-VALIDATION-INDEX.md`** (exact path per roadmap success criterion #2). + +### Index structure +- Single flat table across all 7 phases: `| Phase | # | Criterion | Status | Evidence | Gap Link |` +- Header block above the table: audit date, auditor, overall tally (`X/Y pass, Z deferred, W fail-fix`). +- Per-phase subsections NOT used — flat table keeps the rollup scannable and greppable. +- **Sign-off:** dated checkbox line at the bottom: `- [x] Nyquist audit complete — — `. Same sign-off replicated in each phase's VALIDATION.md frontmatter. + +### Audit execution approach +- **Sequential phase-by-phase (1 → 7).** Each audit informs the next (shared patterns, shared test infra), and ImpTune is small enough that parallelism would cost more coordination than it saves. +- **One plan per v1.0 phase audited** (7 plans: 08-01 through 08-07), plus **one final plan (08-08) for the index + triage sign-off**. Total: 8 plans. +- Each audit plan: read that phase's ROADMAP criteria → map each to an observable check → locate evidence → fill the Nyquist Record → commit. +- The final 08-08 plan: aggregate all 7 phase records into `v1.0-VALIDATION-INDEX.md`, confirm gap links against Phases 9/10/11, sign off. + +### Claude's Discretion +- Exact wording / column widths in the Nyquist Record tables. +- Whether to also flip `status: draft → audited` in per-phase frontmatter (preferred but not mandatory). +- How to handle the Phase 1 "spike" row (`01-03-02`, upload to real Intune tenant) — likely flagged as `fail-fix-v1.1` linked to Phase 10 RTVAL-01, but the auditor confirms at audit time. +- Whether to cite commit SHAs as short (7-char) or full — auditor's call. +- How to phrase "observable check" sentences. + + + + +## Existing Code Insights + +### Reusable Assets +- **Existing per-phase VALIDATION.md files** at `.planning/phases/{NN}-*/NN-VALIDATION.md` — already have frontmatter, execution sampling tables, and Wave 0 requirements. The audit upgrades these in place rather than creating new files. +- **`milestones/v1.0-ROADMAP.md`** — canonical source of success criteria per phase. The audit reads this, not the current `ROADMAP.md` (which is the v1.1 view). +- **`VERIFICATION.md` files** per phase — already record per-phase verification runs; manual-only evidence links point here. +- **Test suite under `tests/`** — pytest already green at v1.0 shipped commit; provides most test evidence for automated checks. + +### Established Patterns +- **Frontmatter convention** — every phase doc uses YAML frontmatter; `nyquist_compliant: false` flag already exists in VALIDATION.md, ready to flip. +- **Per-task verification map** pattern uses `| Task ID | ... | Automated Command |` — the new Nyquist Record table mirrors this shape for consistency. +- **Evidence citation style** elsewhere in .planning uses commit SHAs and `file.py:line` references — reuse. + +### Integration Points +- **Milestone-level index**: new file at `.planning/milestones/v1.0-VALIDATION-INDEX.md` — sits alongside existing `v1.0-ROADMAP.md`, same directory. +- **Roadmap back-links** — `fail-fix-v1.1` gap rows link into Phase 9 (UX), Phase 10 (RTVAL), Phase 11 (RWR) per the v1.1 phase mapping in REQUIREMENTS.md. +- **No source code touched** — this phase writes only to `.planning/` tree. + + + + +## Specific Ideas + +- The existing `01-VALIDATION.md` Manual-Only Verifications row "Upload to real Intune tenant" is the clearest example of a gap: will flip to `fail-fix-v1.1` linking RTVAL-01 / Phase 10. +- "Nyquist-compliant" per the roadmap success criterion means: every success criterion maps to exactly one observable check with cited evidence. That's the guardrail — no auditor editorializing beyond that. +- User ran `/gsd:discuss-phase 8` and explicitly said "go ahead and do your best" — Claude has broad discretion on presentation details; lock only the decisions above. + + + + +## Deferred Ideas + +- **Live re-running of the v1.0 pytest suite at audit time** — not required for Nyquist. If a later phase wants a "green-at-audit-date" stamp, handle it in Phase 10 or later. +- **Automating index generation from per-phase files** — manual compilation is fine for 7 phases; revisit if v1.x grows past ~15 phases. +- **Converting this audit into a reusable template for future milestones** — capture as a v1.2+ chore, not in scope for v1.1. + + + +--- + +*Phase: 08-nyquist-validation-track* +*Context gathered: 2026-04-13*