singular-particular-space/skills/commissioning-skill/seeds-entry-format.md

# SEEDS.md entry format

SEEDS.md lives at the module root and serves two purposes simultaneously:
a routing index for the commissioning skill, and a provenance log for the
parent agent. Each entry corresponds to one spore file.

---

## File header

```markdown
# SEEDS.md
# module: {module-name}
# maintained-by: parent agent
# last-updated: {YYYY-MM-DD}

---
```

---

## Entry schema

```yaml
---
task-class: {task-class-name}
spore-file: spores/{task-class}-spores.md
status: active | provisional | superseded
deposited: {YYYY-MM-DD}
supersedes: {path-to-old-spore-file} | null
---

## Context

[1-3 sentences. What situation generated this decision class. What the module
was doing when this task class was first encountered. Why a spore file was
needed rather than relying on the scion's base reasoning.]

## Reasoning

[The parent's full reasoning. Why each policy in the spore file was chosen.
What edge cases were considered. What alternatives were rejected and why.
Write for a frontier model reading this months later with no conversation
context. This section has no token constraint — optimize for completeness.]

## Revision triggers

[Bullet list of conditions that would make this entry stale or require
a new spore file to be composed:]
- {Condition 1}
- {Condition 2}
```

---

## Status definitions

`active` — the spore file has been used by at least one scion run without
unexpected escalation on covered decisions. Treat as current.

`provisional` — newly composed, not yet validated in production. The commissioning
skill should flag after first scion run. Promote to `active` if the scion
completed its task without escalating on covered decisions. If unexpected
escalations occurred, update the spore file and seed entry before promoting.

`superseded` — this entry has been replaced by a newer one. The `supersedes`
field in the newer entry points to the old spore file path. Retain superseded
entries for audit — do not delete. Skip during routing.

---

## Routing rules for the commissioning skill

The commissioning skill scans frontmatter only on first pass. The scan should:

1. Filter by `task-class` matching the current task
2. Filter by `status` not equal to `superseded`
3. If a match is found, read `spore-file` to get the path
4. Read the entry body only if the parent needs to review or revise the policy

The body is for deliberate review, not for automated routing. Do not load
entry bodies into the routing scan — they are for the parent, not the pipeline.

---

## Full SEEDS.md example

```markdown
# SEEDS.md
# module: data-pipeline
# maintained-by: parent agent
# last-updated: 2026-03-20

---
task-class: annotator
spore-file: spores/annotator-spores.md
status: active
deposited: 2026-03-20
supersedes: null
---

## Context

The data-pipeline module processes raw input files and produces annotated JSONL
output. Annotator scions handle the core transformation. The first annotator
scion run encountered a write attempt to a .env file and an ambiguous output
format question — both were resolved and crystallized as spore entries.

## Reasoning

Credential file protection: the annotator task class has no legitimate reason
to write to .env or secrets files. The decision to deny unconditionally (rather
than escalate) was made because even a legitimate-seeming reason from a Haiku-class
scion is not sufficient justification for credential file access — escalate for
that. A hook was generated because the condition is fully deterministic.

Output format: JSONL was chosen over JSON array because annotator runs are
long-running and JSONL allows streaming consumption by downstream validators
without waiting for run completion. This is a module convention, not a general
principle — other modules may differ.

Bash guard: the annotator task class requires read and write access but never
needs to execute shell commands. The deny-all-bash policy was chosen over a
more permissive pattern because any bash requirement from an annotator scion
is unexpected and warrants parent review.

## Revision triggers

- If the module adds a legitimate use case for bash execution in annotation
- If the output format changes from JSONL to another format
- If credential file patterns change (new file types added to the project)
- If annotator task class is split into sub-classes with different permission needs

---
task-class: validator
spore-file: spores/validator-spores.md
status: provisional
deposited: 2026-03-20
supersedes: null
---

## Context

Validator scions check annotator output against a schema. First commissioned
2026-03-20. Not yet run in production — status provisional pending first run.

## Reasoning

Read-only access: validators should not write to source files. The deny-write
policy covers all paths except the validator's own output directory. This is
conservative — if a legitimate write need emerges, the scion will escalate and
the policy can be revised.

Schema mismatch escalation: rather than having the validator silently fail or
produce empty output on schema mismatch, escalation was chosen so the parent
can decide whether the schema has drifted or the annotation has an error.

## Revision triggers

- After first production run — review escalation rate; if too high, the
  schema-mismatch trigger may be too sensitive
- If validator gains write permissions to a specific output path
```