wisk 0.3.0__py3-none-any.whl

wisk/__init__.py

@@ -0,0 +1,12 @@
+"""Wisk compatibility runtime built on OKF.
+
+The public product/package name is ``wisk``. ``wisk`` remains importable
+for compatibility with existing consumers during the rename transition.
+"""
+
+from wisk.live_run import LiveRunWisk as Wisk
+
+Wisk = Wisk
+
+__version__ = "0.3.0"
+__all__ = ["Wisk", "Wisk", "__version__"]

wisk/_assets/canonical/run-specs/experience.md

@@ -0,0 +1,26 @@
+---
+type: RunSpec
+id: run-specs/experience
+title: Experience run
+version: "1.0.0"
+status: experimental
+required_reading_kinds:
+  - active-handoffs
+  - active-skills
+required_goal_kinds:
+  - task-advance
+required_evidence_kinds:
+  - execution
+required_check_kinds:
+  - verification
+allowed_result_states:
+  - success
+  - partial
+  - blocked
+  - no-useful-change
+completion_notes: "Do useful work when available, verify the observed result, and preserve truthful episodic evidence including the skill/version actually used."
+---
+
+# Experience RunSpec
+
+The canonical execution contract. `verification` asks whether the claimed observed effect is supported by the execution evidence. It does not decide whether a skill should be promoted globally.

wisk/_assets/canonical/run-specs/skill.md

@@ -0,0 +1,31 @@
+---
+type: RunSpec
+id: run-specs/skill
+title: Skill evolution run
+version: "1.0.0"
+status: experimental
+required_reading_kinds:
+  - wiki
+  - experiences
+  - active-skills
+  - active-handoffs
+required_goal_kinds:
+  - evolve-skill
+required_evidence_kinds:
+  - intervention
+required_check_kinds:
+  - lineage
+allowed_result_states:
+  - proposed
+  - refined
+  - promoted
+  - rejected
+  - no-change
+  - partial
+  - blocked
+completion_notes: "Make a justified procedural intervention or lifecycle decision, preserving lineage to the WikiEntry and Experience evidence that supports it."
+---
+
+# Skill RunSpec
+
+The canonical procedural-evolution contract. `lineage` asks whether the intervention or lifecycle action is supported by durable knowledge and traceable execution evidence. Creating a candidate does not satisfy promotion; promotion is a later possible result after evidence accumulates.

wisk/_assets/canonical/run-specs/wiki.md

@@ -0,0 +1,27 @@
+---
+type: RunSpec
+id: run-specs/wiki
+title: Wiki synthesis run
+version: "1.0.0"
+status: experimental
+required_reading_kinds:
+  - experiences
+  - wiki
+  - active-handoffs
+required_goal_kinds:
+  - consolidate-knowledge
+required_evidence_kinds:
+  - consolidation
+required_check_kinds:
+  - grounding
+allowed_result_states:
+  - updated
+  - no-change
+  - partial
+  - blocked
+completion_notes: "Synthesize durable knowledge from Experience evidence; when variants differ, preserve that distinction and comparative evidence rather than collapsing it."
+---
+
+# Wiki RunSpec
+
+The canonical synthesis contract. `grounding` asks whether the WikiEntry claims are traceable to Experience evidence and whether meaningful counterevidence or variant differences were preserved.

wisk/_assets/canonical/session-types/experience.md

@@ -0,0 +1,15 @@
+---
+type: SessionType
+id: session-types/experience
+title: Experience
+purpose: "Execute real work under available skills and record truthful episodic evidence of what happened."
+run_spec: run-specs/experience
+nudges:
+  - "Do useful external work; the session exists to generate experience, not to judge a skill globally."
+  - "Record which AgentSkill and version actually guided the execution so incumbent and experimental candidates remain distinguishable."
+  - "Treat one successful or failed execution as evidence, not as automatic promotion or rejection of a skill."
+---
+
+# Experience session
+
+Canonical execution role in the Wisk learning cycle. It deliberately carries no context, access, output, or cadence policy: consumer work sessions specialize this role and compose the policies appropriate to their environment.

wisk/_assets/canonical/session-types/skill.md

