refactor(pipeline): specs/plans are gitignored working files, never committed
Per-cycle specs and plans stop being git-tracked commit-then-git-rm artefacts and become git-ignored working files: created on disk for the active cycle, read across sessions from the working tree, and shell-rm'd at cycle close by audit. Nothing is committed, so there is no git-history copy — the durable record of a cycle's intent is the design ledger only, and no durable artefact (code, test, doc, ledger) may cite a spec/plan by number or path. - conventions/pipeline/design/README: invert the git-tracked -> git-rm -> git-history-recovery model to gitignored -> shell-rm -> ledger-only. - naming: drop the NNNN file counter; files are slug.md (fieldtest specs keep a fieldtest- prefix as the cycle-close discriminator). - cycle number: separated from the (now-gone) file number, sourced from the feat(NNNN)/audit(NNNN) commit subjects, which cycle commits carry. - specify/planner/fieldtest/fieldtester: no commit step; fieldtest splits fixtures (committed as code) from its spec (gitignored), with the cross-cycle rule that a fieldtest- spec belongs to the next cycle. - boss: auto-sign auditability moves from the (boss-signed) commit subject to the run's reference issue; rollback reverts only code. - audit: new Step 5 shell-rm's the cycle spec+plan after the architect reads them, sparing fieldtest- specs. Companion machine config (outside this repo): the global git excludes (~/.config/git/ignore) gains docs/specs/ and docs/plans/ so the ignore applies to every project at once.
This commit is contained in:
@@ -111,11 +111,13 @@ This repo (the **plugin**) carries everything that is universal:
|
|||||||
The constants that used to be configurable but were the same in
|
The constants that used to be configurable but were the same in
|
||||||
every project are now **fixed conventions** — named directly in the
|
every project are now **fixed conventions** — named directly in the
|
||||||
skills and documented once in `docs/conventions.md`: spec dir
|
skills and documented once in `docs/conventions.md`: spec dir
|
||||||
`docs/specs`, plan dir `docs/plans`, 4-digit per-directory naming,
|
`docs/specs`, plan dir `docs/plans`, slug-only `slug.md` naming,
|
||||||
the vocabulary above, standing reading (`CLAUDE.md` + `git log -10`),
|
the vocabulary above, standing reading (`CLAUDE.md` + `git log -10`),
|
||||||
git discipline, Gitea + `closes #N`, and the whole pipeline graph.
|
git discipline, Gitea + `closes #N`, and the whole pipeline graph.
|
||||||
Specs and plans are ephemeral — git-tracked, held only for the active
|
Specs and plans are ephemeral — git-ignored, held only for the active
|
||||||
cycle, then `git rm`'d at cycle close; git history keeps the record
|
cycle, then shell-`rm`'d at cycle close (never committed, so there is
|
||||||
|
nothing to `git rm` and no git-history copy); the design ledger is the
|
||||||
|
durable record and no durable artefact cites a spec/plan
|
||||||
(`docs/conventions.md` § Lifecycle).
|
(`docs/conventions.md` § Lifecycle).
|
||||||
|
|
||||||
The handful of facts that genuinely vary per project live in the
|
The handful of facts that genuinely vary per project live in the
|
||||||
@@ -141,7 +143,8 @@ spec boundaries unattended. (Outside `/boss` the user signs every spec
|
|||||||
directly.) The autonomous signature is the **`grounding-check` `PASS`**:
|
directly.) The autonomous signature is the **`grounding-check` `PASS`**:
|
||||||
an independent fresh-context agent's verdict against currently-green
|
an independent fresh-context agent's verdict against currently-green
|
||||||
tests, not the orchestrator's confidence. On `PASS` the orchestrator
|
tests, not the orchestrator's confidence. On `PASS` the orchestrator
|
||||||
commits the spec (`(boss-signed)` in the subject), sends a mandatory
|
keeps the signed spec as a git-ignored working file (never committed) and
|
||||||
|
records the sign on the run's reference issue, sends a mandatory
|
||||||
informational notify that names the signed capability and invites a
|
informational notify that names the signed capability and invites a
|
||||||
veto, and continues to `planner` without stopping. A no-override
|
veto, and continues to `planner` without stopping. A no-override
|
||||||
grounding `BLOCK` / `INFRA_ERROR` routes to the human sign-off pause.
|
grounding `BLOCK` / `INFRA_ERROR` routes to the human sign-off pause.
|
||||||
|
|||||||
+26
-1
@@ -51,7 +51,9 @@ For cycle <X>: read the project's design ledger, if it has one
|
|||||||
(its CLAUDE.md project facts), walk its contracts;
|
(its CLAUDE.md project facts), walk its contracts;
|
||||||
`git log <prev-close>..HEAD --format=full` for the cycle's
|
`git log <prev-close>..HEAD --format=full` for the cycle's
|
||||||
iter and audit commit bodies; `git diff <prev-close>..HEAD`
|
iter and audit commit bodies; `git diff <prev-close>..HEAD`
|
||||||
for the diff; report drift.
|
for the diff; read the cycle's spec at `docs/specs/<slug>.md`
|
||||||
|
if one exists (a git-ignored working file — read it from disk,
|
||||||
|
not git); report drift.
|
||||||
```
|
```
|
||||||
|
|
||||||
Architect produces a prioritised drift list (see
|
Architect produces a prioritised drift list (see
|
||||||
@@ -120,6 +122,29 @@ The orchestrator picks per item:
|
|||||||
Red Flags, "about to return clean without having read the diff in
|
Red Flags, "about to return clean without having read the diff in
|
||||||
full"; the gate verifies it rather than trusting the status.)
|
full"; the gate verifies it rather than trusting the status.)
|
||||||
|
|
||||||
|
### Step 5 — Discard the cycle's spec and plan
|
||||||
|
|
||||||
|
Once the cycle is drift-clean (or the drift is ratified) and the
|
||||||
|
architect has read the spec, the cycle's spec and plan have served their
|
||||||
|
purpose. Discard them from the working tree with a plain shell `rm`:
|
||||||
|
|
||||||
|
```
|
||||||
|
rm -f docs/specs/<slug>.md docs/plans/<slug>.md
|
||||||
|
```
|
||||||
|
|
||||||
|
This is a shell delete, NOT `git rm` — the files are git-ignored and were
|
||||||
|
never committed, so nothing is staged and the audit-close commit carries
|
||||||
|
only code and ledger changes. **Ordering is load-bearing:** the
|
||||||
|
architect's read (Step 1) must precede this delete, because a git-ignored
|
||||||
|
spec has no `git show` recovery once it is gone.
|
||||||
|
|
||||||
|
**Spare any `fieldtest-`-prefixed spec.** A `fieldtest-<slug>.md` under
|
||||||
|
`docs/specs` belongs to the *next* cycle (it is the input to its
|
||||||
|
`planner`), so it is not this cycle's to discard — leave it for the next
|
||||||
|
cycle's close. If this cycle is itself a milestone close with no
|
||||||
|
following `planner`, discard the fieldtest spec too (see
|
||||||
|
`../fieldtest/SKILL.md`).
|
||||||
|
|
||||||
## Handoff Contract
|
## Handoff Contract
|
||||||
|
|
||||||
`audit` hands to the orchestrator:
|
`audit` hands to the orchestrator:
|
||||||
|
|||||||
+19
-13
@@ -538,10 +538,13 @@ pause. The boss-side contract is just this:
|
|||||||
verifies. Editorial roughness the old panel would have caught is let
|
verifies. Editorial roughness the old panel would have caught is let
|
||||||
through deliberately — cheap to patch inline downstream, never worth an
|
through deliberately — cheap to patch inline downstream, never worth an
|
||||||
obligatory five-juror panel on every spec.
|
obligatory five-juror panel on every spec.
|
||||||
- **On a clean sign, do not stop.** Commit the spec (the auto-sign
|
- **On a clean sign, do not stop.** The spec is never committed — it is
|
||||||
commit subject carries `(boss-signed)` so the act is auditable in
|
a git-ignored working file, signed by the `grounding-check` PASS.
|
||||||
history), fire the auto-sign notify, and continue to `planner` in
|
Make the sign auditable on the run's **reference issue** (a
|
||||||
the same run. The notify is informational-with-veto, not a pause.
|
decision-log comment recording that the spec was auto-signed on a
|
||||||
|
PASS with no human), fire the auto-sign notify, and continue to
|
||||||
|
`planner` in the same run. The notify is informational-with-veto, not
|
||||||
|
a pause.
|
||||||
- **The notify must be vetoable.** It follows the same editorial rules
|
- **The notify must be vetoable.** It follows the same editorial rules
|
||||||
as a done-state notify (English, user-as-reader, no iteration codes
|
as a done-state notify (English, user-as-reader, no iteration codes
|
||||||
or crate names) with one addition forced by its purpose: it must
|
or crate names) with one addition forced by its purpose: it must
|
||||||
@@ -552,15 +555,18 @@ pause. The boss-side contract is just this:
|
|||||||
capability> myself and started the implementation plan — reply to
|
capability> myself and started the implementation plan — reply to
|
||||||
veto." No internals, but enough identity to act on.
|
veto." No internals, but enough identity to act on.
|
||||||
- **A veto is a forward correction — or, within the run, a rollback.**
|
- **A veto is a forward correction — or, within the run, a rollback.**
|
||||||
If the user vetoes a spec already committed below the session anchor
|
The spec is never a commit (it is a git-ignored working file), so a
|
||||||
(ratified history), undo it forward
|
veto is undone forward by shell-`rm`ing (or editing) the spec and
|
||||||
— revert the spec commit, discard the downstream working-tree work with
|
reverting only the downstream **code** it produced: `git revert` the
|
||||||
`git checkout`, file the redirection. *Within* the autonomous run, the
|
code commits below the session anchor (ratified history), or
|
||||||
rollback sandbox (§ Direction freedom) is the additional remedy: the
|
`git checkout` the unstaged work, and file the redirection. *Within*
|
||||||
orchestrator may hard-reset its own unpushed `(boss-signed)` commit and
|
the autonomous run, the rollback sandbox (§ Direction freedom) is the
|
||||||
the work built on it back toward the session anchor when it judges the
|
additional remedy: the orchestrator may hard-reset its own unpushed
|
||||||
fork was wrong — its own work only, never below the anchor, never a
|
autonomous **code** commits and the work built on them back toward the
|
||||||
pushed commit.
|
session anchor when it judges the fork was wrong — its own work only,
|
||||||
|
never below the anchor, never a pushed commit — and shell-`rm`s the
|
||||||
|
git-ignored spec/plan of the abandoned line. The reference-issue thread
|
||||||
|
is the only surviving trace of the abandoned attempt.
|
||||||
|
|
||||||
## Skill-system feedback
|
## Skill-system feedback
|
||||||
|
|
||||||
|
|||||||
+49
-24
@@ -27,6 +27,15 @@ These directories are fixed. A project that keeps specs and plans
|
|||||||
elsewhere is the rare exception and states the override in its
|
elsewhere is the rare exception and states the override in its
|
||||||
`CLAUDE.md` project facts.
|
`CLAUDE.md` project facts.
|
||||||
|
|
||||||
|
Both directories are **git-ignored** — their contents are transient
|
||||||
|
working files, never committed (see § Lifecycle). The plugin ignores
|
||||||
|
them **globally**: `docs/specs/` and `docs/plans/` live in the user's
|
||||||
|
global git excludes (`~/.config/git/ignore`, the XDG default that
|
||||||
|
applies to every repo), next to the other plugin-wide ignores. One
|
||||||
|
entry set covers every project — no per-project `.gitignore` line is
|
||||||
|
needed, though a project MAY add its own if it wants the ignore to
|
||||||
|
travel with the repo.
|
||||||
|
|
||||||
## Lifecycle
|
## Lifecycle
|
||||||
|
|
||||||
`docs/specs/` and `docs/plans/` hold **only the active cycle's
|
`docs/specs/` and `docs/plans/` hold **only the active cycle's
|
||||||
@@ -35,35 +44,51 @@ valid for the cycle that produces it; its code shapes drift the moment
|
|||||||
the code moves, so a stale one left lying around reads as a live API
|
the code moves, so a stale one left lying around reads as a live API
|
||||||
reference and misleads the next agent that opens it.
|
reference and misleads the next agent that opens it.
|
||||||
|
|
||||||
The two directories stay **git-tracked** — never git-ignored. A
|
The two directories are **git-ignored** — their contents are never
|
||||||
spec/plan is committed while its cycle is live, and at **cycle close** —
|
committed. A spec/plan is a working file: present on disk while its
|
||||||
after `audit` is drift-clean — the orchestrator **retires** it: `git rm`
|
cycle is live (readable across sessions, since the working tree
|
||||||
the spec and plan in the cycle-close commit. The deletion rides in that
|
persists), and at **cycle close** — after `audit` is drift-clean — the
|
||||||
commit, so at `HEAD` the directories hold only what is still in flight,
|
orchestrator **discards** it with a plain shell `rm`. There is nothing
|
||||||
while the full text stays recoverable from git history
|
to `git rm` (it was never tracked) and no deletion commit is produced;
|
||||||
(`git show <rev>:<path>`).
|
the working tree is simply left without a stale artefact. This is the
|
||||||
|
same shell-delete-an-uncommitted-file mechanic `specify` already uses on
|
||||||
|
its grounding-`BLOCK` failure path.
|
||||||
|
|
||||||
A spec/plan is therefore **transient in the repo**: present for its own
|
A spec/plan is therefore **transient on disk**: present for its own
|
||||||
cycle, gone from `HEAD` afterwards. The durable record of a past cycle
|
cycle, `rm`'d afterwards, and — never having been committed — leaving no
|
||||||
is the design ledger (where the rationale is lifted during audit) + the
|
trace in git. It is **not recoverable, by design**. The durable record
|
||||||
git history of the spec, plan, and code — never a live file under
|
of a past cycle's design intent is the **design ledger only** (where the
|
||||||
`docs/specs` / `docs/plans`.
|
rationale is lifted during audit); the implementation is committed as
|
||||||
|
normal code.
|
||||||
|
|
||||||
|
**No durable artefact may cite a spec or plan** — not by number, not by
|
||||||
|
path. Code, tests, docs, and ledger entries outlive the spec/plan that
|
||||||
|
prompted them, so any reference to `docs/specs/…` or "spec NNNN" would
|
||||||
|
dangle the moment the cycle closes. Cite the **design-ledger contract**
|
||||||
|
instead (e.g. a `C`-id); it is the durable record the spec's rationale
|
||||||
|
was lifted into.
|
||||||
|
|
||||||
## Naming
|
## Naming
|
||||||
|
|
||||||
Counter-prefixed, per directory: `NNNN-slug.md`, 4-digit
|
Files are named `slug.md` — a short kebab-case identifier of the
|
||||||
zero-padded. The counter is per directory, assigned in creation
|
cycle's topic (slug separator `-`). There is **no numeric prefix**:
|
||||||
order, and stable for the life of the file. New files take the
|
because the directories are git-ignored, shell-`rm`'d at cycle close,
|
||||||
next-higher number; `brainstorm` / `specify` / `planner` scan the
|
and cited by nothing (see § Lifecycle), they hold at most the active
|
||||||
target directory for the next free number before writing.
|
cycle's handful of files, so a slug is already unique enough — the old
|
||||||
|
scan-for-the-next-free-number ritual bought nothing and is gone. A
|
||||||
|
`fieldtest`-produced spec takes a `fieldtest-` prefix
|
||||||
|
(`fieldtest-slug.md`): that prefix is the discriminator the cycle-close
|
||||||
|
sweep uses to spare it, because it belongs to the next cycle (see
|
||||||
|
`../fieldtest/SKILL.md`).
|
||||||
|
|
||||||
The number is a within-cycle handle, not a stable archival ID.
|
**The file name is not the cycle number.** The **cycle number** that
|
||||||
Because the directories hold only active artefacts (see § Lifecycle),
|
appears in commit subjects (`feat(NNNN)`, `audit(NNNN)`) and in `git
|
||||||
an emptied directory restarts at `0001` and a number freed by a
|
log` cycle ranges is a distinct, monotonic identifier that must survive
|
||||||
retired file may be reused — that recycling is fine, since the durable
|
spec/plan discard. Source it from the highest `NNNN` in the
|
||||||
record is git history, not the filename.
|
`feat(NNNN)` / `audit(NNNN)` git-log subjects, plus one — never from a
|
||||||
|
file name (there is none) and never from a per-directory scan. Cycle
|
||||||
The slug separator is `-`.
|
commits therefore MUST carry the zero-padded `(NNNN)` cycle number in
|
||||||
|
their subject.
|
||||||
|
|
||||||
## Vocabulary
|
## Vocabulary
|
||||||
|
|
||||||
|
|||||||
+7
-5
@@ -85,16 +85,18 @@ The plugin owns:
|
|||||||
The constants that used to be configurable but were the same in
|
The constants that used to be configurable but were the same in
|
||||||
every project are now plugin conventions, named directly in skill
|
every project are now plugin conventions, named directly in skill
|
||||||
and agent bodies and documented once in `conventions.md`:
|
and agent bodies and documented once in `conventions.md`:
|
||||||
spec dir `docs/specs`, plan dir `docs/plans`, 4-digit per-directory
|
spec dir `docs/specs`, plan dir `docs/plans`, slug-only `slug.md`
|
||||||
naming, the vocabulary cycle / iteration / milestone / contract,
|
naming, the vocabulary cycle / iteration / milestone / contract,
|
||||||
standing reading (`CLAUDE.md` + `git log -10`), git discipline
|
standing reading (`CLAUDE.md` + `git log -10`), git discipline
|
||||||
(only-orchestrator commits, main sacrosanct), Gitea + `closes #N`,
|
(only-orchestrator commits, main sacrosanct), Gitea + `closes #N`,
|
||||||
and the whole pipeline graph (see `pipeline.md`).
|
and the whole pipeline graph (see `pipeline.md`).
|
||||||
|
|
||||||
Specs and plans are ephemeral active-cycle artefacts — the two
|
Specs and plans are ephemeral active-cycle working files — the two
|
||||||
directories stay git-tracked and hold only what is in flight; at cycle
|
directories are git-ignored and hold only what is in flight; at cycle
|
||||||
close each is `git rm`'d from the repo, kept only in git history, never
|
close each is shell-`rm`'d (never committed, so nothing to `git rm` and
|
||||||
as a durable file (see `conventions.md` § Lifecycle).
|
no git-history copy). The durable record of a past cycle is the design
|
||||||
|
ledger only, and no durable artefact cites a spec/plan (see
|
||||||
|
`conventions.md` § Lifecycle).
|
||||||
|
|
||||||
## Project facts (project-specific)
|
## Project facts (project-specific)
|
||||||
|
|
||||||
|
|||||||
+17
-11
@@ -140,8 +140,9 @@ Hard-gate before plan — the spec-production core and the carrier of the
|
|||||||
"no plan without an approved spec" invariant. Takes a settled design
|
"no plan without an approved spec" invariant. Takes a settled design
|
||||||
(directly from sources, or a ratified design handed over by
|
(directly from sources, or a ratified design handed over by
|
||||||
`brainstorm`), applies the feature-acceptance criterion, writes the
|
`brainstorm`), applies the feature-acceptance criterion, writes the
|
||||||
spec to `docs/specs` (an ephemeral active-cycle artefact, git-tracked
|
spec to `docs/specs` (an ephemeral active-cycle working file —
|
||||||
and `git rm`'d at cycle close — see `conventions.md` § Lifecycle), runs
|
git-ignored, never committed, shell-`rm`'d at cycle close — see
|
||||||
|
`conventions.md` § Lifecycle), runs
|
||||||
the `grounding-check` gate, and takes sign-off — with review but no
|
the `grounding-check` gate, and takes sign-off — with review but no
|
||||||
interview. Under the bold stance it decides every load-bearing fork it
|
interview. Under the bold stance it decides every load-bearing fork it
|
||||||
can *derive* an answer for and records the decision in the run's
|
can *derive* an answer for and records the decision in the run's
|
||||||
@@ -152,9 +153,11 @@ gate before `planner` on every design path.
|
|||||||
Outside `/boss` the sign-off is the user's. Under `/boss` the autonomous
|
Outside `/boss` the sign-off is the user's. Under `/boss` the autonomous
|
||||||
signature is the **`grounding-check` `PASS`** itself: an independent
|
signature is the **`grounding-check` `PASS`** itself: an independent
|
||||||
fresh-context agent's verdict against currently-green tests, not the
|
fresh-context agent's verdict against currently-green tests, not the
|
||||||
orchestrator's confidence. On `PASS` the orchestrator commits the spec
|
orchestrator's confidence. On `PASS` the orchestrator keeps the signed
|
||||||
(subject `(boss-signed)`), fires the vetoable auto-sign notify, and
|
spec as a git-ignored working file (never committed), records the
|
||||||
continues to `planner`; a no-override grounding `BLOCK` / `INFRA_ERROR`
|
autonomous sign on the run's reference issue, fires the vetoable
|
||||||
|
auto-sign notify, and continues to `planner`; a no-override grounding
|
||||||
|
`BLOCK` / `INFRA_ERROR`
|
||||||
routes to the human sign-off pause. The former obligatory five-lens
|
routes to the human sign-off pause. The former obligatory five-lens
|
||||||
`spec-skeptic` panel is **retired** (baseline tag `pre-autosign-rework`):
|
`spec-skeptic` panel is **retired** (baseline tag `pre-autosign-rework`):
|
||||||
the judgement it applied now lives upstream in Step 1.5's bold-decide
|
the judgement it applied now lives upstream in Step 1.5's bold-decide
|
||||||
@@ -167,9 +170,10 @@ See `../specify/SKILL.md` Step 6 and `../boss/SKILL.md` §"Spec auto-sign".
|
|||||||
### planner
|
### planner
|
||||||
|
|
||||||
Hard-gate before implement. Produces a placeholder-free,
|
Hard-gate before implement. Produces a placeholder-free,
|
||||||
bite-sized implementation plan in `docs/plans` (ephemeral, retired
|
bite-sized implementation plan in `docs/plans` (an ephemeral,
|
||||||
alongside the spec at cycle close — see `conventions.md` § Lifecycle)
|
git-ignored working file, shell-`rm`'d alongside the spec at cycle
|
||||||
that the implement skill can execute task-by-task. Dispatches
|
close — see `conventions.md` § Lifecycle) that the implement skill can
|
||||||
|
execute task-by-task. Dispatches
|
||||||
the plan-recon agent for read-only file-structure mapping.
|
the plan-recon agent for read-only file-structure mapping.
|
||||||
|
|
||||||
### implement
|
### implement
|
||||||
@@ -209,9 +213,11 @@ review-and-commit discipline; the orchestrator inspects and commits.
|
|||||||
Runs at cycle close. Dispatches the architect agent (read-only
|
Runs at cycle close. Dispatches the architect agent (read-only
|
||||||
drift review against the design ledger) and the bencher agent
|
drift review against the design ledger) and the bencher agent
|
||||||
(regression diagnostics). Reports drift and regress. Once it is
|
(regression diagnostics). Reports drift and regress. Once it is
|
||||||
drift-clean, the orchestrator retires the cycle's spec and plan —
|
drift-clean, the orchestrator discards the cycle's spec and plan with a
|
||||||
`git rm`'ing them in the cycle-close commit (see `conventions.md`
|
plain shell `rm` (nothing to `git rm` — they were never committed),
|
||||||
§ Lifecycle).
|
sparing any `fieldtest-`-prefixed spec (it belongs to the next cycle);
|
||||||
|
the cycle-close commit contains only code and ledger changes (see
|
||||||
|
`conventions.md` § Lifecycle).
|
||||||
|
|
||||||
### debug
|
### debug
|
||||||
|
|
||||||
|
|||||||
+11
-4
@@ -120,10 +120,17 @@ Contract below. The agent picks 2-4 examples (one per axis
|
|||||||
the cycle touched; fewer loses the signal on variation, more
|
the cycle touched; fewer loses the signal on variation, more
|
||||||
overflows one readable report), implements them as downstream
|
overflows one readable report), implements them as downstream
|
||||||
consumers, runs them, classifies findings, and writes the
|
consumers, runs them, classifies findings, and writes the
|
||||||
spec. All artefacts (fixtures + spec) stay in the working tree
|
spec. The two artefact kinds part ways at commit: the **fixtures are
|
||||||
as unstaged changes; the orchestrator commits them after
|
committed as normal code** (they are consumer test assets — suggested
|
||||||
reviewing the report (suggested commit subject:
|
subject `fieldtest: <cycle> — <N> examples, <K> findings`), while the
|
||||||
`fieldtest: <cycle> — <N> examples, <K> findings`).
|
**fieldtest spec is a git-ignored working file that is never committed**.
|
||||||
|
|
||||||
|
The fieldtest spec is written at cycle N's close but is an **input to
|
||||||
|
the next cycle's `planner`**, so it belongs to cycle N+1, not N: the
|
||||||
|
cycle-close sweep spares it (its `fieldtest-` filename prefix is the
|
||||||
|
discriminator) and it is shell-`rm`'d at N+1's close alongside N+1's own
|
||||||
|
spec and plan. If the consuming cycle closes without a `planner` (e.g. a
|
||||||
|
milestone close), the orchestrator discards it explicitly.
|
||||||
|
|
||||||
## Handoff Contract
|
## Handoff Contract
|
||||||
|
|
||||||
|
|||||||
@@ -211,14 +211,15 @@ not merged.
|
|||||||
|
|
||||||
### Phase 5 — Write the spec, hand back
|
### Phase 5 — Write the spec, hand back
|
||||||
|
|
||||||
Write the fieldtest spec under `docs/specs` with a name
|
Write the fieldtest spec under `docs/specs` named
|
||||||
following the `NNNN-slug.md` convention (4-digit prefix,
|
`fieldtest-slug.md` (the `fieldtest-` prefix is mandatory — it is the
|
||||||
per-directory; see `docs/conventions.md`). Use the spec
|
discriminator that spares the spec from the cycle-close sweep; no numeric
|
||||||
template below. Leave all artefacts (the fixtures and the
|
prefix, see `docs/conventions.md` § Naming). Use the spec
|
||||||
spec file) in the working tree as unstaged changes. You do
|
template below. Leave all artefacts in the working tree as unstaged
|
||||||
NOT commit — the orchestrator commits after reading the
|
changes. You do NOT commit — the orchestrator commits the **fixtures**
|
||||||
end-report (suggested commit subject:
|
as code after reading the end-report (suggested subject
|
||||||
`fieldtest: <cycle> — <N> examples, <K> findings`).
|
`fieldtest: <cycle> — <N> examples, <K> findings`); the fieldtest
|
||||||
|
**spec** is git-ignored and is never committed.
|
||||||
|
|
||||||
Report `DONE` with the carrier (see Output format).
|
Report `DONE` with the carrier (see Output format).
|
||||||
|
|
||||||
|
|||||||
+8
-9
@@ -16,8 +16,9 @@ into bites small enough that a subagent can execute one in
|
|||||||
2-5 minutes without making judgement calls outside its remit.
|
2-5 minutes without making judgement calls outside its remit.
|
||||||
|
|
||||||
Plans live under `docs/plans` with the fixed name shape
|
Plans live under `docs/plans` with the fixed name shape
|
||||||
`NNNN-slug.md` — a 4-digit counter per directory (see
|
`slug.md` — a short kebab-case topic slug, no numeric prefix (see
|
||||||
`docs/conventions.md`). The header references the parent spec. The plan
|
`docs/conventions.md` § Naming). `docs/plans` is git-ignored; the plan
|
||||||
|
is a working file, never committed. The header references the parent spec. The plan
|
||||||
decomposes work into tasks; each task is the unit of review
|
decomposes work into tasks; each task is the unit of review
|
||||||
(spec-compliance and quality gates inside `implement`), not
|
(spec-compliance and quality gates inside `implement`), not
|
||||||
the unit of commit. Commits are an orchestrator-only decision
|
the unit of commit. Commits are an orchestrator-only decision
|
||||||
@@ -226,16 +227,14 @@ Fix issues inline.
|
|||||||
|
|
||||||
### Step 6 — Hand off
|
### Step 6 — Hand off
|
||||||
|
|
||||||
The plan sits in the working tree as an unstaged file under
|
The plan sits in the working tree as a git-ignored working file under
|
||||||
`docs/plans`. Hand off to `implement` with: path to the
|
`docs/plans`. Hand off to `implement` with: path to the
|
||||||
plan file + optional task focus ("only Tasks 1-3 this run").
|
plan file + optional task focus ("only Tasks 1-3 this run").
|
||||||
|
|
||||||
The orchestrator commits the plan when handing it forward
|
The plan is **never committed**. Like the spec, it is a git-ignored
|
||||||
(suggested commit subject: `plan: <iteration> <subject>`).
|
active-cycle working file: present on disk for its own cycle and
|
||||||
The planner skill does not perform the commit itself. Like the spec,
|
shell-`rm`'d alongside the spec at cycle close by `audit` (see
|
||||||
the plan is an ephemeral active-cycle artefact: committed for its own
|
`docs/conventions.md` § Lifecycle).
|
||||||
cycle and `git rm`'d at cycle close (see `docs/conventions.md`
|
|
||||||
§ Lifecycle).
|
|
||||||
|
|
||||||
## Handoff Contract
|
## Handoff Contract
|
||||||
|
|
||||||
|
|||||||
+32
-26
@@ -268,10 +268,10 @@ it as a target, not verified fact.
|
|||||||
|
|
||||||
### Step 3 — Write the spec
|
### Step 3 — Write the spec
|
||||||
|
|
||||||
Path: under `docs/specs`, named per the fixed naming convention —
|
Path: under `docs/specs`, named `slug.md` per the fixed naming
|
||||||
`NNNN-slug.md`, 4-digit per-directory counter (see
|
convention (see `docs/conventions.md` § Naming) — a short kebab-case
|
||||||
`docs/conventions.md`). Determine the next free number by scanning the
|
topic slug, no numeric prefix. The directory is git-ignored; the spec is
|
||||||
directory.
|
created there and never `git add`'d.
|
||||||
|
|
||||||
Structure:
|
Structure:
|
||||||
|
|
||||||
@@ -377,22 +377,23 @@ spec file; nothing slips between it and the commit.
|
|||||||
Outside `/boss` the signature is the user's; under `/boss` it is the
|
Outside `/boss` the signature is the user's; under `/boss` it is the
|
||||||
Step-5 `grounding-check` `PASS` (the `/boss` subsection below).
|
Step-5 `grounding-check` `PASS` (the `/boss` subsection below).
|
||||||
|
|
||||||
The spec sits in the working tree as an unstaged file. Tell the user:
|
The spec sits in the working tree as a git-ignored working file. Tell
|
||||||
|
the user:
|
||||||
|
|
||||||
> Spec written to `<path>` (uncommitted). Please review it and let me
|
> Spec written to `<path>` (git-ignored, never committed). Please review
|
||||||
> know if you want changes before we start the implementation plan.
|
> it and let me know if you want changes before we start the
|
||||||
> The orchestrator will commit it once you approve.
|
> implementation plan.
|
||||||
|
|
||||||
Wait for the user's response. If they request changes, edit the file
|
Wait for the user's response. If they request changes, edit the file
|
||||||
in place (still uncommitted), **re-run Step 4 AND re-dispatch Step 5**
|
in place, **re-run Step 4 AND re-dispatch Step 5**
|
||||||
(the previous PASS report no longer covers the edited bytes), then
|
(the previous PASS report no longer covers the edited bytes), then
|
||||||
return here. Only proceed after approval AND a fresh Step 5 PASS.
|
return here. Only proceed after approval AND a fresh Step 5 PASS.
|
||||||
|
|
||||||
The orchestrator commits the approved spec after sign-off (suggested
|
The spec is **never committed**: it is a git-ignored active-cycle working
|
||||||
commit subject: `spec: <cycle> <topic>`). The skill does not perform
|
file that lives on disk only for its own cycle and is shell-`rm`'d at
|
||||||
the commit itself. The spec is an ephemeral active-cycle artefact: it
|
cycle close by `audit` (see `docs/conventions.md` § Lifecycle). The
|
||||||
lives in the repo only for its own cycle and is `git rm`'d at cycle
|
durable record of its design intent is the design ledger, lifted during
|
||||||
close (see `docs/conventions.md` § Lifecycle).
|
audit — not the spec file.
|
||||||
|
|
||||||
**In `/boss` (autonomous):** `specify` is dispatched autonomously — it
|
**In `/boss` (autonomous):** `specify` is dispatched autonomously — it
|
||||||
is bounded (no interview), so there is no user at this gate to take the
|
is bounded (no interview), so there is no user at this gate to take the
|
||||||
@@ -404,11 +405,13 @@ adversarial panel**, no objective-gates-then-panel staging, no
|
|||||||
self-correction loop; those were retired in favour of decide-upstream +
|
self-correction loop; those were retired in favour of decide-upstream +
|
||||||
recover-downstream (baseline tag `pre-autosign-rework`).
|
recover-downstream (baseline tag `pre-autosign-rework`).
|
||||||
|
|
||||||
- On a Step-5 **`PASS`**: commit the spec yourself (subject `spec:
|
- On a Step-5 **`PASS`**: the spec is signed by the PASS — leave it as a
|
||||||
<cycle> <topic> (boss-signed)`), fire the auto-sign notify (see `boss`
|
git-ignored working file (never committed). Record the autonomous sign
|
||||||
§ Notifications — it names the capability in user terms and states the
|
on the run's reference issue (a decision-log comment: which capability,
|
||||||
plan is proceeding and a reply vetoes), then proceed to Step 7. No
|
that the `grounding-check` PASS was the signature, that no human
|
||||||
pause.
|
signed), fire the auto-sign notify (see `boss` § Notifications — it
|
||||||
|
names the capability in user terms and states the plan is proceeding
|
||||||
|
and a reply vetoes), then proceed to Step 7. No pause.
|
||||||
- On a Step-5 no-override **`BLOCK`** or **`INFRA_ERROR`**: there is no
|
- On a Step-5 no-override **`BLOCK`** or **`INFRA_ERROR`**: there is no
|
||||||
human to override it, so it routes to the human sign-off pause — a
|
human to override it, so it routes to the human sign-off pause — a
|
||||||
problem-state notify ("spec X needs your sign-off") — exactly as the
|
problem-state notify ("spec X needs your sign-off") — exactly as the
|
||||||
@@ -435,13 +438,16 @@ leaning. This is a *tool it reaches for*, not a gate it must clear: the
|
|||||||
lens returns a finding, the orchestrator decides. Carrier and lenses are
|
lens returns a finding, the orchestrator decides. Carrier and lenses are
|
||||||
defined in `agents/spec-skeptic.md`.
|
defined in `agents/spec-skeptic.md`.
|
||||||
|
|
||||||
**Auto-sign commits on `main` are forward-only — with one `/boss`
|
**Auto-signed CODE commits on `main` are forward-only — with one `/boss`
|
||||||
exception.** A later user veto is normally a forward correction (revert /
|
exception.** The spec itself is never a commit (it is a git-ignored
|
||||||
revised spec / `git checkout` of downstream work). The `/boss` rollback
|
working file), so a later user veto is a forward correction: shell-`rm`
|
||||||
sandbox is the exception: within an autonomous run the orchestrator may
|
(or edit) the git-ignored spec, and `git revert` / `git checkout` only
|
||||||
hard-reset its own *unpushed* autonomous commits back toward (never
|
the downstream **code** it produced. The `/boss` rollback sandbox is the
|
||||||
below) the session anchor when it has run into a dead end — its own work
|
exception: within an autonomous run the orchestrator may hard-reset its
|
||||||
only. See `boss` § Direction freedom for the exact boundary.
|
own *unpushed* autonomous code commits back toward (never below) the
|
||||||
|
session anchor when it has run into a dead end — its own work only, and
|
||||||
|
it shell-`rm`s the git-ignored spec/plan of the abandoned line. See
|
||||||
|
`boss` § Direction freedom for the exact boundary.
|
||||||
|
|
||||||
### Step 7 — Hand off to `planner`
|
### Step 7 — Hand off to `planner`
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user