Add depth repair effect visibility

Sources/SpecGraph/Documentation.docc/ProductWorkspacePilots.md

@@ -720,6 +720,13 @@ preview validates relation names and source/target event-storming refs before
 materialization copies only review-only, non-dependency workflow edges into the
 candidate graph preview. The loop does not introduce a score, prompt-agent
 execution, canonical spec mutation, Ontology writes, or promotion authority.
+Proposal `0209` adds the post-rerun visibility layer for this loop:
+`structural_depth_delta` records before/after structural counts, added
+event-storming refs, added workflow relation evidence, remaining shallow
+dimensions, and whether the repair effect was `improved`, `resolved`,
+`still_shallow`, `unchanged`, or `not_measured`. The delta is review-only
+evidence for downstream product surfaces, not a Metrics field, gate, score, or
+authority expansion.
 
 The next slices are Platform awareness and a `local-subscription-control` demo
 pass. Platform may use the report as an explanatory preflight signal before

docs/archive/proposal_sources/0209_depth_repair_effect_visibility.md

@@ -0,0 +1,20 @@
+# 0209 Depth Repair Effect Visibility
+
+Source draft for proposal `0209`.
+
+Structural-depth repair became actionable in proposals `0207` and `0208`, but
+downstream product surfaces still need durable evidence of what changed after a
+rerun. Add a review-only `structural_depth_delta` to rerun preview and
+materialization artifacts:
+
+- before/after candidate structure counts;
+- added event-storming entry refs;
+- added workflow relation evidence;
+- remaining shallow dimensions;
+- compact status: `resolved`, `improved`, `still_shallow`, `unchanged`, or
+  `not_measured`.
+
+The delta is visibility only. It must not change Metrics schemas, add a score,
+become a gate, mutate canonical specs or intake sources, write Ontology
+packages, accept ontology terms, execute prompt agents, create Git artifacts, or
+publish read models.

docs/product_workspace_graph_versioning_roadmap.md

@@ -1614,6 +1614,23 @@ workflow topology remains review evidence and never becomes canonical spec
 mutation, Ontology acceptance, Git authority, or YAML implementation
 dependency.
 
+## Depth Repair Effect Visibility
+
+Status: implemented producer-side in proposal `0209`; SpecSpace can layer a
+read-only "Depth impact" surface over the existing rerun materialization
+artifact.
+
+Proposal `0209` closes the visibility gap after depth-driven repair. Rerun
+preview and rerun materialization now expose
+`structural_depth_delta`: before/after structural counts, added event-storming
+entry refs, added workflow relation evidence, remaining shallow dimensions, and
+a compact status such as `improved`, `resolved`, `still_shallow`, `unchanged`,
+or `not_measured`.
+
+The delta is not a Metrics schema extension, score, gate, approval signal, or
+promotion condition. It is review-only evidence that helps product surfaces
+explain what depth repair changed and what still needs clarification.
+
 ## Real Idea Entry Request Import
 
 Status: implemented producer-side in proposal `0202`; downstream UI/Platform

docs/proposals/0209_depth_repair_effect_visibility.md