@@ -0,0 +1,16 @@
+---
+type: SessionType
+id: session-types/skill
+title: Skill
+purpose: "Change future procedural behavior using durable knowledge and supporting execution evidence."
+run_spec: run-specs/skill
+nudges:
+  - "Create or revise a candidate only when accumulated knowledge supports a procedural intervention."
+  - "Keep an incumbent available while an experimental candidate is gathering evidence; creating a candidate is not promotion."
+  - "Use later Wiki synthesis to decide whether to refine, continue experimenting, promote, reject, deprecate, or replace a candidate."
+  - "Preserve lineage from the decision back to WikiEntry and Experience evidence."
+---
+
+# Skill session
+
+Canonical procedural-evolution role in the Wisk learning cycle. It is policy-neutral; consumers compose access, context, output, and cadence in their own specializations.

wisk/_assets/canonical/session-types/wiki.md

@@ -0,0 +1,16 @@
+---
+type: SessionType
+id: session-types/wiki
+title: Wiki
+purpose: "Synthesize episodic evidence into durable knowledge, including comparison across skill variants when relevant."
+run_spec: run-specs/wiki
+nudges:
+  - "Ground durable knowledge in Experience records rather than intuition or one-off narrative."
+  - "When incumbent and candidate skills were both exercised, keep their evidence distinguishable and synthesize the comparison explicitly."
+  - "Describe scope, strengths, regressions, trade-offs, failure modes, and counterevidence when the experiences support them."
+  - "Do not promote or reject a skill; produce knowledge that a later Skill session can act on."
+---
+
+# Wiki session
+
+Canonical synthesis role in the Wisk learning cycle. It is policy-neutral; consumers decide what context it can read, what it can write, and when it should run.

wisk/_assets/specs/accesspolicy.md

@@ -0,0 +1,25 @@
+---
+type: ConceptSpecification
+concept_type: AccessPolicy
+description: "Declares repositories, paths, connectors, and tools a SessionType should or may be restricted to using."
+---
+
+# Concept: AccessPolicy
+
+`AccessPolicy` is separate from context curation. It describes the desired access boundary and whether the host should treat it as advisory, scoped, or enforced.
+
+## Required Frontmatter Fields
+
+- `type`: `"AccessPolicy"`
+- `id`: Stable identifier
+- `title`: Human-readable name
+- `mode`: `advisory`, `scoped`, or `enforced`
+
+## Optional Frontmatter Fields
+
+- `repositories`: Repository identifiers or URLs
+- `paths`: Repository/workspace path scopes
+- `connectors`: Connector/tool families relevant to the session
+- `instructions`: Human-readable access guidance
+
+Wisk always exposes the requested policy. Actual coercive enforcement is a capability of the host environment and must not be claimed when unavailable.

wisk/_assets/specs/accesspolicy.schema.sql

@@ -0,0 +1,9 @@
+CREATE TABLE "AccessPolicy" (
+    "id" VARCHAR,
+    "title" VARCHAR,
+    "mode" VARCHAR,
+    "repositories" VARCHAR[],
+    "paths" VARCHAR[],
+    "connectors" VARCHAR[],
+    "instructions" VARCHAR[]
+);

wisk/_assets/specs/agentskill.md

@@ -0,0 +1,33 @@
+---
+type: ConceptSpecification
+concept_type: AgentSkill
+description: "Actionable, procedural guidance and policies executed by agents."
+---
+
+# Concept: AgentSkill
+
+An `AgentSkill` is a concise, procedural rulebook. It answers: *given what we learned, how should the agent act?*
+
+A skill may also reference a `RunSpec` that turns the skill into a contract-guided execution protocol. The skill describes reusable procedure; the `RunSpec` describes what a well-formed live run must establish, read, evidence and verify.
+
+## Required Frontmatter Fields
+
+- `type`: Must be `"AgentSkill"`
+- `id`: Skill identifier (e.g. `skill-develop-feature`)
+- `title`: Human-readable skill name
+- `version`: Semver or incremental version string (e.g. `"1.0.0"`)
+- `status`: Skill lifecycle state (`"active"`, `"deprecated"`, `"experimental"`)
+
+## Optional Frontmatter Fields
+
+- `derived_from`: Links to `[WikiEntry](../wiki/...)` justifying this procedure
+- `tags`: List of domain/tool tags
+- `run_spec`: Link to the default `RunSpec` that operationalizes this skill
+
+## Content Structure
+
+The body must be:
+- Concise, procedural, step-by-step.
+- Free of raw conversation dumps or unverified notes.
+
+An `experimental` AgentSkill may coexist with the active incumbent while Experience sessions gather evidence under each version. Wiki sessions synthesize and compare those experiences; later Skill sessions decide whether to refine, continue experimenting, promote, reject, deprecate, or replace the candidate. `SkillEvaluation` may record an explicit benchmark when useful, but it is not a mandatory fourth stage of the learning cycle.

