[codex] Add decision and thread planning modules

.agent-os/decision-policy.yaml

@@ -0,0 +1,3 @@
+decision_policy:
+  strictness: warn
+  downgrade_reason: ""

.agent-os/specs.yaml

@@ -1,7 +1,17 @@
-active_spec: SPEC-20260513-001
+active_spec: SPEC-20260529-001
 specs:
   - id: SPEC-20260513-001
     title: "KnowledgeOS Core Product Philosophy"
     status: active
     created_at: 2026-05-13T05:59:52.646718+00:00
     path: .agent-os/specs/SPEC-20260513-001
+  - id: SPEC-20260519-001
+    title: "Capability effect verification"
+    status: active
+    created_at: 2026-05-19T01:20:48.972160+00:00
+    path: .agent-os/specs/SPEC-20260519-001
+  - id: SPEC-20260529-001
+    title: "Decision Graph Module"
+    status: active
+    created_at: 2026-05-29T14:25:59.993564+00:00
+    path: .agent-os/specs/SPEC-20260529-001

.agent-os/specs/SPEC-20260529-001/acceptance.md

@@ -0,0 +1,10 @@
+# Acceptance
+
+- `decision-event` records command-generated decision events and returns `DECISION_OK`.
+- `decision-query` returns filtered parent/child decision events.
+- `verify-decisions` rejects forged or orphaned decision events and emits `DECISION_VERIFY_OK`.
+- `decision-policy strictness: warn` does not block linear work without decision events.
+- `decision-policy strictness: enforce` blocks completion without valid decision evidence.
+- `decision-policy strictness: off` requires `downgrade_reason`.
+- `render-html --kind decision-map` creates a self-contained HTML sidecar with source hash metadata.
+- Documentation explains Decision Graph as a module, not kernel.

.agent-os/specs/SPEC-20260529-001/alignment.md

@@ -0,0 +1,3 @@
+# Alignment
+
+No alignment has been run yet.

.agent-os/specs/SPEC-20260529-001/change-log.ndjson

@@ -0,0 +1,2 @@
+{"event_type": "create-spec", "set_active": true, "timestamp": "2026-05-29T14:25:59.994039+00:00", "title": "Decision Graph Module"}
+{"timestamp":"2026-05-29T14:36:16Z","change":"Filled Decision Graph Module spec with public contract, acceptance, and non-goals."}

.agent-os/specs/SPEC-20260529-001/non-goals.md

@@ -0,0 +1,7 @@
+# Non-Goals
+
+- Do not store hidden chain-of-thought.
+- Do not make Decision Graph mandatory for minimal projects.
+- Do not replace `trace-step`, `phase-task`, `capability-event`, or `artifact-assert`.
+- Do not auto-open HTML in v1.
+- Do not build a full visual Workbench UI in this change.

.agent-os/specs/SPEC-20260529-001/spec.md

@@ -0,0 +1,26 @@
+# Spec: Decision Graph Module
+
+## Intent
+
+Add an optional Decision Graph module that records public, auditable natural-language decision summaries during KnowledgeOS runs. The module captures plan branches, route selections, inserted steps, abandoned branches, rollbacks, superseded paths, deferred work, human decisions, risk tradeoffs, and final decisions.
+
+The module must preserve KnowledgeOS product philosophy:
+
+```text
+small kernel + pluggable modules + optional apps + project-level strictness + mandatory visible checkpoints
+```
+
+Decision Graph is not kernel. It is a module that can be observed by default and enforced only by project policy.
+
+## Public Contract
+
+- `decision-event` writes `.agent-os/runs/<RUN_ID>/decision-events.ndjson` and emits `DECISION_OK`.
+- `decision-query` filters decision events by run, task, kind, status, or parent id.
+- `verify-decisions` checks command evidence, orphan parents, duplicate ids, invalid kinds/statuses, and unexplained abandoned/rollback/superseded branches.
+- `render-html --kind decision-map` renders a static HTML sidecar from `decision-events.ndjson`.
+- `.agent-os/decision-policy.yaml` defaults to `strictness: warn`.
+- `complete-task` blocks only when decision verification status is failed, including `strictness: enforce` without valid decision evidence.
+
+## Source Of Truth
+
+The source of truth is NDJSON under `.agent-os/runs/<RUN_ID>/decision-events.ndjson`. HTML is presentation only.

.agent-os/startup-prompt.md

