gsdd-cli 0.19.2 → 0.20.0

package/README.md

@@ -346,6 +346,7 @@ Workflows are agent skills or commands, not plain shell utilities. How you invok
 | `npx -y gsdd-cli init [--tools <platform>]` | Set up `.planning/`, generate skills/adapters |
 | `npx -y gsdd-cli update [--tools <platform>] [--templates]` | Regenerate skills/adapters and refresh the repo-local helper runtime; `--templates` refreshes `.planning/templates/` and role contracts |
 | `npx -y gsdd-cli health [--json]` | Check workspace integrity and generated-surface freshness (healthy/degraded/broken) |
+| `npx -y gsdd-cli ui-proof validate <path> [--claim <public\|publication\|tracked\|delivery\|release>]` | Validate UI proof bundle metadata without requiring browser tooling; use `--claim` only when validating that stronger proof use |
 | `npx -y gsdd-cli file-op <copy\|delete\|regex-sub>` | Run deterministic workspace-confined file copy, delete, and regex substitution |
 | `npx -y gsdd-cli find-phase [N]` | Show phase info as JSON (for agent consumption) |
 | `npx -y gsdd-cli phase-status <N> <status>` | Update a single ROADMAP phase status through the status-aware helper |

package/agents/DISTILLATION.md

@@ -54,7 +54,7 @@ Evidence map from each of the 10 canonical GSDD roles to their GSD sources, with
 - Explicit "Scope" table showing scope × trigger × focus × output location
 - Clear statement: "Same algorithm, different scope. The scope is a context input, not a different role."
 
-**Rationale:** The GSD original had two roles (project and phase researcher) that followed the identical algorithm but with a scope parameter. GSDD merged them into one canonical role taking scope as input, reducing the role count from 11 to 9 (later 10 with approach-explorer in D29) while preserving all leverage. This is the clean merger mentioned in D2.
+**Rationale:** The GSD original had two roles (project and phase researcher) that followed the identical algorithm but with a scope parameter. GSDD merged them into one canonical role taking scope as input, reducing duplicate role contracts while preserving the current 10-role catalog. This is the clean merger mentioned in D2.
 
 ---
 
@@ -362,11 +362,23 @@ Cross-source best practices applied to GSDD role contracts, audited against 6 ex
 
 | Principle | What It Means | Source | GSDD Implementation |
 |-----------|--------------|--------|---------------------|
-| **Context isolation** | Research and heavy reads go in subagents; only compressed summaries enter the main context | Anthropic "Building effective agents" (Dec 2024): orchestrator-worker pattern — sub-agents do deep technical work and return condensed summaries | Approach explorer research subagents return ~1000-token summaries; plan-checker runs in fresh context |
+| **Context isolation** | Research and heavy reads go in subagents; only compressed summaries enter the main context | Anthropic "Building effective agents" (Dec 2024): orchestrator-worker pattern — sub-agents do deep technical work and return condensed summaries | Approach explorer research subagents return 500-800 token agent-mediated summaries; plan-checker runs in fresh context |
 | **JIT context loading** | Never say "read everything." Specify what to extract from each file | LangChain "Context Engineering for Agents" (2025): Select step of Write/Select/Compress/Isolate — load only the specific content needed, not full files | `<input_contract>` with extraction guidance: "From SPEC.md read ONLY locked decisions" |
 | **Intermediate persistence** | For long interactions, write confirmed state to disk incrementally | Anthropic BEA: agent memory outside context window. LangChain CE: Write pattern — confirmed state persisted to disk | Approach explorer writes decisions to disk as they're confirmed during conversation |
 | **Progressive disclosure** | Don't front-load all context; let agents discover incrementally | LangChain CE: Compress/Isolate patterns — agents assemble understanding incrementally rather than loading everything upfront | Gray areas presented individually; research loaded per area on demand |
 