@@ -0,0 +1,108 @@
+# 0209 Depth Repair Effect Visibility
+
+## Status
+
+Draft / producer-side repair-effect visibility slice.
+
+## Summary
+
+Proposals `0205` through `0208` made structural depth observable, interpretable,
+actionable through clarification requests, and repairable through safe
+event-storming and workflow-topology hints. The remaining gap is visibility:
+after a rerun, downstream surfaces can see final `candidate_structure_depth`
+counts, but they cannot easily explain what changed because of the accepted
+depth repair answers.
+
+This slice adds a review-only `structural_depth_delta` surface to the existing
+rerun preview/materialization artifacts. It records before/after structural
+counts, added event-storming entries, added workflow relations, remaining
+shallow dimensions, and a compact effect status.
+
+## Decision
+
+`tools/idea_to_spec_rerun_preview.py` emits:
+
+```json
+{
+  "rerun_preview": {
+    "structural_depth_delta": {
+      "proposal_id": "0209",
+      "status": "improved",
+      "before": {
+        "actor_count": 0,
+        "workflow_edge_count": 0
+      },
+      "after": {
+        "actor_count": 1,
+        "workflow_edge_count": 3
+      },
+      "delta": {
+        "actor_count": 1,
+        "workflow_edge_count": 3
+      },
+      "added_event_storming_entry_refs": {
+        "actors": ["actor.household-member"]
+      },
+      "added_workflow_relation_count": 3,
+      "remaining_shallow_dimensions": ["constraint_count"],
+      "review_only": true,
+      "canonical_mutations_allowed": false,
+      "materialization_dependency": false
+    }
+  }
+}
+```
+
+`tools/idea_to_spec_rerun_materialization.py` preserves the effect in
+`materialization_preview.delta.structural_depth_delta` and recomputes graph-side
+after counts from the actual `candidate_graph_preview`.
+
+Valid statuses are:
+
+- `resolved`: previously shallow structural dimensions are now non-zero;
+- `improved`: at least one structural dimension increased, but some dimensions
+  may still be shallow;
+- `still_shallow`: no measured improvement and at least one dimension is still
+  zero;
+- `unchanged`: no measured improvement and no shallow dimensions remain;
+- `not_measured`: the rerun/materialization was not ready enough to produce a
+  trustworthy delta.
+
+`tools/idea_maturity_metrics_report.py` may reference this delta from
+producer-side readiness explainers, but it does not add a new Metrics field,
+score, status, or gate.
+
+## Authority Boundary
+
+This slice is report-only and review-only. It does not:
+
+- change Metrics schemas or validator semantics;
+- add a structural-depth score;
+- change Idea Maturity status semantics;
+- change repair, Pre-SIB, candidate approval, promotion, Git, or publication
+  gates;
+- mutate event-storming intake source artifacts;
+- mutate candidate or canonical specs;
+- write Ontology packages or lockfiles;
+- accept ontology terms;
+- execute prompt agents;
+- create Git branches, commits, or pull requests;
+- publish read models.
+
+Workflow topology remains product-review evidence. Structural depth deltas must
+not become YAML `depends_on`, implementation dependencies, or promotion
+authority.
+
+## Acceptance Criteria
+
+- Rerun preview emits `structural_depth_delta` for event-storming and workflow
+  topology repair answers.
+- Rerun materialization preserves `structural_depth_delta` in its existing
+  review-only delta and recomputes graph-side after counts from the materialized
+  candidate graph preview.
+- Failed or unready materialization reports `status: "not_measured"` instead of
+  implying depth was unchanged.
+- Idea Maturity readiness explainers can cite the structural depth delta as
+  evidence without changing Metrics counts, status, or gate semantics.
+- Downstream consumers can show what improved, what was added, and which shallow
+  dimensions remain without gaining execution or mutation authority.

tests/test_idea_maturity_metrics_report.py

@@ -646,6 +646,44 @@ def test_idea_maturity_metrics_report_interprets_shallow_structure_without_gatin
     candidate_graph["nodes"][0]["acceptance_criteria"] = []
     candidate_graph["edges"] = []
     write_json(paths["candidate_graph"], candidate_graph)
+    materialization = load_json(paths["rerun_materialization"])
+    materialization["materialization_preview"]["delta"]["structural_depth_delta"] = {
+        "proposal_id": "0209",
+        "status": "improved",
+        "before": {
+            "actor_count": 0,
+            "command_count": 0,
+            "domain_event_count": 0,
+            "policy_count": 0,
+            "constraint_count": 0,
+            "topology_edge_count": 0,
+            "workflow_edge_count": 0,
+            "requirement_count": 0,
+            "acceptance_criteria_count": 0,
+        },
+        "after": {
+            "actor_count": 0,
+            "command_count": 0,
+            "domain_event_count": 0,
+            "policy_count": 0,
+            "constraint_count": 0,
+            "topology_edge_count": 1,
+            "workflow_edge_count": 1,
+            "requirement_count": 0,
+            "acceptance_criteria_count": 0,
+        },
+        "delta": {"workflow_edge_count": 1, "topology_edge_count": 1},
+        "remaining_shallow_dimensions": [
+            "actor_count",
+            "command_count",
+            "domain_event_count",
+            "policy_count",
+            "constraint_count",
+            "requirement_count",
+            "acceptance_criteria_count",
+        ],
+    }
+    write_json(paths["rerun_materialization"], materialization)
 
     report = build_report(paths)
 
@@ -667,6 +705,18 @@ def test_idea_maturity_metrics_report_interprets_shallow_structure_without_gatin
     }
     assert all("candidate_approval" not in item["blocks"] for item in structure_explainers)
     assert all("platform_promotion" not in item["blocks"] for item in structure_explainers)
