Add deterministic workflow visualization export

README.md

@@ -50,15 +50,40 @@ python -m agentic_sdlc validate fixtures/valid_workflow
 python -m agentic_sdlc validate fixtures/privacy_violation
 python -m agentic_sdlc status fixtures/ownership_conflict
 python -m agentic_sdlc review-plan fixtures/missing_review_evidence
+python -m agentic_sdlc visualize fixtures/valid_workflow
+python -m agentic_sdlc visualize fixtures/valid_workflow --format svg --output workflow.svg
 ```
 
 Machine-readable output:
 
 ```powershell
 $env:PYTHONPATH = "src"
 python -m agentic_sdlc validate fixtures/stale_resume --json
+python -m agentic_sdlc visualize fixtures/missing_review_evidence --json
 ```
 
+## Workflow Visualization
+
+`visualize` turns the same validated JSONL records into a deterministic workflow
+graph. The default output is Mermaid, so the result can be pasted into Markdown
+or rendered by tools that support Mermaid diagrams.
+
+```powershell
+$env:PYTHONPATH = "src"
+python -m agentic_sdlc visualize fixtures/valid_workflow
+python -m agentic_sdlc visualize fixtures/valid_workflow --format svg --output workflow.svg
+python -m agentic_sdlc visualize fixtures/missing_review_evidence --json
+```
+
+The graph is not a runtime trace. It is a read-only view of the workflow state:
+tasks, handoffs, events, resume packets, review gates, evidence, ownership, and
+validation findings. Invalid workspaces still render, but the command exits with
+`1` and labels failing records with stable `ASDLC###` rule IDs.
+
+SVG output is the minimal visual view: tasks are boxes, events are circles,
+review gates are diamonds, evidence artifacts are ellipses, and failures use red
+outlines with compact rule labels.
+
 Run tests:
 
 ```powershell
@@ -99,4 +124,5 @@ Adapters can come later. First the workflow records need to be trustworthy.
 
 - [V1 spec](docs/v1-spec.md)
 - [Rule catalog](docs/rule-catalog.md)
+- [Visualization](docs/visualization.md)
 - [JSON Schemas](schemas/README.md)

docs/v1-spec.md

@@ -51,6 +51,7 @@ Published schema files live in `schemas/`.
 agentic-sdlc validate <workspace> [--json]
 agentic-sdlc status <workspace> [--json]
 agentic-sdlc review-plan <workspace> [--json]
+agentic-sdlc visualize <workspace> [--json] [--format mermaid|json|svg] [--output PATH]
 ```
 
 All commands are offline and read-only.
@@ -79,6 +80,8 @@ V1 is acceptable when:
 - `validate` fails every invalid fixture with stable rule IDs.
 - `status` summarizes task counts, review gates, handoff readiness, stale resumes, and ownership conflicts.
 - `review-plan` explains what evidence is missing for review gates.
+- `visualize` renders the workflow as deterministic JSON, Mermaid, or SVG,
+  including validation state and stable `ASDLC###` findings.
 - output is available as human text and JSON.
 - test coverage includes positive and negative fixtures for every advertised invariant.
 - no command runs agents, writes to GitHub, starts watchers, promotes memory, or scans broad folders.
@@ -90,6 +93,7 @@ V1 is acceptable when:
 - MCP integration
 - scheduled watchers
 - dashboard UI
+- live runtime progress visualization
 - vector memory
 - automatic durable memory promotion
 - cross-device bus automation

docs/visualization.md