wisk/_assets/specs/agentskill.schema.sql

@@ -0,0 +1,8 @@
+CREATE TABLE "AgentSkill" (
+    "id" VARCHAR,
+    "title" VARCHAR,
+    "version" VARCHAR,
+    "status" VARCHAR,
+    "derived_from" VARCHAR[],
+    "tags" VARCHAR[]
+);

wisk/_assets/specs/cadencepolicy.md

@@ -0,0 +1,31 @@
+---
+type: ConceptSpecification
+concept_type: CadencePolicy
+description: "Declares when a SessionType becomes eligible to start and the execution limits used to rank candidates."
+---
+
+# Concept: CadencePolicy
+
+`CadencePolicy` models session eligibility rather than reducing orchestration to cron.
+
+## Required Frontmatter Fields
+
+- `type`: `"CadencePolicy"`
+- `id`: Stable identifier
+- `title`: Human-readable name
+
+## Optional Frontmatter Fields
+
+- `on_demand`: Session may always be selected explicitly
+- `event_triggers`: Named events that make the session eligible
+- `interval_seconds`: Regular interval trigger
+- `threshold_metric`: Named runtime metric
+- `threshold_gte`: Minimum metric value for eligibility
+- `cooldown_seconds`: Minimum time after a prior run before automatic re-entry
+- `max_delay_seconds`: Maximum tolerated time without a run; exceeding it makes the session eligible
+- `priority`: Higher values rank first among eligible sessions
+- `max_parallel`: Maximum simultaneous active runs of this type
+- `max_runs_per_hour`: Rolling run budget
+- `handoff_compatible`: Whether a targeted active Handoff may activate this type
+
+Eligibility is inspectable: the runtime reports triggering reasons and blocking controls separately.

wisk/_assets/specs/cadencepolicy.schema.sql

@@ -0,0 +1,15 @@
+CREATE TABLE "CadencePolicy" (
+    "id" VARCHAR,
+    "title" VARCHAR,
+    "on_demand" BOOLEAN,
+    "event_triggers" VARCHAR[],
+    "interval_seconds" BIGINT,
+    "threshold_metric" VARCHAR,
+    "threshold_gte" BIGINT,
+    "cooldown_seconds" BIGINT,
+    "max_delay_seconds" BIGINT,
+    "priority" BIGINT,
+    "max_parallel" BIGINT,
+    "max_runs_per_hour" BIGINT,
+    "handoff_compatible" BOOLEAN
+);

wisk/_assets/specs/changelog.md

@@ -0,0 +1,7 @@
+---
+type: ConceptSpecification
+concept_type: Changelog
+description: Changelog card
+---
+
+# Changelog

wisk/_assets/specs/changelog.schema.sql

@@ -0,0 +1,4 @@
+CREATE TABLE "Changelog" (
+    "version" VARCHAR,
+    "date" VARCHAR
+);

wisk/_assets/specs/contextpolicy.md

@@ -0,0 +1,24 @@
+---
+type: ConceptSpecification
+concept_type: ContextPolicy
+description: "Declares what information is appropriate to surface to a SessionType and how strongly that curation is applied."
+---
+
+# Concept: ContextPolicy
+
+`ContextPolicy` separates epistemic guidance from technical access control.
+
+## Required Frontmatter Fields
+
+- `type`: `"ContextPolicy"`
+- `id`: Stable identifier
+- `title`: Human-readable name
+- `mode`: `advisory` or `curated`
+
+## Optional Frontmatter Fields
+
+- `include`: Context categories to surface by default
+- `exclude`: Context categories that are off-limits or omitted from curated context
+- `instructions`: Human-readable guidance shown to the agent
+
+`advisory` explains the intended boundary without coercion. `curated` also filters the context returned by the Wisk runtime, while still not pretending to restrict external tools the host makes available.

wisk/_assets/specs/contextpolicy.schema.sql

@@ -0,0 +1,8 @@
+CREATE TABLE "ContextPolicy" (
+    "id" VARCHAR,
+    "title" VARCHAR,
+    "mode" VARCHAR,
+    "include" VARCHAR[],
+    "exclude" VARCHAR[],
+    "instructions" VARCHAR[]
+);

