kawa/ImpTune
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
1bec899f871cf2707d23cf71436dba87ceca5147
ImpTune/.planning/phases/08-nyquist-validation-track/08-CONTEXT.md
T

7.8 KiB
Raw Blame History

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: <name>.

Evidence types (what counts)

Accepted, in priority order:

  1. Test evidence — pytest <path>::<testname> 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 — <date> — <auditor>. 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.

<code_context>

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.

</code_context>

## 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

Pre-surfaced Nyquist gaps (feed into the audit, fixed elsewhere)

  • POST /drivers/upload returns HTTP 500 (reported 2026-04-13 during Phase 8 kickoff). Blocks UX-01 by definition — you cannot refresh the DriverDesc dropdown if the upload itself fails. The auditor MUST record this as a fail-fix-v1.1 row in v1.0-VALIDATION-INDEX.md under Phase 2 (Driver Management, DRV-01..05) linking to Phase 9 / UX-01 as the fixing phase. Root cause is unknown at audit-kickoff time; reproduction: attempt driver ZIP upload, check server console for the 500. Do NOT fix in Phase 8 (pure audit); the fix lands in Phase 9's UX-01 plan.

Out of scope entirely

  • 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

Reference in New Issue View Git Blame Copy Permalink