@@ -0,0 +1,77 @@
+# Visualization
+
+`agentic-sdlc visualize` is a read-only projection of workflow records into a
+graph. It does not run agents or infer hidden state. It renders what the bounded
+workflow directory already proves.
+
+## Command
+
+```text
+agentic-sdlc visualize <workspace> [--json] [--format mermaid|json|svg] [--output PATH]
+```
+
+Defaults:
+
+- view: `readiness`
+- format: `mermaid`
+- output: stdout
+
+Exit codes match `validate`:
+
+- `0`: no error findings
+- `1`: validation error findings or unreadable input
+
+Invalid workspaces still render so the graph can show where the workflow is
+blocked.
+
+## Readiness View
+
+The readiness graph shows the evidence chain that determines whether work can
+continue:
+
+- task dependencies
+- handoffs into tasks
+- task events
+- return/resume packets
+- review gates
+- evidence artifacts and events
+- ownership claims
+- privacy boundaries
+- validation findings
+
+Mermaid output is intended for human inspection:
+
+```powershell
+agentic-sdlc visualize fixtures/valid_workflow
+```
+
+JSON output is the canonical machine-readable graph:
+
+```powershell
+agentic-sdlc visualize fixtures/missing_review_evidence --json
+```
+
+The JSON graph includes nodes, edges, counts, validation status, and redacted
+finding messages. It does not include raw record payloads or loader-private
+fields.
+
+SVG output is the minimal visual form:
+
+```powershell
+agentic-sdlc visualize fixtures/valid_workflow --format svg --output workflow.svg
+```
+
+The SVG uses shape language instead of verbose labels:
+
+- task: square
+- event: circle
+- review gate: diamond
+- artifact: ellipse
+- missing evidence: dashed octagon
+- invalid record: red outline with compact `ASDLC###` label
+
+## Boundary
+
+Visualization is not a dashboard, watcher, scheduler, runtime trace, or agent
+orchestrator. Live agent progress such as `builder working 4m 16s` belongs to a
+future runtime adapter after the offline evidence model is stable.

evidence/visualize-readiness-workflow/artifacts.jsonl

@@ -0,0 +1,8 @@
+{"schema_version":"1.0","artifact_type":"artifact","id":"artifact_visualize_research","created_at":"2026-05-20T18:03:30Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","artifact_kind":"analysis","status":"passed","required":true,"summary":"Inspected CLI, validator, fixtures, schemas, tests, README, V1 spec, and external Mermaid syntax before implementation."}
+{"schema_version":"1.0","artifact_type":"artifact","id":"artifact_visualize_code","created_at":"2026-05-20T18:04:30Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","artifact_kind":"implementation","status":"passed","required":true,"subject_paths":["src/agentic_sdlc/visualize.py","src/agentic_sdlc/cli.py","tests/test_visualize.py","README.md","docs/v1-spec.md","docs/visualization.md","evidence/visualize-readiness-workflow/**"],"summary":"Added normalized graph model, Mermaid renderer, JSON renderer, visualize CLI, docs, tests, and real workflow evidence records."}
+{"schema_version":"1.0","artifact_type":"artifact","id":"artifact_visualize_tests","created_at":"2026-05-20T18:05:30Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","artifact_kind":"test_result","status":"passed","required":true,"command":"python -m unittest discover -s tests -v","observed_result":"unit tests passed"}
+{"schema_version":"1.0","artifact_type":"artifact","id":"artifact_visualize_valid_demo","created_at":"2026-05-20T18:06:30Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","artifact_kind":"cli_output","status":"passed","required":true,"command":"agentic-sdlc visualize fixtures/valid_workflow --json","observed_result":"valid workflow rendered with PASS state and evidence-chain edges"}
+{"schema_version":"1.0","artifact_type":"artifact","id":"artifact_visualize_invalid_demo","created_at":"2026-05-20T18:07:00Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","artifact_kind":"cli_output","status":"passed","required":true,"command":"agentic-sdlc visualize fixtures/missing_review_evidence --json","observed_result":"invalid workflow rendered with ASDLC010 finding and nonzero validation exit"}
+{"schema_version":"1.0","artifact_type":"artifact","id":"artifact_visualize_svg_demo","created_at":"2026-05-20T18:07:15Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","artifact_kind":"visual_output","status":"passed","required":true,"command":"agentic-sdlc visualize evidence/visualize-readiness-workflow --format svg --output evidence/visualize-readiness-workflow/workflow.svg","observed_result":"actual SVG diagram rendered with boxes, circles, diamonds, ellipses, arrows, and minimal labels"}
+{"schema_version":"1.0","artifact_type":"artifact","id":"artifact_visualize_self_validation","created_at":"2026-05-20T18:07:30Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","artifact_kind":"validation_result","status":"passed","required":true,"command":"agentic-sdlc validate evidence/visualize-readiness-workflow","observed_result":"real workflow evidence validated successfully"}
+{"schema_version":"1.0","artifact_type":"artifact","id":"artifact_visualize_privacy_scan","created_at":"2026-05-20T18:08:00Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","artifact_kind":"privacy_check","status":"passed","required":true,"command":"agentic-sdlc validate evidence/visualize-readiness-workflow","observed_result":"validator privacy checks passed for the persisted workflow evidence"}