+### Subagent Return Tiers
+
+Use the smallest return that preserves the downstream decision. Full documents stay on disk unless a role explicitly owns a durable artifact update.
+
+| Tier | Use When | Return Size |
+|------|----------|-------------|
+| Routing summary | The orchestrator only needs a signal, category, or next-step recommendation | 100-200 tokens |
+| Human-read summary | The user will read the summary directly to understand options or findings | 300-500 tokens |
+| Agent-mediated discussion | The orchestrator must discuss findings with the user and answer follow-up questions without re-querying the subagent | 500-800 tokens |
+
+This replaces the prior mixed guidance around sentence-count summaries, single-tier token budgets, and larger undifferentiated summaries. The deliberate boundary is conservative: subagents are useful for read-heavy or artifact-backed isolation, not for hidden implementation orchestration or overlapping writes without explicit write-set ownership.
+
 ### Prompt Structure (medium leverage)
 
 | Principle | What It Means | Source | GSDD Implementation |
@@ -381,7 +393,7 @@ Cross-source best practices applied to GSDD role contracts, audited against 6 ex
 
 | Principle | What It Means | Source | GSDD Implementation |
 |-----------|--------------|--------|---------------------|
-| **Authority language: intentional leverage** | Anthropic Claude warns "CRITICAL:" can overtrigger on newer models. GSDD decision: **keep CRITICAL: for mandatory initial-read** — a genuine compliance-critical instruction where skipping causes cascading failures. Emphasis markers work when rare and specific (signal-to-noise principle: one CRITICAL: in a role contract is a load-bearing gate; ten would be noise). Use normal language for algorithm steps, scope guidance, and quality rules. | Anthropic Claude prompting docs (overtriggering caution) + technical writing signal-to-noise principle. GSDD applies the caution selectively: only compliance-critical context gates use CRITICAL: | `CRITICAL: Mandatory initial read` kept in all 7 roles. `NEVER` kept for security (mapper secret protection). Normal language used for algorithm steps, scope guidance, and quality rules |
+| **Authority language: intentional leverage** | Anthropic Claude warns "CRITICAL:" can overtrigger on newer models. GSDD decision: keep `CRITICAL:` only for compliance-critical context gates where skipping causes cascading failures. Emphasis markers work when rare and specific (signal-to-noise principle: one CRITICAL: in a role contract is a load-bearing gate; ten would be noise). Use normal language for algorithm steps, scope guidance, and quality rules. | Anthropic Claude prompting docs (overtriggering caution) + technical writing signal-to-noise principle. GSDD applies the caution selectively: only compliance-critical context gates use CRITICAL: | Most roles keep `CRITICAL: Mandatory initial read`; executor now uses `CRITICAL: Tiered context intake` so mandatory-now, task-scoped, reference-only, and conditional reads replace blanket preload. `NEVER` kept for security (mapper secret protection). Normal language used for algorithm steps, scope guidance, and quality rules |
 | **Tell what to do, not just what not to do** | Anti-patterns alone are insufficient; pair with positive instructions | Anthropic Claude: "Tell Claude what to do instead of what not to do" | Every role has both `<anti_patterns>` AND positive algorithm/process sections |
 | **Context for instructions** | Explain WHY a rule exists so the agent can generalize | Anthropic Claude: "Providing context or motivation behind your instructions helps Claude better understand your goals" | Research quality rules explain WHY: "Training data is a hypothesis. Verify before asserting." |
 
@@ -417,5 +429,5 @@ When sources conflict, these resolutions apply:
 |----------|------------|-----|
 | Authority language ("YOU MUST" vs. normal) | Keep CRITICAL: for mandatory initial-read (compliance-critical). Use normal language elsewhere | Emphasis markers work when rare and specific (signal-to-noise). Anthropic's overtriggering concern applies to general guidance; a single CRITICAL: for a mandatory context gate is a load-bearing instruction, not noise |
 | Example count (2 vs. 3-5) | Target 3+ for conversational agents; inline format examples are sufficient for structured output agents | Anthropic's 3-5 recommendation is general; interactive roles benefit more than output-only roles |
-| Subagent return size (200 vs. 1000-2000 tokens) | Use 300-500 tokens | Anthropic's 1000-2000 is upper bound; 200 was too tight for structured approach summaries with trade-offs |
+| Subagent return size (200 vs. 1000-2000 tokens) | Use the three-tier return model: 100-200 for routing, 300-500 for human-read summaries, and 500-800 for agent-mediated discussion | Anthropic's 1000-2000 is an upper bound; 200 is too tight for structured approach summaries with trade-offs, while returning full raw research defeats context isolation |
 | "Don't invent alternatives" vs. "try fallback strategies" | Keep "don't invent" for approach research; use fallbacks for information retrieval | These solve different problems: manufacturing fake options is worse than acknowledging one viable path |

