git:20260924.bfc7d63 to git:20260924.fae0414

# Working on the CYPRESS seed (this repo)

This repository IS the seed — not a grown plant. `core/AGENTS.md` here is

the product shipped to target projects, not this repo's instructions.

There is no `docs/graph/` here; these notes replace it.

## Gates (run before claiming anything works)

```

bash tests/run.sh # the full gate. The roster is deliberately not

# restated here: it drifted twice during one session

# of editing it, which is what a count in prose does.

# Ask the thing that derives it:

# python3 tools/gate-registry.py --summary

# for how many gates there are and what each READS,

# --table for the false green each can still produce.

```

A count in prose is a fact with two homes. Where one is unavoidable, derive it:

`tools/gate-registry.py` parses `tests/run.sh` and refuses a step nobody has

classified — which is also what keeps the gate honest about the gates that read

only `tests/fixtures/`, and therefore prove a linter works while saying nothing

about the tree the seed ships. `--summary` prints how many that currently is.

`tests/seed-lint.py` is one-home-per-fact for the seed's own meta-facts:

roster/frontmatter/manifest/README consistency, the delegator invariant,

numeric claims, the kernel size budget (8 000 bytes), stable §3.1–§3.8

anchors, machinery-node frontmatter (every protocol/skill/agent/method

file is a graph node: id, kind, origin: seed, owns, load_when,

est_tokens, prevents; owns globally unique; the eight `rule.*` keys in

exactly their mapped homes), canonical-block byte-identity in the brief

templates, and the per-session instruction budget of the integrations.

## Release (GitHub, tag-triggered)

`tools/prepare-release.py` is seed-only — absent from `manifest.json`'s

`tools` map, so it never ships to a plant. It stages

`.github/RELEASE_NOTES.md` from the `CHANGELOG.md` entry for the current

`manifest.json` version, taken verbatim rather than re-drafted: the entry

already passed canonize's `skills/humanizer` prose pass, so re-authoring it

here would be a second home for the same release, in the same voice, for

the same reader. The staged file is `skill-corpus/discardme.md`-shaped

scaffolding — produced this session, consumed by the pipeline below,

superseded (not explicitly deleted) the next time the script runs for the

following version, since a same-turn cleanup commit back to the default

branch would race whatever lands on it next for no benefit a release reader

gets.

Flow, once the version bump and its `CHANGELOG.md` entry are committed:

1. `python3 tools/prepare-release.py` — writes `.github/RELEASE_NOTES.md`

and prints the exact commands for the next step.

2. `bash tests/run.sh` green, then commit the staged file with the rest of

the change.

3. `git tag -a vX.Y.Z -m vX.Y.Z && git push && git push origin vX.Y.Z` —

pushing the tag is a publish and needs the same explicit go-ahead as any

