# Spore entry format

Each entry in a `*-spores.md` file is a self-contained, atomic policy record.
One trigger condition. One outcome. No prose reasoning.

---

## Schema

```yaml
---
spore: {kebab-case-identifier}
task-class: {task-class-name}
scion-model: {model-identifier}
deposited: {YYYY-MM-DD}
hook: {relative-path-to-hook} | nil
---
policy: {single declarative sentence describing the decision}
trigger: {event} · {condition}
on-match: allow | deny | escalate
on-novel: escalate to parent
```

---

## Field definitions

`spore` — unique identifier within the file. Kebab-case. Descriptive enough to
identify the decision at a glance without reading the body.

`task-class` — the task class this entry was written for. Should match the
filename stem (e.g. `annotator` in `annotator-spores.md`).

`scion-model` — the model this entry was token-budgeted for. Entries written for
Haiku-4.5 are valid for Sonnet-class scions (more capable model, easier load)
but not necessarily vice versa.

`deposited` — ISO date the entry was first written.

`hook` — relative path to the compiled cchooks Python file, if one exists for
this decision. `nil` if the decision requires scion interpretation and has no
compiled hook.

`policy` — one declarative sentence. What the scion should do. Not why. Not when.
Just what. The trigger handles when.

`trigger` — the event and condition that activates this policy. Use the format:
`{HookEvent} · {condition}`. Hook events are: `PreToolUse`, `PostToolUse`,
`UserPromptSubmit`, `Stop`, `SessionStart`, `SessionEnd`.

`on-match` — the outcome when trigger fires: `allow`, `deny`, or `escalate`.

`on-novel` — always `escalate to parent`. This is the fallback for situations
not covered by any spore entry.

---

## Token discipline

Each entry must stay under approximately 60 tokens. Count before writing.
The policy line is the most likely offender — keep it to one clause.
The trigger line should be terse: event type, one condition, nothing more.

Reasoning about *why* a policy exists belongs in the corresponding SEEDS.md
entry body, not here. If you find yourself wanting to add a comment or
explanation to a spore entry, that content goes in SEEDS.md instead.

---

## Examples

### File write guard (with hook)

```yaml
---
spore: env-file-write-guard
task-class: annotator
scion-model: haiku-4.5
deposited: 2026-03-20
hook: hooks/env-guard.py
---
policy: deny all writes to sensitive credential files
trigger: PreToolUse · tool=Write · file_path matches *.env|secrets.json|id_rsa
on-match: deny
on-novel: escalate to parent
```

### Output format enforcement (no hook)

```yaml
---
spore: annotation-output-format
task-class: annotator
scion-model: haiku-4.5
deposited: 2026-03-20
hook: nil
---
policy: write all annotation output as JSONL to stdout, one record per line
trigger: PostToolUse · tool=Write · file_path matches *.annotation
on-match: allow
on-novel: escalate to parent
```

### Bash safety guard (with hook)

```yaml
---
spore: destructive-bash-guard
task-class: annotator
scion-model: haiku-4.5
deposited: 2026-03-20
hook: hooks/bash-guard.py
---
policy: deny bash commands containing destructive patterns
trigger: PreToolUse · tool=Bash · command matches rm -rf|sudo|fdisk|format
on-match: deny
on-novel: escalate to parent
```

### Escalation trigger (no hook)

```yaml
---
spore: schema-mismatch-escalate
task-class: annotator
scion-model: haiku-4.5
deposited: 2026-03-20
hook: nil
---
policy: escalate if input schema does not match expected annotation schema
trigger: PreToolUse · tool=Read · file_path matches *.input · schema-mismatch detected
on-match: escalate
on-novel: escalate to parent
```

---

## Full spore file example

```markdown
# annotator-spores.md
# task-class: annotator
# scion-model: haiku-4.5
# token-budget: 600
# last-updated: 2026-03-20

---
spore: env-file-write-guard
task-class: annotator
scion-model: haiku-4.5
deposited: 2026-03-20
hook: hooks/env-guard.py
---
policy: deny all writes to sensitive credential files
trigger: PreToolUse · tool=Write · file_path matches *.env|secrets.json|id_rsa
on-match: deny
on-novel: escalate to parent

---
spore: annotation-output-format
task-class: annotator
scion-model: haiku-4.5
deposited: 2026-03-20
hook: nil
---
policy: write annotation output as JSONL to stdout, one record per line
trigger: PostToolUse · tool=Write · file_path matches *.annotation
on-match: allow
on-novel: escalate to parent
```