package/agents/README.md

@@ -11,8 +11,20 @@ Vendor-agnostic role contracts for Workspine's agent architecture.
 
 Roles define what an agent is. Delegates define what an agent does in a specific workflow context.
 
+## Deliberate Subagent Boundary
+
+Workspine uses subagents when isolation earns its cost: research, review, mapping, synthesis, and integration checks may run as read-only or artifact-backed delegation, with summaries returned to the orchestrator and full detail written to disk when detail is needed later.
+
+Subagents must not become hidden implementation orchestration. Implementation remains plan-scoped and write-set constrained; overlapping implementation writes require explicit write-set ownership in the approved plan before any parallelism is safe.
+
+Roadmapper is intentionally role-only/direct invocation in the current catalog. There is no roadmapper delegate because roadmap creation is sequential, coverage-sensitive, and writes `.planning/ROADMAP.md`; a future delegate would need a proven thin-wrapper use case before it is added.
+
+Leverage record: lost flexibility to add delegates by symmetry; kept the two-layer role/delegate architecture and summaries-up/documents-to-disk model; gained a conservative boundary that prevents subagents from implying agent teams, parallel PR orchestration, or runtime parity claims.
+
 ## Lifecycle Roles
 
+The catalog contains 10 canonical roles across lifecycle, audit, and utility responsibilities.
+
 | Role | File | Absorbs From (GSD) |
 |------|------|---------------------|
 | Mapper | `mapper.md` | `gsd-codebase-mapper.md` |

package/agents/approach-explorer.md

@@ -90,7 +90,7 @@ Generate 3-4 **phase-specific** gray areas. Not generic categories — concrete
 
 ## Step 3: Research Approaches (Technical and Hybrid Only)
 
-For each technical or hybrid gray area, research 2-3 viable approaches.
+For each technical or hybrid gray area, use a read-only research subagent when isolation earns its cost, then research 2-3 viable approaches.
 
 **Source hierarchy:**
 1. Existing codebase — what patterns are already established?
@@ -311,7 +311,7 @@ Ready for assumptions?"
 
 <research_subagent_prompt>
 
