Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Deriving task conflict domains

Conflict domains fence the complete work a task describes, not only the first file an author expects to edit. Derive them before making the task runnable by walking all four path layers below, then add the semantic domains that serialize work across different paths. Declare a directory when the requirement applies to a family of files or consumers.

The four-layer walk

  1. Implementation: include the code, configuration, or documentation where the requested change is written.
  2. Authority: follow the behavior through every authority-bearing boundary. Include kernel, schema, and generated bindings when the change passes through the spawn path, launcher, broker, or Cap’n Proto contract, even when the initially named edit is elsewhere.
  3. Proof: include every proof surface required by acceptance, such as manifests, the Makefile, tools, and demos. A required smoke, fixture, generated input, or process-output assertion is part of the task’s write scope even when the implementation could compile without it.
  4. Record: include every durable record the work can require, including root-level records that path:docs cannot cover. As a capOS task-fencing rule, behavior and read-side-proof slices declare path:docs; this is independent of whether a particular slice updates status text. A roadmap stage implementation also declares path:README.md and path:docs because the mandatory documentation step in CLAUDE.md covers README pointers, docs/status.md, docs/roadmap.md, docs/repo-map.md, and proposals. Add path:REVIEW.md for a new invariant, review rule, or threat-boundary change; path:CLAUDE.md for conventions, build/test workflow, feature flags, or design principles; and path:AGENTS.md for repository lifecycle or task- authoring policy.

The path result is the union of all four layers. Re-run the walk when acceptance or the proposed design changes; a fence derived from an earlier, narrower task is not evidence that the revised task still fits.

Add semantic domain kinds

Path coverage is necessary but not sufficient. Loopyard accepts five typed domain kinds: path, resource, interface, evidence, and docs. path: domains overlap by ancestor and descendant. The other kinds retain their prefix and overlap by exact match, so they serialize tasks that share a conceptual surface even when their file sets do not overlap.

After the four-layer path walk, a non-trivial repository task declares at least one resource: domain for its primary subsystem or workflow. Use an established domain name from adjacent task records rather than inventing a task-unique name that cannot overlap. Then map the authority, proof, and record layers to any additional exact-match domains:

  • resource: for a shared subsystem or operational resource;
  • interface: for a shared interface or contract;
  • evidence: for a shared proof or evidence lane; and
  • docs: for a shared documentation authority or topic.

Do not treat a complete path list as an empty declaration for semantic kinds: omitting an applicable exact-match domain permits conceptually conflicting work to run concurrently. A deliberately empty semantic set requires affirmative evidence that no shared subsystem, contract, proof lane, or documentation authority exists.

Choose family scope, not example scope

Naming the one file mentioned by acceptance is precision by example, not a complete scope declaration. When a change alters what a class of consumers needs, list the family and declare its directory. Inspect the family rather than guessing its membership from memory.

The failures that motivated this rule included:

  • one declared crate in a seven-crate demos/task-coordinator-* subsystem;
  • one declared manifest in a nineteen-manifest manifests/system-posix-* family; and
  • two declared documentation files when twenty-five documents cited the renamed Make target.

Each declaration matched an example in its task, but none covered the class of consumers the requested change actually affected. The counts describe the observed failures; current family membership must still be listed when filing a new task.

Bias toward safe overlap

A fence that is too narrow can invalidate a completed implementation candidate after the worker has spent the full run. A conservatively overlapping fence only serializes work that might have been parallel. When evidence does not support a narrower boundary, prefer the wider declaration and refine it only after inspecting the implementation, authority, proof, and record paths.

Why this is a focused authority

This page is the sole authority for the derivation rule. The mandatory AGENTS.md and CLAUDE.md entrypoints share a no-growth aggregate budget, and the repository agent harness has separate 1,800-token soft and 2,400-token hard limits. Keeping the evidence and four-layer procedure here preserves those entrypoints as compact routing documents; task-authoring guidance links here instead of duplicating the rule.