wisk/_assets/specs/experience.md

@@ -0,0 +1,35 @@
+---
+type: ConceptSpecification
+concept_type: Experience
+description: "Raw episodic execution trace or observation recorded by an agent."
+---
+
+# Concept: Experience
+
+An `Experience` represents an episodic record of what happened during an execution. It is historical evidence, not a consolidated rule.
+
+## Required Frontmatter Fields
+
+- `type`: Must be `"Experience"`
+- `id`: Unique identifier (e.g. `exp-2026-09-02-01`)
+- `title`: Short descriptive title of what was attempted
+- `timestamp`: ISO-8601 timestamp
+- `status`: Execution outcome (`"success"`, `"failure"`, `"partial"`, `"observation"`)
+
+## Optional Frontmatter Fields
+
+- `skill_used`: Link or identifier of the skill executed
+- `skill_version`: Version of the skill used
+- `task`: High-level goal or task description
+- `error_code`: Error identifier if applicable
+- `context`: Contextual notes or environment flags
+- `run`: Link to the `LoopRun` whose execution produced this Experience
+
+## Content Structure
+
+The body should describe:
+1. **Context & Intent**: What the agent wanted to achieve.
+2. **Action & Observed Output**: Concrete trace, response, or command output.
+3. **Findings**: What was surprising, what broke, or what succeeded.
+
+When the Experience emerges from a contract-guided run, `run` preserves provenance back to the operational state and evidence that produced the learning.

wisk/_assets/specs/experience.schema.sql

@@ -0,0 +1,12 @@
+CREATE TABLE "Experience" (
+    "id" VARCHAR,
+    "title" VARCHAR,
+    "timestamp" TIMESTAMPTZ,
+    "status" VARCHAR,
+    "skill_used" VARCHAR,
+    "skill_version" VARCHAR,
+    "task" VARCHAR,
+    "error_code" VARCHAR,
+    "context" VARCHAR,
+    "run" VARCHAR
+);

wisk/_assets/specs/handoff.md

@@ -0,0 +1,41 @@
+---
+type: ConceptSpecification
+concept_type: Handoff
+description: "Resumable unfinished work transferred from one LoopRun to a future LoopRun."
+---
+
+# Concept: Handoff
+
+A `Handoff` represents material work intentionally transferred between agent sessions.
+
+## Required frontmatter
+
+- `type`: `Handoff`
+- `id`: stable identifier
+- `title`: concise description of the unfinished work
+- `created_at`: ISO-8601 timestamp
+- `status`: `active` or `archived`
+- `created_by_run`: LoopRun that emitted the handoff
+- `state`: concrete state in which the work was left
+- `next_action`: natural resumption point
+- `references`: relevant PRs, issues, files, concepts, evidence or other identifiers
+
+## Goal accountability
+
+- `goals`: RunGoals from `created_by_run` whose unfinished intent this Handoff carries forward.
+
+A LoopRun may close only after every owned RunGoal reaches a terminal state. `achieved` means the run resolved that intent itself. `carried_forward` means responsibility moved to a Handoff, and the corresponding RunGoal must therefore appear in the Handoff's `goals` list. The Handoff continues to satisfy that historical provenance after it is archived by a later run.
+
+## Optional routing
+
+- `target_session_type`: SessionType that is the natural continuation owner. A compatible cadence policy may treat this active Handoff as an eligibility trigger.
+
+## Archived handoffs
+
+When a later session continues the work, the handoff is archived and records:
+
+- `continued_by_run`: LoopRun that resumed it
+- `archived_at`: ISO-8601 timestamp
+- `resolution`: what the continuing session did with the handoff
+
+Archiving is semantic rather than destructive: the document remains queryable as provenance between sessions.

wisk/_assets/specs/handoff.schema.sql

@@ -0,0 +1,15 @@
+CREATE TABLE "Handoff" (
+    "id" VARCHAR,
+    "title" VARCHAR,
+    "created_at" TIMESTAMPTZ,
+    "status" VARCHAR,
+    "created_by_run" VARCHAR,
+    "target_session_type" VARCHAR,
+    "state" VARCHAR,
+    "next_action" VARCHAR,
+    "references" VARCHAR[],
+    "goals" VARCHAR[],
+    "continued_by_run" VARCHAR,
+    "archived_at" TIMESTAMPTZ,
+    "resolution" VARCHAR
+);