+    workflow_explainer = next(
+        item
+        for item in structure_explainers
+        if item["kind"] == "candidate_structure_workflow_topology_flat"
+    )
+    assert (
+        f"{ref(paths['rerun_materialization'])}"
+        "#materialization_preview.delta.structural_depth_delta"
+        in workflow_explainer["evidence_refs"]
+    )
+    assert workflow_explainer["evidence"]["repair_effect_status"] == "improved"
+    assert workflow_explainer["evidence"]["repair_effect_delta"] == 1
 
 
 def test_idea_maturity_metrics_report_prioritizes_blockers_before_structure(

tests/test_idea_to_spec_rerun_materialization.py

@@ -238,6 +238,51 @@ def rerun_preview_with_workflow_topology() -> dict[str, object]:
         "review_only": True,
         "materialization_dependency": False,
     }
+    preview["rerun_preview"]["structural_depth_delta"] = {
+        "proposal_id": "0209",
+        "status": "improved",
+        "before": {
+            "actor_count": 0,
+            "command_count": 0,
+            "domain_event_count": 0,
+            "policy_count": 0,
+            "constraint_count": 0,
+            "topology_edge_count": 0,
+            "workflow_edge_count": 0,
+            "requirement_count": 0,
+            "acceptance_criteria_count": 0,
+        },
+        "after": {
+            "actor_count": 0,
+            "command_count": 0,
+            "domain_event_count": 0,
+            "policy_count": 0,
+            "constraint_count": 0,
+            "topology_edge_count": 2,
+            "workflow_edge_count": 2,
+            "requirement_count": 0,
+            "acceptance_criteria_count": 0,
+        },
+        "delta": {
+            "topology_edge_count": 2,
+            "workflow_edge_count": 2,
+        },
+        "added_event_storming_entry_refs": {},
+        "added_workflow_relation_count": 0,
+        "added_workflow_relations": [],
+        "remaining_shallow_dimensions": [
+            "actor_count",
+            "command_count",
+            "domain_event_count",
+            "policy_count",
+            "constraint_count",
+            "requirement_count",
+            "acceptance_criteria_count",
+        ],
+        "review_only": True,
+        "canonical_mutations_allowed": False,
+        "materialization_dependency": False,
+    }
     preview["rerun_preview"]["ontology_gap_preview"]["resolved_ontology_gaps"] = []
     preview["rerun_preview"]["ontology_gap_preview"]["unresolved_ontology_gaps"] = []
     return preview
@@ -365,9 +410,39 @@ def test_rerun_materialization_merges_review_only_workflow_topology_edges() -> N
         "event.pantry-item-recorded",
         "event.pantry-item-reviewed",
     }
+    depth_delta = delta["structural_depth_delta"]
+    assert depth_delta["proposal_id"] == "0209"
+    assert depth_delta["status"] == "improved"
+    assert depth_delta["before"]["workflow_edge_count"] == 0
+    assert depth_delta["after"]["workflow_edge_count"] == 2
+    assert depth_delta["delta"]["workflow_edge_count"] == 2
+    assert depth_delta["added_workflow_relation_count"] == 0
+    assert report["summary"]["structural_depth_delta_status"] == "improved"
     assert report["summary"]["removed_gap_count"] == 0
 
 
+def test_rerun_materialization_treats_missing_preview_depth_delta_as_not_measured() -> None:
+    module = load_module()
+    rerun_preview = rerun_preview_with_workflow_topology()
+    del rerun_preview["rerun_preview"]["structural_depth_delta"]
+
+    report = module.build_idea_to_spec_rerun_materialization(
+        rerun_preview=rerun_preview,
+        candidate_graph=candidate_graph_for_workflow_topology(),
+    )
+
+    assert report["readiness"]["ready"] is True
+    delta = report["materialization_preview"]["delta"]
+    assert delta["added_workflow_topology_edge_count"] == 2
+    depth_delta = delta["structural_depth_delta"]
+    assert depth_delta["status"] == "not_measured"
+    assert depth_delta["delta"] == {}
+    assert depth_delta["remaining_shallow_dimensions"] == []
+    assert "actor_count" not in depth_delta["before"]
+    assert report["summary"]["structural_depth_delta_status"] == "not_measured"
+    assert report["summary"]["structural_depth_remaining_shallow_dimension_count"] == 0
+
+
 def test_rerun_materialization_preserves_node_scope_for_duplicate_candidate_gap_ids() -> None:
     module = load_module()
     candidate_graph = copy.deepcopy(candidate_graph_artifact())