@@ -9,27 +9,30 @@ This prompt is only the session trigger. Durable rules live in `AGENTS.md`, `.ag
 Before substantial work:
 
 1. Read `AGENTS.md`.
-2. Read `.agent-os/workspace.yaml`, `.agent-os/project.yaml`, `.agent-os/tasks.yaml`, `.agent-os/specs.yaml`, `.agent-os/phase-policy.yaml`, `.agent-os/effect-policy.yaml`, `.agent-os/decisions.yaml`, `.agent-os/evals.yaml`, `.agent-os/fabric-link.yaml`, `.agent-os/read-policy.yaml`, `.agent-os/write-policy.yaml`, `.agent-os/dispatch-policy.yaml`, and `.agent-os/tool-registry.yaml`.
+2. Read `.agent-os/workspace.yaml`, `.agent-os/project.yaml`, `.agent-os/tasks.yaml`, `.agent-os/specs.yaml`, `.agent-os/phase-policy.yaml`, `.agent-os/decision-policy.yaml`, `.agent-os/effect-policy.yaml`, `.agent-os/decisions.yaml`, `.agent-os/evals.yaml`, `.agent-os/fabric-link.yaml`, `.agent-os/read-policy.yaml`, `.agent-os/write-policy.yaml`, `.agent-os/dispatch-policy.yaml`, and `.agent-os/tool-registry.yaml`.
 3. Run `./bin/knowledgeos doctor --project-root . --summary` and do not proceed if it fails.
 4. If the user says `create spec`, `align spec`, `创建spec`, `对齐spec`, or equivalent, run `./bin/knowledgeos create-spec --project-root . --title "<title>"` or `./bin/knowledgeos align-spec --project-root . --task-id <task-id>` before execution.
-5. Select or confirm one task id from `.agent-os/tasks.yaml`.
-6. Run `./bin/knowledgeos route-task --project-root . --task-id <task-id>`.
-7. Run `./bin/knowledgeos dispatch-task --project-root . --task-id <task-id>` before invoking subagents, MCP tools, skills, workflows, or scripts.
-8. Before planned mutation, run `./bin/knowledgeos check-route-write --project-root . --task-id <task-id> --path <planned-path>`.
-9. Create run evidence with `./bin/knowledgeos run-task --project-root . --task-id <task-id>`.
-10. Write/update the execution context with `./bin/knowledgeos context-pack --project-root . --task-id <task-id> --run-id <run-id>` and `./bin/knowledgeos plan-task --project-root . --task-id <task-id> --run-id <run-id> --summary "<summary>"`.
-11. Pause at consultation checkpoints, state your recommended next move, name the tradeoff, and ask the human whether to proceed.
-12. Record run-bound dispatch evidence with `./bin/knowledgeos dispatch-task --project-root . --task-id <task-id> --run-id <run-id>`.
-13. Record public operational progress with `./bin/knowledgeos trace-step --project-root . --task-id <task-id> --run-id <run-id> --step <step> --note "<public trace>" --evidence "<command/file/user confirmation>"`, and relay the returned `TRACE_OK` marker.
-14. Record public phase evidence with `./bin/knowledgeos phase-task --project-root . --task-id <task-id> --run-id <run-id> --phase <route|plan|review|dispatch|execute|report> --status completed --note "<public trace>" --evidence "<command/file/user confirmation>"`, and relay the returned `CHECKPOINT_OK` marker.
-15. Record MCP, skill, subagent, orchestrator, or important script use with `./bin/knowledgeos capability-event --project-root . --task-id <task-id> --run-id <run-id> --kind <kind> --id <capability-id> --purpose "<purpose>"`, and relay the returned `CAPABILITY_OK` marker.
-16. Verify real side effects with `./bin/knowledgeos artifact-assert --project-root . --task-id <task-id> --run-id <run-id> --kind <kind> --path <artifact>` and relay the returned `EFFECT_OK` marker.
-17. Run `./bin/knowledgeos eval-task --project-root . --task-id <task-id> --run-id <run-id>`; do not manually append eval status.
-18. Run `./bin/knowledgeos verify-context --project-root . --task-id <task-id> --run-id <run-id>`, `./bin/knowledgeos verify-lifecycle --project-root . --task-id <task-id> --run-id <run-id>`, and `./bin/knowledgeos verify-effects --project-root . --task-id <task-id> --run-id <run-id>`; relay the returned `EFFECT_VERIFY_OK` marker before claiming effect verification success.
-19. Use `./bin/knowledgeos complete-task --project-root . --task-id <task-id> --run-id <run-id> --summary "<summary>"`; it enforces spec/context/plan, lifecycle, capability visibility, effect verification, and required postflight.
-20. If a shared-fabric postflight hook is configured, report `[SYNC_OK]` only after `complete-task` returns `sync_status: SYNC_OK`.
-21. For reset requests, run `./bin/knowledgeos reset-project --project-root . --mode <soft|hard> --dry-run` before destructive action.
-22. For old-project reorganization requests, run `./bin/knowledgeos migrate-legacy-project --project-root . --write-plan` before moving files.
-23. For historical or superseded files that should be stored but not read by default, run `./bin/knowledgeos archive-legacy-project --project-root . --write-plan` before moving files into `archive/`.
+5. If the user starts or continues a durable plan/spec conversation, run `./bin/knowledgeos thread-plan current --project-root .` or `./bin/knowledgeos thread-plan start --project-root . --title "<natural language goal>"`; append plain-language progress with `./bin/knowledgeos thread-plan append --project-root . --thread-id <thread-id> --kind <kind> --text "<plain note>"` and relay `THREAD_PLAN_OK`.
+6. Select or confirm one task id from `.agent-os/tasks.yaml`.
+7. Run `./bin/knowledgeos route-task --project-root . --task-id <task-id>`.
+8. Run `./bin/knowledgeos dispatch-task --project-root . --task-id <task-id>` before invoking subagents, MCP tools, skills, workflows, or scripts.
+9. Before planned mutation, run `./bin/knowledgeos check-route-write --project-root . --task-id <task-id> --path <planned-path>`.
+10. Create run evidence with `./bin/knowledgeos run-task --project-root . --task-id <task-id>`.
+11. Write/update the execution context with `./bin/knowledgeos context-pack --project-root . --task-id <task-id> --run-id <run-id>` and `./bin/knowledgeos plan-task --project-root . --task-id <task-id> --run-id <run-id> --summary "<summary>"`.
+12. Pause at consultation checkpoints, state your recommended next move, name the tradeoff, and ask the human whether to proceed.
+13. Record run-bound dispatch evidence with `./bin/knowledgeos dispatch-task --project-root . --task-id <task-id> --run-id <run-id>`.
+14. Record public operational progress with `./bin/knowledgeos trace-step --project-root . --task-id <task-id> --run-id <run-id> --step <step> --note "<public trace>" --evidence "<command/file/user confirmation>"`, and relay the returned `TRACE_OK` marker.
+15. Record public phase evidence with `./bin/knowledgeos phase-task --project-root . --task-id <task-id> --run-id <run-id> --phase <route|plan|review|dispatch|execute|report> --status completed --note "<public trace>" --evidence "<command/file/user confirmation>"`, and relay the returned `CHECKPOINT_OK` marker.
+16. Record MCP, skill, subagent, orchestrator, or important script use with `./bin/knowledgeos capability-event --project-root . --task-id <task-id> --run-id <run-id> --kind <kind> --id <capability-id> --purpose "<purpose>"`, and relay the returned `CAPABILITY_OK` marker.
+17. Record public decision changes with `./bin/knowledgeos decision-event --project-root . --task-id <task-id> --run-id <run-id> --kind <kind> --title "<title>" --summary "<summary>" --reason "<reason>" --evidence "<evidence>"`, and relay the returned `DECISION_OK` marker when plans branch, change, roll back, or abandon a route.
+18. Verify real side effects with `./bin/knowledgeos artifact-assert --project-root . --task-id <task-id> --run-id <run-id> --kind <kind> --path <artifact>` and relay the returned `EFFECT_OK` marker.
+19. Run `./bin/knowledgeos eval-task --project-root . --task-id <task-id> --run-id <run-id>`; do not manually append eval status.
+20. Run `./bin/knowledgeos verify-context --project-root . --task-id <task-id> --run-id <run-id>`, `./bin/knowledgeos verify-lifecycle --project-root . --task-id <task-id> --run-id <run-id>`, `./bin/knowledgeos verify-effects --project-root . --task-id <task-id> --run-id <run-id>`, and `./bin/knowledgeos verify-decisions --project-root . --task-id <task-id> --run-id <run-id>`; relay `EFFECT_VERIFY_OK` and `DECISION_VERIFY_OK` before claiming verification success.
+21. Use `./bin/knowledgeos complete-task --project-root . --task-id <task-id> --run-id <run-id> --summary "<summary>"`; it enforces spec/context/plan, lifecycle, capability visibility, effect verification, decision verification, and required postflight.
+22. For medium, high, or complex tasks, include the returned `FLOW_OK` Mermaid Mission Flow in the final answer; if needed, run `./bin/knowledgeos flow-summary --project-root . --run-id <run-id>`.
+23. If a shared-fabric postflight hook is configured, report `[SYNC_OK]` only after `complete-task` returns `sync_status: SYNC_OK`.
+24. For reset requests, run `./bin/knowledgeos reset-project --project-root . --mode <soft|hard> --dry-run` before destructive action.
+25. For old-project reorganization requests, run `./bin/knowledgeos migrate-legacy-project --project-root . --write-plan` before moving files.
+26. For historical or superseded files that should be stored but not read by default, run `./bin/knowledgeos archive-legacy-project --project-root . --write-plan` before moving files into `archive/`.
 
-Never claim boot, route, dispatch, write safety, spec alignment, context pack, plan, trace, checkpoint, capability, effect, eval, completion, or sync success without command evidence.
+Never claim boot, route, dispatch, write safety, spec alignment, thread plan, context pack, plan, trace, checkpoint, capability, decision, effect, eval, completion, flow, or sync success without command evidence.