-When the orchestrator spawns a read-only research subagent for a technical or hybrid gray area, use this prompt template. Substitute the bracketed values. One subagent is spawned per gray area.
+When the orchestrator spawns a read-only research subagent for a technical or hybrid gray area, use this prompt template. Substitute the bracketed values. One subagent is spawned per gray area and returns an agent-mediated discussion summary, not raw notes.
 
 ```
 You are a research subagent for approach exploration. Your job: investigate viable approaches for ONE gray area and return a compressed structured summary. You do NOT interact with the user — read, search, and return findings only.
@@ -341,9 +341,9 @@ Training data is a hypothesis. Verify before asserting. Do NOT recommend a libra
 - Do NOT recommend deprecated or unmaintained libraries
 - Do NOT present "roll your own" as an approach unless existing libraries genuinely fail to solve the problem
 - Do NOT include approaches you cannot source
-- Do NOT exceed 1000 tokens in your response
+- Do NOT exceed 800 tokens in your response
 
-## Output Format (under 1000 tokens)
+## Output Format (500-800 tokens)
 
 For each of 2-3 viable approaches:
 - **Name**

package/agents/executor.md

@@ -209,6 +209,9 @@ Before reporting a task complete:
 - if a UI change is involved, verify the relevant rendering path
 - if an API change is involved, hit the endpoint or targeted integration path
 - A task is not complete because code was written. It is complete when the intended verification path actually passes.
+
+### UI Proof Execution
+If the plan defines UI proof slots, record observed proof against the exact claim, route/state, observation, evidence kind, artifact path or manual step, privacy metadata, result, and claim limit before claiming task completion. Artifact metadata must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; raw screenshots, traces, videos, DOM snapshots, and reports are local-only/unsafe by default and cannot back public, tracked, delivery, release, or publication proof claims. Use `gsdd ui-proof validate <path>` or `gsdd health` when a bundle exists. Artifact count, source comments, AST/cAST findings, semantic search, and Semble-like retrieval are not proof. Missing or weakly linked evidence must be recorded as proof debt, waiver, deferment, or reduced claim language rather than satisfied proof.
 </execution_loop>
 
 <checkpoint_protocol>

package/agents/integration-checker.md

@@ -5,7 +5,7 @@
 <role>
 You are an integration checker. You verify that phases work together as a system, not just individually.
 
-Your job: check cross-phase wiring, API coverage, auth protection, and end-to-end user flows. Return a structured report to the milestone auditor.
+Your job: check cross-phase wiring, API coverage, auth protection, and end-to-end user flows. This is read-only verification: inspect artifacts and code, return a structured report to the milestone auditor, and do not write implementation changes.
 
 CRITICAL: Mandatory initial read
 
@@ -283,7 +283,7 @@ The integration checker is milestone-scoped:
 - maps each milestone requirement to its integration path
 - does NOT verify single-phase goal completion; that is the verifier's job
 - does NOT run the application or execute tests; this is static analysis
-- does NOT write output to disk; it returns a structured report to the milestone auditor
+- does NOT write output to disk or mutate source files; it is a read-only subagent-style check that returns a structured report to the milestone auditor
   </scope_boundary>
 
 <anti_patterns>

package/agents/mapper.md

@@ -19,7 +19,7 @@ Accountable for producing accurate, file-path-rich analysis of an existing codeb
   - `arch` -> ARCHITECTURE.md
   - `quality` -> CONVENTIONS.md
   - `concerns` -> CONCERNS.md
-- **Return:** Brief confirmation (document names + line counts). NOT document contents -- the point is reducing context transfer to the orchestrator.
+- **Return:** Routing summary only (100-200 tokens: document names, line counts, and the highest-signal flags). NOT document contents -- the point is reducing context transfer to the orchestrator while the full artifacts stay on disk.
 
 ## Downstream Consumers
 
@@ -39,7 +39,7 @@ This means: file paths are critical (planner needs to navigate directly), patter
 2. **Explore the codebase** thoroughly for the assigned focus area. Use file listing, content search, and targeted file reads. Read actual code -- do not guess.
 3. **Fill the document template** with findings. Replace all placeholders with real data. Use "Not detected" for genuinely absent items.
 4. **Write document(s)** to the designated output directory.
-5. **Return confirmation only** -- document names and line counts. Do not echo contents back.
+5. **Return summary only** -- document names, line counts, and highest-signal flags. Do not echo contents back.
 
 ## Focus Area Guidance
 

package/agents/planner.md

@@ -10,6 +10,7 @@ Your job:
 - decompose the phase into dependency-aware plans and waves
 - derive must-haves from the phase goal
 - return structured planning output instead of prose-only recommendations
+- use research or checker subagents only for read-only or fresh-context review; do not plan hidden implementation orchestration
 
 CRITICAL: Mandatory initial read — if the prompt contains a `<files_to_read>` block, read every file listed there before doing any other work. That is your primary context.
 </role>
@@ -152,6 +153,14 @@ Any checkpoint must be justified by the task itself, not by planner caution or h
 Any plan containing `checkpoint:*` must set `autonomous: false`.
 </task_contract>
 
+<ui_proof_planning>
+For UI-sensitive work, plan proof slots that can later be matched exactly to claim, route/state, observation, evidence kind, artifact path or manual step, privacy metadata, result, and claim limit. Use only the stable evidence kinds `code`, `test`, `runtime`, `delivery`, and `human`.
+
+Require observed artifacts to carry `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; when a planned slot is meant to support public, publication, tracked, delivery, or release proof, say to validate the observed bundle with `gsdd ui-proof validate <path> --claim <...>`. `gsdd ui-proof validate`/`gsdd health` must catch invalid bundle metadata when present.
+
+Do not let source annotations, AST/cAST findings, semantic search, comments, or Semble-like retrieval satisfy proof slots; they are discovery hints only. Human acceptance can narrow or waive a claim and record proof debt, but it must not turn missing or mismatched non-human evidence into `satisfied` proof.
+</ui_proof_planning>
+
 <dependency_graph_example>
 Example dependency graph:
 