evidence/visualize-readiness-workflow/events.jsonl

@@ -0,0 +1,6 @@
+{"schema_version":"1.0","artifact_type":"event","id":"event_visualize_research","created_at":"2026-05-20T18:01:00Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","event_type":"research_and_breadth_review","task_id":"task_visualize_readiness","sequence":1}
+{"schema_version":"1.0","artifact_type":"event","id":"event_visualize_system_analysis","created_at":"2026-05-20T18:02:00Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","event_type":"repo_system_analysis","task_id":"task_visualize_readiness","sequence":2}
+{"schema_version":"1.0","artifact_type":"event","id":"event_visualize_reverse_pass","created_at":"2026-05-20T18:03:00Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","event_type":"plan_reverse_pass_resolved","task_id":"task_visualize_readiness","sequence":3}
+{"schema_version":"1.0","artifact_type":"event","id":"event_visualize_implementation","created_at":"2026-05-20T18:04:00Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","event_type":"implementation_completed","task_id":"task_visualize_readiness","sequence":4}
+{"schema_version":"1.0","artifact_type":"event","id":"event_visualize_tests_passed","created_at":"2026-05-20T18:05:00Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","event_type":"tests_passed","task_id":"task_visualize_readiness","sequence":5}
+{"schema_version":"1.0","artifact_type":"event","id":"event_visualize_self_validation","created_at":"2026-05-20T18:06:00Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","event_type":"self_validation_passed","task_id":"task_visualize_readiness","sequence":6}

evidence/visualize-readiness-workflow/handoffs.jsonl

@@ -0,0 +1 @@
+{"schema_version":"1.0","artifact_type":"handoff","id":"handoff_visualize_readiness","created_at":"2026-05-20T18:00:30Z","provenance":{"source":"actual_repo_change","actor":"orchestrator"},"privacy_classification":"internal","task_id":"task_visualize_readiness","objective":"Add a read-only visualization command that renders workflow records and validation state as deterministic JSON or Mermaid.","allowed_paths":["src/agentic_sdlc/visualize.py","src/agentic_sdlc/cli.py","tests/test_visualize.py","README.md","docs/v1-spec.md","docs/visualization.md","evidence/visualize-readiness-workflow/**"],"return_contract":"Return changed files, commands run, validation outputs, and remaining risks without raw transcripts or secrets.","evidence_required":["repo_inspection","implementation_summary","unit_tests","cli_visualization_demo","self_validation","privacy_scan"]}

evidence/visualize-readiness-workflow/ownership_claims.jsonl

@@ -0,0 +1 @@
+{"schema_version":"1.0","artifact_type":"ownership_claim","id":"ownership_visualize_main","created_at":"2026-05-20T18:00:45Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","task_id":"task_visualize_readiness","owner":"codex-main-thread","paths":["src/agentic_sdlc/visualize.py","src/agentic_sdlc/cli.py","tests/test_visualize.py","README.md","docs/v1-spec.md","docs/visualization.md","evidence/visualize-readiness-workflow/**"],"coordination_id":"visualize-readiness-workflow"}

evidence/visualize-readiness-workflow/privacy_boundaries.jsonl

@@ -0,0 +1 @@
+{"schema_version":"1.0","artifact_type":"privacy_boundary","id":"privacy_visualize_records","created_at":"2026-05-20T18:01:15Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","task_id":"task_visualize_readiness","scope":"repo-local workflow evidence","policy":"Persist concise artifact summaries and command names only; do not persist secrets, raw transcripts, private absolute paths, or bulky logs."}

evidence/visualize-readiness-workflow/returns.jsonl

