Intent Contract
| Dimension | Question | Decision Log CLI |
|---|---|---|
| Objective | What problem, and why now? | Decisions and reasoning are lost in chat or ephemeral agent memory; we need a durable Context Graph. |
| Desired Outcomes | Observable state changes proving success (2–4) | Structured JSON/MD traces emitted to standardized store; CLI callable by humans and agents in <5 seconds. |
| Health Metrics | What must not degrade? | Existing CLI performance; workflow friction must remain near zero. |
| Hard Constraints | What the system blocks regardless of agent intent | Trace must contain context, options, decision, outcome criteria, and approver. |
| Steering | How it should think and trade off | Bias for simplicity over exhaustive formatting; capture the why. |
| Autonomy | What it may do alone / must escalate / must never do | Allowed: Log independent actions. Escalate: When policy exception required. |
| Stop Rules | Complete when... Halt & escalate when... | Complete when trace securely written to graph storage. Halt on schema violation. |
| Evidence | For each outcome, what artifact proves it happened? | Machine-readable decision log entry (/data/decisions/*.json or similar). |
| Verification | How each artifact is checked | Schema validator runs on CI to ensure traces match Context Graph node requirements. |
Story Contract
Stories are test contracts. Tests must be RED before implementation starts. GREEN = value delivered.
S1 — Agent logs a decision durably
Trigger: Agent invokes log-decision with a valid trace payload during a workflow
Checklist:
- CLI writes a structured tracing node with all required fields
- CLI returns a durable Trace ID
- Payload without required fields (e.g., missing why) is rejected — not silently accepted
Forbidden: Payload accepted without required fields. No Trace ID returned.
Evidence: integration — tests/cli/log-decision.spec.ts
Commission Result: ⬜ PASS / ⬜ FAIL Notes: (findings)
S2 — Human logs a decision via CLI
Trigger: Human runs claude /log-decision
Checklist:
- Prompt sequence requests Situation, Options, Decision, and Expected Outcome in order
- Structured node saved after all fields collected
- Free-text accepted only within structured fields — no unstructured dump mode
Forbidden: CLI drops into free-text without structural coercion.
Evidence: integration — tests/cli/human-log.spec.ts
Commission Result: ⬜ PASS / ⬜ FAIL Notes: (findings)
Build Contract
| # | FeatureID | Feature | Function | Artifact | Success Test | Safety Test | Regression Test | Value | State |
|---|---|---|---|---|---|---|---|---|---|
| 1 | inst-dec-cli | CLI Logger | Capture formatted decision traces via terminal | src/cli/log-decision | S1, S2 | F1 | cli_load_time | Enables frictionless entry of Context Graph nodes | Stub |
| 2 | inst-dec-schema | Trace Schema Validator | Validate decision payloads against node schema | src/schema/decision | S1 | F1 | N/A | Ensures graph integrity and cross-agent interop | Stub |
Principles
SIO:
- Situation: When an agent or human makes a workflow routing decision, policy exception, or architectural choice.
- Intention: The "why" must be captured durably alongside the "what" as a Graph node.
- Obstacle: Ephemeral chat/reasoning creates organizational amnesia.
- Hardest Thing: Ensuring the capture mechanism isn't bypassed due to high friction.
Performance
- Priority Score: 2000 (Build Now)
- Quality Targets: Valid traces captured in <2 seconds.
- Kill Signal: Trace data goes unqueried for >90 days.
Platform
- Current State: Traces lost in Slack/Claude history.
- Build Ratio: 90% logic, 10% wiring.
Protocols
- Build Order: Schema -> CLI Capture -> Graph Query.
- Commissioning: L2 verified when 5 consecutive real-world decisions are logged and queried.
Players
- Demand-Side Jobs: As an agent orchestrator, I want to durably log my reasoning so my decisions act as precedent. As a manager, I want to query why an exception was granted so I can refine policies.
Context
- PRD Index — Decision Trace Logging CLI
- Prompt Deck — 5-card pitch
- Pictures — Pre-flight maps