@@ -176,13 +185,14 @@ Wave 3: C
 Wave rule:
 - if a task's verify step depends on a test file or artifact, an earlier wave must create it
 - if two tasks touch the same critical file or one task's output is another task's input, they are not parallel
+- parallel implementation is allowed only when the approved plan names explicit, disjoint write-set ownership
 </dependency_graph_example>
 
 <output>
 Write one or more `PLAN.md` files to the phase directory.
 
 Keep the current GSDD schema exactly:
-- frontmatter keys: `phase`, `plan`, `type`, `wave`, `runtime`, `assurance`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `non_goals`, `hard_boundaries`, `escalation_triggers`, `approval_gates`, `anti_regression_targets`, `known_unknowns`, `high_leverage_surfaces`, `second_pass_required`, `closure_claim_limit`, `parallelism_budget`, `leverage`, `must_haves`
+- frontmatter keys: `phase`, `plan`, `type`, `wave`, `runtime`, `assurance`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `non_goals`, `hard_boundaries`, `escalation_triggers`, `approval_gates`, `anti_regression_targets`, `known_unknowns`, `ui_proof_slots`, `no_ui_proof_rationale`, `high_leverage_surfaces`, `second_pass_required`, `closure_claim_limit`, `parallelism_budget`, `leverage`, `must_haves`
 - typed tasks with `files`, `action`, `verify`, and `done`
 
 Typed frontmatter example:
@@ -213,6 +223,8 @@ anti_regression_targets:
   - Existing session middleware behavior remains unchanged for already-supported routes.
 known_unknowns:
   - Exact copy wording for auth errors may still need product confirmation.
+ui_proof_slots: []
+no_ui_proof_rationale: Not UI-sensitive; scoped work does not claim a visible UI outcome.
 high_leverage_surfaces: []
 second_pass_required: false
 closure_claim_limit: Do not claim phase completion until verification satisfies the evidence contract for the scoped truths.

package/agents/researcher.md

@@ -26,7 +26,7 @@ Same algorithm, different scope. The scope is a context input, not a different r
 
 - **Artifacts (project scope):** STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md (+ COMPARISON.md or FEASIBILITY.md if applicable mode)
 - **Artifacts (phase scope):** Single RESEARCH.md with sections: Standard Stack, Architecture Patterns, Don't Hand-Roll, Common Pitfalls, Code Examples
-- **Return:** Structured summary with key findings, confidence assessment, and open questions
+- **Return:** Human-read structured summary (300-500 tokens) with key findings, confidence assessment, and open questions. Do not return raw research; full detail belongs in the written artifact.
 
 ## Core Algorithm
 
@@ -43,7 +43,7 @@ Same algorithm, different scope. The scope is a context input, not a different r
    - Single unverified source -> LOW confidence, flag for validation
 5. **Run quality checklist:** All domains investigated? Negative claims verified with official docs? Multiple sources for critical claims? Confidence levels assigned honestly?
 6. **Write output files** to the designated directory.
-7. **Return structured result** to orchestrator. Do not commit -- orchestrator handles git.
+7. **Return structured summary** to orchestrator. Do not return raw research and do not commit -- orchestrator handles git.
 
 ## Quality Guarantees
 

package/agents/roadmapper.md

@@ -5,6 +5,8 @@
 <role>
 You are a roadmapper. You turn requirements into a phased delivery plan that downstream planners can execute without guessing.
 
+Roadmapper is role-only/direct invocation in the current Workspine contract, not a delegate. Roadmap creation is sequential, coverage-sensitive, and owns `.planning/ROADMAP.md`; do not route it through a hidden subagent wrapper unless a future plan explicitly adds that delegate.
+
 Your job:
 - derive phases from requirements instead of imposing a template
 - map every in-scope requirement to exactly one phase
@@ -292,5 +294,5 @@ If a section does not improve requirement coverage, dependency order, or observa
 ## Vendor Hints
 
 - **Tools required:** file read, file write, content search