@@ -0,0 +1 @@
+{"schema_version":"1.0","artifact_type":"return_resume","id":"resume_visualize_readiness_done","created_at":"2026-05-20T18:12:00Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","task_id":"task_visualize_readiness","handoff_id":"handoff_visualize_readiness","last_seen_event_id":"event_visualize_self_validation","next_safe_action":"Use the visualize command to inspect real workflow records, then harden SOP-specific adherence rules in a separate slice.","commands_run":["python -m unittest discover -s tests -v","agentic-sdlc visualize fixtures/valid_workflow --json","agentic-sdlc visualize fixtures/missing_review_evidence --json","agentic-sdlc visualize evidence/visualize-readiness-workflow --format svg --output evidence/visualize-readiness-workflow/workflow.svg","agentic-sdlc validate evidence/visualize-readiness-workflow"],"checks":[{"name":"unit_tests","status":"passed","evidence_id":"artifact_visualize_tests"},{"name":"valid_visualization_demo","status":"passed","evidence_id":"artifact_visualize_valid_demo"},{"name":"invalid_visualization_demo","status":"passed","evidence_id":"artifact_visualize_invalid_demo"},{"name":"svg_visualization_demo","status":"passed","evidence_id":"artifact_visualize_svg_demo"},{"name":"self_validation","status":"passed","evidence_id":"artifact_visualize_self_validation"}],"touched_paths":["src/agentic_sdlc/visualize.py","src/agentic_sdlc/cli.py","tests/test_visualize.py","README.md","docs/v1-spec.md","docs/visualization.md","evidence/visualize-readiness-workflow/**"],"open_decisions":["Define a dedicated SOP adherence rule only after the evidence model stabilizes."],"blocked_actions":[],"requires_human_approval":[]}

evidence/visualize-readiness-workflow/review_gates.jsonl

@@ -0,0 +1,5 @@
+{"schema_version":"1.0","artifact_type":"review_gate","id":"gate_visualize_research","created_at":"2026-05-20T18:09:00Z","provenance":{"source":"actual_repo_change","actor":"reviewer"},"privacy_classification":"internal","task_id":"task_visualize_readiness","gate_type":"research_system_analysis","status":"passed","required_evidence":["analysis"],"evidence":["artifact_visualize_research"]}
+{"schema_version":"1.0","artifact_type":"review_gate","id":"gate_visualize_implementation","created_at":"2026-05-20T18:09:30Z","provenance":{"source":"actual_repo_change","actor":"reviewer"},"privacy_classification":"internal","task_id":"task_visualize_readiness","gate_type":"implementation_review","status":"passed","required_evidence":["implementation"],"evidence":["artifact_visualize_code"]}
+{"schema_version":"1.0","artifact_type":"review_gate","id":"gate_visualize_tests","created_at":"2026-05-20T18:10:00Z","provenance":{"source":"actual_repo_change","actor":"reviewer"},"privacy_classification":"internal","task_id":"task_visualize_readiness","gate_type":"tests","status":"passed","required_evidence":["test_result"],"evidence":["artifact_visualize_tests"]}
+{"schema_version":"1.0","artifact_type":"review_gate","id":"gate_visualize_demo","created_at":"2026-05-20T18:10:30Z","provenance":{"source":"actual_repo_change","actor":"reviewer"},"privacy_classification":"internal","task_id":"task_visualize_readiness","gate_type":"demo_and_self_validation","status":"passed","required_evidence":["cli_output","visual_output","validation_result"],"evidence":["artifact_visualize_valid_demo","artifact_visualize_invalid_demo","artifact_visualize_svg_demo","artifact_visualize_self_validation"]}
+{"schema_version":"1.0","artifact_type":"review_gate","id":"gate_visualize_privacy","created_at":"2026-05-20T18:11:00Z","provenance":{"source":"actual_repo_change","actor":"reviewer"},"privacy_classification":"internal","task_id":"task_visualize_readiness","gate_type":"privacy","status":"passed","required_evidence":["privacy_check"],"evidence":["artifact_visualize_privacy_scan"]}

evidence/visualize-readiness-workflow/tasks.jsonl

@@ -0,0 +1 @@
+{"schema_version":"1.0","artifact_type":"task","id":"task_visualize_readiness","created_at":"2026-05-20T18:00:00Z","provenance":{"source":"actual_repo_change","actor":"codex-main-thread"},"privacy_classification":"internal","title":"Add deterministic workflow visualization","status":"done","depends_on":[],"review_gate_ids":["gate_visualize_research","gate_visualize_implementation","gate_visualize_tests","gate_visualize_demo","gate_visualize_privacy"],"current_resume_id":"resume_visualize_readiness_done"}