toolcraft — the durable-tool doctrine

This node owns the toolcraft rule (kernel §3.8): durable tools compound; throwaway scripts are rework. When an operation will recur across independent sessions (or has already recurred inside one), the unit of work is a durable, tested tool with a stable interface, designed so at plan time, named in tools_built on every handback, and cataloged in docs/graph/tools/ by the librarian inside the close-out spawn. Genuine one-offs and throwaway prototypes stay disposable. A task completes only under the fail-closed rule below.

Work generates capabilities, not only knowledge. A task needs an operation performed (seed a fixture, migrate a schema, probe an endpoint, regenerate a client), and an agent writes code to do it. If that code dies with the session, the next task that needs the same operation writes it again, slightly differently, with a fresh chance to get it wrong. Toolcraft is the doctrine that keeps a capability once it is worth keeping.

This node is the rule; authoring and cataloging are separate, because they happen at different times and are done by different actors:

	Who	When
the rule — what earns durability	this node; every session reads it	always
authoring — building the tested tool	docs/graph/agents/tool-smith.md	mid-task, when the recurrence is noticed
cataloging — the page in docs/graph/tools/	the librarian, inside docs/graph/protocols/canonize.md	once, at close-out

Cataloging happens inside the one canonize close-out spawn; protocol.canonize owns that rule. Canonize catalogs the tool "it produced", and the producer is the tool-smith.

What counts as a durable tool (toolcraft.durability-criteria)

Catalog a piece of real code that:

• recurs across independent sessions: an agent, expert, or skill will plausibly run it again in a future task (the trigger is recurrence, not size). Recurrence also counts inside one long session, and the third-time rule (agent.tool-smith's bar) fires on scratch code too (the scratch count below);
• has a stable interface: a named entry point, defined inputs and outputs, a documented invocation, not a copy-pasted snippet;
• is authorized by a test (§3.4): at least one test, sized by test-first.proportionate-checks, pins what it does;
• lives in the repository, committed where the project keeps its tooling, reachable by path.

What stays disposable

• a genuine one-off: needed once, no future task plausibly repeats it;
• a throwaway prototype written to learn a library or shape: the blessed carve-out of the test-first rule (§3.4); recorded, if anywhere, as an exception in grill.md §9;
• anything embedding secrets, credentials, or production/personal data;
• project-specific tooling aimed at the seed: that is harvest's agnosticism gate.

The procedure sibling — durable skills

A tool is durable code; a skill is a durable procedure: the disciplined sequence for a recurring kind of work (a migration recipe, a release choreography, a data-reset dance). Same recurrence trigger, different shape: if the recurring thing is code that runs, it is a tool; if it is the how (the ordered steps and the gate each one clears, usually composing existing protocols and tools), it is a skill. When such a procedure recurs and no core docs/graph/skills/ discipline covers it, author it as a project skill from docs/graph/templates/skill.template.md, the same way a missing role is commissioned from docs/graph/templates/agent.template.md. Its home is the graph node docs/graph/skills/<name>.md; create the projection in each harness directory the plant actually uses (.claude/skills/<name>/SKILL.md and kin) in the same pass, so the harness can load it before the next install. install.sh projects what the graph holds, so from then on the projection is maintained for you. It composes disciplines by reference. The core docs/graph/skills/ stay the fixed shared methodology; a project skill is the optional, project-specific procedure on top.

Design-time half of the rule

The doctrine cuts earlier than task end: when grill identifies a recurring operation, the plan-of-record names a durable tool (or, when the recurring thing is a procedure rather than code, a project skill) as the unit of work; the capability is designed durable, not retrofitted. Workers name every tool they build in tools_built and every recurring procedure in skills_built in their handback payload (docs/graph/templates/prompts/handback-payload.md); those fields are what the close-out brief forwards to the librarian.

Fail-closed doctrine

A task completes only when every durable tool it produced is cataloged and every procedure it repeated is crystallized into a project skill, or the close-out has explicitly recorded "no durable tool / no skill, because …" (for Tier 0/1 tasks, the session's one-line self-record in the delivery covers this; see docs/graph/protocols/canonize.md). A task that built a reusable capability (a tool, or a procedure worn in by repetition) and left it uncaptured is a silent capability leak: the next session cannot find what exists, so it rewrites it.

Scratch space is where copies pile up uncounted: each worker writes its own variant, none is promoted, and the session ends with dozens of near-duplicates. So at each delivery metrics checkpoint (protocol.deliver) or at session end, the orchestrator counts the scratch scripts by purpose; a purpose with three or more variants is a recurrence and goes to tool-smith.

Cross-project mirror: harvest folds project-agnostic tools into the seed's tool-corpus/ and project-agnostic skills into skill-corpus/, user-triggered only.