-- **Parallelizable:** No - roadmapping is sequential and coverage-sensitive
+- **Parallelizable:** No - roadmapping is sequential, coverage-sensitive, and writes `.planning/ROADMAP.md` directly
 - **Context budget:** Moderate - the reasoning work is heavier than the I/O

package/agents/synthesizer.md

@@ -9,7 +9,7 @@ Your job:
 - read the full research outputs
 - extract the most decision-relevant findings
 - cross-reference them into roadmap implications
-- return a structured handoff the roadmapper can use directly
+- return an agent-mediated structured summary the roadmapper can use directly
 
 CRITICAL: Mandatory initial read
 
@@ -75,7 +75,7 @@ Assign confidence by area based on source quality and identify any unresolved ga
 
 ## Step 6: Write the summary and return a structured handoff
 
-Write `.planning/research/SUMMARY.md`. Return a short structured summary to the orchestrator.
+Write `.planning/research/SUMMARY.md`. Return a 500-800 token structured summary to the orchestrator so downstream discussion can preserve recommendation reasoning without returning the full document.
 </execution_flow>
 
 <cross_reference_dimensions>

package/agents/verifier.md

@@ -123,6 +123,8 @@ Do not return a flat symptom list when the same underlying breakage explains mul
 
 Visual correctness, live interaction quality, and some external integrations still need explicit human checks.
 
+For UI proof slots, fail closed unless observed proof is matched to the exact claim, route/state, observation, evidence kind, artifact path or manual step, privacy metadata, result, and claim limit. Artifact metadata must include `visibility`, `retention`, `sensitivity`, and `safe_to_publish`; local-only or unsafe artifacts cannot back public, tracked, delivery, release, or publication proof claims, and `gsdd ui-proof validate`/`gsdd health` metadata failures block the stronger proof claim. Screenshots, traces, reports, Gherkin, a11y scans, E2E outputs, manual notes, source annotations, AST/cAST findings, semantic search, comments, and Semble-like retrieval do not satisfy proof by existence alone. Human acceptance records risk, waiver, deferment, proof debt, or a narrowed claim; it does not upgrade missing or mismatched non-human proof to `satisfied`.
+
 ## Step 9: Determine overall status
 
 - `passed` when all programmatic checks pass and no human-only checks remain

package/bin/gsdd.mjs

@@ -19,6 +19,7 @@ import { cmdFileOp } from './lib/file-ops.mjs';
 import { createCmdHealth } from './lib/health.mjs';
 import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
 import { cmdSessionFingerprint } from './lib/session-fingerprint.mjs';
+import { cmdUiProof } from './lib/ui-proof.mjs';
 import { resolveWorkspaceContext } from './lib/workspace-root.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -107,6 +108,7 @@ const COMMANDS = {
   'file-op': cmdFileOp,
   'lifecycle-preflight': cmdLifecyclePreflight,
   'session-fingerprint': cmdSessionFingerprint,
+  'ui-proof': cmdUiProof,
   'find-phase': cmdFindPhase,
   'phase-status': cmdPhaseStatus,
   verify: cmdVerify,
@@ -132,8 +134,5 @@ async function runCli(cliCommand = command, ...cliArgs) {
   await COMMANDS[cliCommand](...normalizedArgs);
 }
 
-if (IS_MAIN) {
-  await runCli();
-}
-
-export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdLifecyclePreflight, cmdSessionFingerprint, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };
+if (IS_MAIN) await runCli();
+export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdLifecyclePreflight, cmdSessionFingerprint, cmdUiProof, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };

package/bin/lib/health.mjs

@@ -4,12 +4,13 @@
 // evaluate once, so CWD must be computed inside function bodies.
 
 import { existsSync, readFileSync, readdirSync } from 'fs';
-import { join } from 'path';
+import { join, relative } from 'path';
 import { readManifest, detectModifications } from './manifest.mjs';
 import { output } from './cli-utils.mjs';
 import { runTruthChecks, TRUTH_CHECK_IDS } from './health-truth.mjs';
 import { evaluateLifecycleState } from './lifecycle-state.mjs';
 import { evaluateRuntimeFreshness } from './runtime-freshness.mjs';
