AGENTS.md: delegating work — task first, fork second; the rule that survives compaction

The cheat-sheet listed Fork first (with "balanced … default: exploration/
impl/test") and Task as the exception, and it lost to the fork tool's
self-recommending description every time it mattered (five of five fork
briefs in one 2026-09-17 session carried "do not"). This file is the one
copy of the rule in the SYSTEM PROMPT — the skill is gone after the first
compaction — so it now carries: the one discriminator (what the child
sees), task as the default for anything that writes or must obey a rule,
fork only for read-only exploration against this conversation or parallel
opinions, a three-question pre-flight before any fork(...), a copy-paste
minimal task(...) call with the roots contract (write_allowed ⊆ roots, never
nested in a watched root), and a note that fork-gate now enforces the split.

README: pi-task is now also the `task` tool (pi-extensions task.ts) with
fork-gate alongside; where the wrapper looks for this script.
This commit is contained in:
2026-09-19 16:42:03 +02:00
parent adfb553f5c
commit 9c87ee843f
2 changed files with 62 additions and 19 deletions
+15
View File
@@ -92,6 +92,21 @@ wait out.
./bin/pi-task run examples/task-*.json # exit 0 = PASS, 1 = FAIL
```
**As a tool, not just a CLI (2026-09-19).** `pi-extensions/extensions/task.ts`
registers this runner as the `task` tool, and `fork-gate.ts` blocks a `fork`
whose brief carries a prohibition, a write boundary or a file-changing
imperative, handing back the `task(...)` call to make instead. Reason: the
correct prose rule ("pi-task for briefs with prohibitions") lost to the tool
list for months — `fork` was a tool with a self-recommending description, this
was a CLI to be remembered — and the skill that carried the rule is gone after
the first compaction. The tool wrapper also rejects, before spending a model
run, the two spec errors that make a violation certain (`write_allowed` not an
exact subset of `roots`; a writable root nested in a watched-only root), and
serialises tasks whose roots overlap. The wrapper looks for this script at
`$PI_TASK_BIN`, `/opt/pi-toolkit/bin/pi-task`, `~/src/pi-toolkit/bin/pi-task`,
`~/src/src_local/pi-toolkit/bin/pi-task`, `/workspace/pi-toolkit/bin/pi-task`,
then `$PATH`.
`selftest` is not decoration: it feeds the validator one known-good and six
known-bad envelopes plus a two-sided boundary check, and **aborts** if any pair
fails to discriminate. A validator that has only ever returned PASS has not been