other push (`core/method/vcs-posture.md`'s `vcs-posture.publish-authorization`).

`.github/workflows/release.yml` triggers on that `vX.Y.Z` tag push, checks

it against `manifest.json`, and runs `gh release create` with the staged

file as the body, unedited. It writes no prose of its own: CI has no access

to the judgment `skills/humanizer` and `skill-corpus/discardme.md` both

require. `tests/seed-lint.py`'s `check_release_workflow` holds the

workflow's shape; `tests/test_prepare_release.py` holds the script's

extraction and CLI behavior.

## Canonical homes (edit the home, never a copy)

- The seed IS a graph (6.0.0): every protocol, skill, agent, and

`core/method/` file is a routable node installed into a plant's

`docs/graph/{protocols,skills,agents,method}/`; the kernel is a

bootstrap of anchors and pointers.

- Each of the eight rules → its owning node's `rule.*` fact

(3.1 specify, 3.2 context-router, 3.3 grill, 3.4 test-first,

3.5 verify, 3.6 deliver, 3.7 canonize, 3.8 toolcraft); the kernel

keeps only the one-line §3.x anchors.

- Tier depth → `core/method/tiers.md`; roster/routing/brief depth →

`core/method/delegation.md`; engineering/design/stewardship posture →

`core/method/{engineering,design,stewardship}-posture.md`

(`core/operating-principles.md` is a tombstone).

- Graph-session discipline → `templates/prompts/graph-session-bootstrap.md`

(brief templates embed it byte-identical; lint enforces sync).

- Handback contract → `templates/prompts/handback-payload.md`

(agent files carry a 3-sentence pointer, never the full spec).

- Close-out flow → `protocols/canonize.md` (single librarian spawn;

`skills/toolcraft/` owns only the durable-tool doctrine — `agent.tool-smith` builds, `canonize` catalogs).

- Failure discipline → `protocols/recover.md` (classify, one move per

class, three attempts, escalate).

- The seed's own specs → `docs/specs/`. Kernel §3.1 says code without a spec is

in remediation mode, and the seed had none of its own. Two exist, covering the

two surfaces where the seed writes into somebody else's repository or makes a

quantitative claim about itself: `SPEC-0001-install-placement` (what

`install.sh` may do to a target) and

`SPEC-0002-routing-contract` (what `--route` and `--eval` may claim). Both

name their contracts in words rather than by letter-number label; read §4 of

each, and `seed-lint`'s `check_spec_test_mapping` for which test holds which.

A third, `SPEC-0003-per-prompt-injection` (what the per-prompt hooks inject,

and the session ledger the Claude Code hook writes into a plant), is

`active`: forward-written for the 7.28.0 context-residency increment, and

promoted in the commit that landed its RED cases.

**Recorded exemption — the corpora are deliberately unspecced.** A

`library-corpus/`, `legal-corpus/` or `tool-corpus/` page is transcribed

knowledge, not behavior: its contract is its `_schema.md` plus

`legal-lint.py` / the page-shape checks, and a §4 Given/When/Then over a

statute would restate the statute. The exemption is bounded to the corpora and

does not extend to any code path. A third spec is owed the moment a new

surface starts writing into a plant or reporting a number about itself.

- Spec shape and contract coverage → `templates/knowledge-graph/spec-lint.py`

(tested by `tests/test-spec-lint.sh`); plan-of-record shape →

`templates/knowledge-graph/grill-lint.py` (tested by

`tests/test-grill-lint.sh`).

- Front-door word definitions → `DOCUMENTATION.md` §15, the glossary (one

anchored entry per term; README, the manual and the references link an

entry, never restate it). What each mechanism holds and misses, with its

ADR-0003 class → `DOCUMENTATION.md` §17, the enforcement section (one row per

mechanism kind; a front-door claim of enforcement links its row).

`SPEC-0004-front-door` holds both through `tests/seed-lint.py`.

- Spawn order of a pass → its protocol's phase table (`grill.flow`,

`specify.flow`, `test-first.cycle`, `ingest-library.flow`,

`from-scratch.phases`); the generic sequencing rule →

`core/method/delegation.md` (`delegation.sequencing`). Skills, agents,

and the orchestrator point, never re-list.

- Source ranking, retrieval steps, conflict rule → `skills/research-and-ingest`;

page-section discipline → `skills/library-wiki`; the scout charter points.

- The spec's `active` moment → `verify.status-evidence` (promotion lands

with the RED); specify, spec-author, and the template point at it.

- Roster ground truth → `agents/*.md` frontmatter (manifest, kernel

roster line, and the agents reference follow it; lint checks). Why a component is on

the roster → the node's own `prevents:` (the failure its absence

produces), never a summary page; `tools/roster-justification.py`

derives the table and prints evidence-of-use and class as absent

rather than guessing them ([ADR-0008](docs/decisions/adr-0008-roster-justification-lives-in-the-node.md)).

- Unknown-row disclosure → `tools/growth-audit.py` (`SILENT`): every

UNKNOWN row is named in the plant's `changelog.md` entry and put to the

owner as a numbered decision; grow's delivery and graft's Phase 8 point.

Raw-snapshot provenance → the `raw:` line of a normalized source

(`skills/research-and-ingest`).

## Conventions

- Behavior change ⇒ bump `manifest.json` version + `CHANGELOG.md` entry

(append-only; supersede, don't rewrite).

- The kernel is loaded on every session of every plant: additions there

need to earn ~2k-token-per-session rent, and lint fails past budget.

Depth belongs in a machinery node, never the kernel.

- Append-only artifacts: CHANGELOG.md, docs/decisions/. Everything else:

integrate, don't bolt on.

- The one exception ([ADR-0011](docs/decisions/adr-0011-donor-token-redaction.md)):

a token that identifies a project the seed was harvested from may be

replaced in an append-only record, by owner decision only, never in an

the one fixed placeholder `[redacted]`, and no sentence is reworded or

deleted; (b) the release's CHANGELOG entry names each edited record and

the class of token removed, never the token, and says the original text

remains at the prior tag and in history, that history was not rewritten,

and that published tags and Releases keep it; (c) the same statement is

a dated line in each edited plan's or spec's changelog; (d) no

force-push and no tag move.

- `harvest`/`graft` are user-sovereign; nothing in the seed may trigger

them automatically.