wisk/_assets/specs/looprun.md

@@ -0,0 +1,71 @@
+---
+type: ConceptSpecification
+concept_type: LoopRun
+description: "Live execution instance scaffolded from a RunSpec and progressively satisfied through typed evidence and checks."
+---
+
+# Concept: LoopRun
+
+A `LoopRun` is the live state of one agent execution round.
+
+It exists before substantive work begins, starts intentionally incomplete, and accumulates typed readings, goals, decisions, evidence, checks and an outcome as the session progresses.
+
+The applicable `RunSpec` defines what a well-formed run of this class requires. The `SessionType` records what kind of session created the run and supplies its purpose, inherited nudges, and default RunSpec selection. Repeated `okf-parser` validation provides operational feedback about missing or inconsistent state.
+
+## Required Frontmatter Fields
+
+- `type`: `"LoopRun"`
+- `id`: Run identifier
+- `title`: Short summary of the run
+- `timestamp`: ISO-8601 start timestamp
+- `status`: `"scaffold"`, `"in_progress"`, or `"closed"`
+- `run_spec`: Link to the governing `RunSpec`
+- `session_type`: Link to the effective `SessionType`
+- `task`: Task or session intent
+
+## Pinned RunSpec provenance
+
+New LoopRuns freeze the complete RunSpec frontmatter that governed the run at creation time:
+
+- `run_spec_version`: authored version of the governing RunSpec;
+- `run_spec_digest`: `sha256:` digest of the canonical snapshot;
+- `run_spec_snapshot`: deterministic JSON serialization of the complete RunSpec frontmatter.
+
+`check_run()` validates a pinned run against this snapshot rather than the mutable current RunSpec. The digest and version make tampering or accidental divergence explicit. Legacy LoopRuns that predate pinning may omit these fields and continue to resolve their current `run_spec` reference as a compatibility fallback.
+
+## Progressive Frontmatter Fields
+
+These fields are expected to be populated as the run advances according to its `RunSpec`:
+
+- `readings`: Links to `RunReading`
+- `goals`: Links to `RunGoal`
+- `decisions`: Links to `RunDecision`
+- `evidence`: Links to `RunEvidence`
+- `checks`: Links to `RunCheck`
+- `outcome`: Link to `RunOutcome`
+- `skills_consulted`: Links to `AgentSkill`
+- `experiences_recorded`: Links to `Experience`
+- `proposals_generated`: Links to `SkillProposal`
+
+## Operational semantics
+
+A new run should be created from a scaffold before meaningful execution work. It is normal for that scaffold to fail completion validation initially.
+
+The agent then cycles through:
+
+```text
+validate live run
+-> inspect unsatisfied requirements
+-> perform the next useful action
+-> record typed state/evidence
+-> validate again
+```
+
+Closing is stronger than merely filling the RunSpec fields. Every RunGoal owned by the run must have a terminal destination before `RunOutcome` may close it:
+
+- `achieved`: the current run resolved the intent;
+- `carried_forward`: a Handoff created by this run explicitly lists the goal and transfers it onward.
+
+Goals left `planned`, `active`, or `advanced` keep the run incomplete. A partial outcome also requires a Handoff to exist before the close is written. Archived Handoffs remain valid provenance for the historical source run.
+
+The final run is both an auditable record of what happened and a structured handoff describing the state reached and the next natural move.

wisk/_assets/specs/looprun.schema.sql

@@ -0,0 +1,21 @@
+CREATE TABLE "LoopRun" (
+    "id" VARCHAR,
+    "title" VARCHAR,
+    "timestamp" VARCHAR,
+    "status" VARCHAR,
+    "run_spec" VARCHAR,
+    "run_spec_version" VARCHAR,
+    "run_spec_digest" VARCHAR,
+    "run_spec_snapshot" VARCHAR,
+    "session_type" VARCHAR,
+    "task" VARCHAR,
+    "readings" VARCHAR[],
+    "goals" VARCHAR[],
+    "decisions" VARCHAR[],
+    "evidence" VARCHAR[],
+    "checks" VARCHAR[],
+    "outcome" VARCHAR,
+    "skills_consulted" VARCHAR[],
+    "experiences_recorded" VARCHAR[],
+    "proposals_generated" VARCHAR[]
+);