+import { findUiProofBundleFiles, readUiProofBundleFile, validateUiProofBundle } from './ui-proof.mjs';
 import { resolveWorkspaceContext } from './workspace-root.mjs';
 
 /**
@@ -31,7 +32,7 @@ export function createCmdHealth(ctx) {
     }
     const cwd = workspaceRoot;
     const frameworkSourceMode = isFrameworkSourceRepo(cwd);
-    const healthCheckIds = ['E1', 'E2', 'E3', 'E4', 'E5', 'E6', 'E7', 'E8', 'E9', 'W1', 'W2', 'W3', 'W4', 'W5', 'W6', ...TRUTH_CHECK_IDS, 'I1', 'I2', 'I3'];
+    const healthCheckIds = ['E1', 'E2', 'E3', 'E4', 'E5', 'E6', 'E7', 'E8', 'E9', 'E10', 'W1', 'W2', 'W3', 'W4', 'W5', 'W6', ...TRUTH_CHECK_IDS, 'I1', 'I2', 'I3'];
 
     // Pre-init guard
     if (!existsSync(join(planningDir, 'config.json'))) {
@@ -123,7 +124,7 @@ export function createCmdHealth(ctx) {
       }
 
       // E8: critical root template files missing
-      const requiredRootFiles = ['spec.md', 'roadmap.md', 'auth-matrix.md'];
+      const requiredRootFiles = ['spec.md', 'roadmap.md', 'auth-matrix.md', 'ui-proof.md'];
       const missingRoot = requiredRootFiles.filter((f) => !existsSync(join(templatesDir, f)));
       if (missingRoot.length > 0) {
         errors.push({ id: 'E8', severity: 'ERROR', message: `.planning/templates/ missing critical root files: ${missingRoot.join(', ')}`, fix: 'Run `npx -y gsdd-cli update --templates`' });
@@ -140,6 +141,23 @@ export function createCmdHealth(ctx) {
       }
     }
 
+    // E10: known UI proof bundles must satisfy deterministic metadata/privacy validation.
+    for (const bundlePath of findUiProofBundleFiles(planningDir)) {
+      const relativePath = relative(cwd, bundlePath).replace(/\\/g, '/');
+      const parsed = readUiProofBundleFile(bundlePath);
+      const validation = parsed.errors.length > 0
+        ? { valid: false, errors: parsed.errors }
+        : validateUiProofBundle(parsed.bundle);
+      if (!validation.valid) {
+        errors.push({
+          id: 'E10',
+          severity: 'ERROR',
+          message: `${relativePath} has invalid UI proof metadata (${validation.errors.map((entry) => entry.code).join(', ')})`,
+          fix: 'Run `gsdd ui-proof validate <path>` and add required privacy metadata, claim limits, fixed evidence kinds, observation artifact references, and safe-to-publish handling.',
+        });
+      }
+    }
+
     // --- WARNING checks ---
 
     // W1: generation-manifest.json missing

package/bin/lib/init-runtime.mjs

@@ -187,6 +187,8 @@ Commands:
   lifecycle-preflight <surface> [phase]
                               Inspect deterministic lifecycle gate results for a workflow surface
   session-fingerprint write    Rebaseline planning-state drift after reviewing changed planning files
+  ui-proof validate <path> [--claim <public|publication|tracked|delivery|release>]
+                              Validate UI proof metadata; use --claim for stronger proof uses
   help                        Show this summary
 
 Platforms (for --tools):
@@ -257,6 +259,7 @@ Advanced/internal helpers (kept available, but not the primary first-run user st
   lifecycle-preflight       Inspect deterministic lifecycle gate results for a workflow surface
   session-fingerprint       Rebaseline the local planning-state fingerprint after review
   phase-status              Update ROADMAP.md phase status through the local helper surface
+  ui-proof                  Validate UI proof metadata; use --claim for stronger proof uses
   file-op                   Deterministic workspace-confined file copy/delete/text mutation
 `;
 }

package/bin/lib/lifecycle-state.mjs

@@ -6,7 +6,7 @@ const BROWNFIELD_CHANGE_DIR = 'brownfield-change';
 const PHASE_LINE_RE = /^\s*[-*]\s*\[([ x-])\]\s*\*\*Phase\s+(\d+(?:\.\d+)*[a-z]?):\s*(.+?)\*\*(?:\s+—\s+\[([^\]]+)])?/i;
 const PHASE_DETAIL_HEADING_RE = /^(#{3,})\s+Phase\s+(\d+(?:\.\d+)*[a-z]?)(?::|\b)/i;
 const PHASE_DETAIL_STATUS_RE = /^\s*\*\*Status\*\*:\s*\[([ x-])\]/i;
-const ACTIVE_MILESTONE_HEADING_RE = /^###\s+(v[^\s]+)\s+(.+)$/im;
+const ACTIVE_MILESTONE_HEADING_RE = /^#{2,3}\s+(v[^\s]+)\s+(.+)$/im;
 const MILESTONE_LEDGER_HEADING_RE = /^##\s+(?:✅\s+)?(v[^\s]+)\s*(?:—|-)?\s*(.*)$/i;
 const DETAILS_OPEN_RE = /<details\b/i;
 const DETAILS_CLOSE_RE = /<\/details>/i;
@@ -274,7 +274,7 @@ export function readBrownfieldChangeState(planningDir) {
     handoffPath,
     title: extractMarkdownHeading(changeArtifact.body),
     changeId: changeArtifact.frontmatter.change || null,
-    currentStatus: changeArtifact.frontmatter.status || extractBulletLabel(currentStatusSection, 'Current posture'),
+    currentStatus: extractBulletLabel(currentStatusSection, 'Current posture') || changeArtifact.frontmatter.status || null,
     currentIntegrationSurface: extractBulletLabel(currentStatusSection, 'Current branch / integration surface'),
     currentOwnerRuntime: extractBulletLabel(currentStatusSection, 'Current owner / runtime'),
     nextAction: collapseMarkdownSection(nextActionSection),

package/bin/lib/rendering.mjs

@@ -13,6 +13,7 @@ const HELPER_LIB_FILES = Object.freeze([
   'lifecycle-state.mjs',
   'phase.mjs',
   'session-fingerprint.mjs',
+  'ui-proof.mjs',
   'workspace-root.mjs',
 ]);
 
@@ -47,6 +48,7 @@ import { cmdFileOp } from './lib/file-ops.mjs';
 import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
 import { cmdPhaseStatus } from './lib/phase.mjs';
 import { cmdSessionFingerprint } from './lib/session-fingerprint.mjs';
+import { cmdUiProof } from './lib/ui-proof.mjs';
 import { bootstrapHelperWorkspace, consumeWorkspaceRootArg, resolveWorkspaceContext } from './lib/workspace-root.mjs';
 
 const COMMANDS = {
@@ -54,6 +56,7 @@ const COMMANDS = {
   'lifecycle-preflight': cmdLifecyclePreflight,
   'phase-status': cmdPhaseStatus,
   'session-fingerprint': cmdSessionFingerprint,
+  'ui-proof': cmdUiProof,
 };
 
 function printHelp() {
@@ -71,6 +74,8 @@ function printHelp() {
     '                               Example: node .planning/bin/gsdd.mjs lifecycle-preflight verify 1 --expects-mutation phase-status',
     '  session-fingerprint write',
     '                               Rebaseline planning-state drift after reviewing changed planning files',
+    '  ui-proof validate <path> [--claim <public|publication|tracked|delivery|release>]',
+    '                               Validate UI proof metadata; use --claim for stronger proof uses',
     '',
     'Advanced option:',
     '  --workspace-root <path>     Override workspace root discovery before or after the subcommand',

package/bin/lib/templates.mjs

@@ -23,7 +23,7 @@ export function installProjectTemplates({ planningDir, distilledDir, agentsDir }
           console.log(`  - WARN: missing expected template subdir: ${subdir}/`);
         }
       }
-      const expectedRootFiles = ['spec.md', 'roadmap.md', 'auth-matrix.md'];
+      const expectedRootFiles = ['spec.md', 'roadmap.md', 'auth-matrix.md', 'ui-proof.md'];
       for (const file of expectedRootFiles) {
         if (!existsSync(join(localTemplatesDir, file))) {
           console.log(`  - WARN: missing expected root template file: ${file}`);