wisk/_assets/specs/outputpolicy.md

@@ -0,0 +1,32 @@
+---
+type: ConceptSpecification
+concept_type: OutputPolicy
+description: "Maps Wisk concept families to semantic output namespaces inside the repository knowledge tree."
+---
+
+# Concept: OutputPolicy
+
+`OutputPolicy` keeps storage conventions explicit while preserving the three primary Wisk stages: `experiences/`, `wiki/`, and `skills/`.
+
+## Required Frontmatter Fields
+
+- `type`: `"OutputPolicy"`
+- `id`: Stable identifier
+- `title`: Human-readable name
+
+## Route Fields
+
+- `experience_path`
+- `run_path`
+- `handoff_path`
+- `wiki_path`
+- `skill_path`
+- `proposal_path`
+- `evaluation_path`
+- `session_type_path`
+- `run_spec_path`
+- `context_policy_path`
+- `access_policy_path`
+- `output_policy_path`
+
+Paths are relative to the knowledge bundle root. The default policy keeps all outputs beneath exactly three principal namespaces: `experiences`, `wiki`, and `skills`.

wisk/_assets/specs/outputpolicy.schema.sql

@@ -0,0 +1,17 @@
+CREATE TABLE "OutputPolicy" (
+    "id" VARCHAR,
+    "title" VARCHAR,
+    "experience_path" VARCHAR,
+    "run_path" VARCHAR,
+    "handoff_path" VARCHAR,
+    "wiki_path" VARCHAR,
+    "skill_path" VARCHAR,
+    "proposal_path" VARCHAR,
+    "evaluation_path" VARCHAR,
+    "session_type_path" VARCHAR,
+    "run_spec_path" VARCHAR,
+    "context_policy_path" VARCHAR,
+    "access_policy_path" VARCHAR,
+    "output_policy_path" VARCHAR,
+    "cadence_policy_path" VARCHAR
+);

wisk/_assets/specs/runcheck.md

@@ -0,0 +1,28 @@
+---
+type: ConceptSpecification
+concept_type: RunCheck
+description: "A verification performed during a live run, including procedure, result, and supporting evidence."
+---
+
+# Concept: RunCheck
+
+A `RunCheck` records an explicit verification of the current run state.
+
+## Required Frontmatter Fields
+
+- `type`: `"RunCheck"`
+- `id`: Check identifier
+- `run`: Link to the `LoopRun`
+- `kind`: Check category defined by the applicable `RunSpec`
+- `procedure`: Command, query, review procedure, or other verification method
+- `result`: Concise observed result
+- `status`: `"pass"`, `"fail"`, or `"inconclusive"`
+
+## Optional Frontmatter Fields
+
+- `evidence`: Link to supporting `RunEvidence`
+- `goal`: Link to the `RunGoal` being verified
+
+## Semantics
+
+Checks turn evidence into explicit verification. The generic type is domain-neutral; RunSpecs define which checks matter for a particular class of work.

wisk/_assets/specs/runcheck.schema.sql

@@ -0,0 +1,10 @@
+CREATE TABLE "RunCheck" (
+    "id" VARCHAR,
+    "run" VARCHAR,
+    "kind" VARCHAR,
+    "procedure" VARCHAR,
+    "result" VARCHAR,
+    "status" VARCHAR,
+    "evidence" VARCHAR,
+    "goal" VARCHAR
+);

wisk/_assets/specs/rundecision.md

@@ -0,0 +1,28 @@
+---
+type: ConceptSpecification
+concept_type: RunDecision
+description: "A consequential choice made during a live run, with rationale and linkage to the goal it advances."
+---
+
+# Concept: RunDecision
+
+A `RunDecision` records a meaningful choice that changes how the run proceeds.
+
+## Required Frontmatter Fields
+
+- `type`: `"RunDecision"`
+- `id`: Decision identifier
+- `run`: Link to the `LoopRun`
+- `question`: Decision point or problem being resolved
+- `decision`: Chosen direction
+- `rationale`: Why this choice is appropriate given current evidence
+
+## Optional Frontmatter Fields
+
+- `goal`: Link to the `RunGoal` advanced by the decision
+- `alternatives`: Other options materially considered
+- `evidence`: Links to supporting `RunEvidence`
+
+## Semantics
+
+The purpose is not to log every thought. Record decisions that affect architecture, scope, interpretation, prioritization, validation, or the next state of the run.