mirror of
https://github.com/EveryInc/compound-engineering-plugin.git
synced 2026-06-19 15:41:46 +02:00
refactor(plan): remove the plan status field; completion derives from git
Plans no longer carry a status field, and ce-work no longer flips active -> completed at ship time. A plan is a point-in-time decision artifact; whether it shipped is derived from git, not stored in the doc -- consistent with how per-unit progress is already derived rather than written. Removes the field and lifecycle from ce-plan (SKILL.md resume gate, plan-sections.md), the ship-time flip from ce-work and ce-work-beta (SKILL.md, shipping-workflow.md, non-code-execution.md), and refreshes the no-status note in brainstorm-sections.md. Updates docs/skills/ce-work.md and the ce-plan / ce-brainstorm output-mode tests. The now-unused status span in the shared HTML rendering references is dropped alongside the rendering changes.
This commit is contained in:
Trevin Chow
@@ -95,7 +95,7 @@ A plan with four implementation units arrives. `ce-work` reads it, picks up an `
|
||||
|
||||
The Parallel Safety Check finds no file overlap across the four units and worktree isolation is available — so all four dispatch in parallel, each on its own branch. They complete; the orchestrator merges them in dependency order; tests pass after each merge. The idempotency check catches that one unit's verification was already satisfied by a prior session and marks it complete without reimplementation.
|
||||
|
||||
The diff isn't on a sensitive surface and isn't large/diffuse, so harness-native review handles it; the two suggested findings are addressed inline. Final validation passes; the operational validation plan is drafted; the plan's frontmatter flips `active → completed`; and `ce-commit-push-pr` opens the PR with summary, testing notes, the operational section, and a Compound Engineered badge.
|
||||
The diff isn't on a sensitive surface and isn't large/diffuse, so harness-native review handles it; the two suggested findings are addressed inline. Final validation passes; the operational validation plan is drafted; and `ce-commit-push-pr` opens the PR with summary, testing notes, the operational section, and a Compound Engineered badge. The plan itself is left untouched — it's a decision artifact, and whether it shipped is derived from git, not recorded in the doc.
|
||||
|
||||
---
|
||||
|
||||
@@ -167,7 +167,7 @@ For large bare-prompt scope (cross-cutting, sensitive surfaces, many files), `ce
|
||||
| `<plan path>` | Origin-sourced execution |
|
||||
| `<bare prompt>` | Triage by complexity (Trivial / Small-Medium / Large) |
|
||||
|
||||
Output: commits and (typically) a PR via `ce-commit-push-pr`. The plan body is read-only during execution; only the frontmatter `status` flips to `completed` at shipping.
|
||||
Output: commits and (typically) a PR via `ce-commit-push-pr`. The plan is read-only throughout — `ce-work` never mutates it; whether it shipped is derived from git, not recorded in the doc.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -233,14 +233,13 @@ the brainstorm.
|
||||
alongside `date` and as the resume-detection key when `ce-brainstorm`'s
|
||||
Phase 0.1 scans `docs/brainstorms/` for an existing artifact to continue.
|
||||
|
||||
### Status flip does not apply to brainstorm
|
||||
### No status field
|
||||
|
||||
Unlike plans, brainstorm artifacts have no `status` field — there is no
|
||||
`active → completed` lifecycle. A brainstorm is a one-time output that
|
||||
downstream consumers (`ce-plan`, `ce-doc-review`) reference via the plan's
|
||||
`origin:` field. The `<span class="status">` HTML hook described in
|
||||
`html-rendering.md` is a plan-side mechanic and does not render on
|
||||
brainstorm artifacts.
|
||||
Brainstorm artifacts have no `status` field and no `active → completed`
|
||||
lifecycle — a brainstorm is a one-time output that downstream consumers
|
||||
(`ce-plan`, `ce-doc-review`) reference via the plan's `origin:` field. No
|
||||
CE artifact carries a mutable status; whether work shipped is derived from
|
||||
git, not stored in the doc. Do not introduce one.
|
||||
|
||||
### Field-name stability
|
||||
|
||||
|
||||
@@ -93,8 +93,8 @@ If the user references an existing plan file or there is an obvious recent match
|
||||
|
||||
Words like "strengthen", "confidence", "gaps", and "rigor" are NOT sufficient on their own to trigger deepening. These words appear in normal editing requests ("strengthen that section about the diagram", "there are gaps in the test scenarios") and should not cause a holistic deepening pass. Only treat them as deepening intent when the request clearly targets the plan as a whole and does not name a specific section or content area to change — and even then, prefer to confirm with the user before entering the deepening flow.
|
||||
|
||||
Once the plan is identified and appears complete (all major sections present, implementation units defined, `status: active`):
|
||||
- **Routing is keyed on file extension first, then frontmatter.** HTML plans (`.html`) are always software plans — the html-rendering invariant forbids YAML frontmatter, so frontmatter absence is not a non-software signal for HTML. Treat the visible-header metadata (title, status, date) as the frontmatter equivalent.
|
||||
Once the plan is identified and appears complete (all major sections present, implementation units defined):
|
||||
- **Routing is keyed on file extension first, then frontmatter.** HTML plans (`.html`) are always software plans — the html-rendering invariant forbids YAML frontmatter, so frontmatter absence is not a non-software signal for HTML. Treat the visible-header metadata (title, date) as the frontmatter equivalent.
|
||||
- **`.html` plan:** short-circuit to Phase 5.3 (Confidence Check and Deepening) in **interactive mode**. Never route to `references/universal-planning.md` based on missing YAML.
|
||||
- **`.md` plan WITH YAML frontmatter:** short-circuit to Phase 5.3 in **interactive mode**.
|
||||
- **`.md` plan WITHOUT YAML frontmatter** (non-software plans use a simple `# Title` heading with `Created:` date instead): route to `references/universal-planning.md` for editing or deepening instead of Phase 5.3. Non-software plans do not use the software confidence check.
|
||||
|
||||
@@ -212,13 +212,13 @@ plan.
|
||||
- **`type`** — conventional-commit-prefix-aligned classification (`feat`,
|
||||
`fix`, `refactor`, `chore`, `docs`, `perf`, `test`, etc.). Carries the
|
||||
intent the eventual commit message should reflect.
|
||||
- **`status`** — `active` on creation; `ce-work` flips to `completed` on
|
||||
ship. `ce-plan`'s Phase 0.1 resume fast path keys on `active`. In HTML,
|
||||
status MUST render as `<span class="status">{value}</span>` so the flip
|
||||
mechanic can locate and rewrite it by selector (see
|
||||
`references/html-rendering.md`).
|
||||
- **`date`** — creation date in ISO 8601 (`YYYY-MM-DD`), ASCII digits only.
|
||||
|
||||
Plans carry **no `status` field** — a plan is a decision artifact, not a
|
||||
tracked work item. `ce-work` does not mutate the plan at ship time;
|
||||
whether a plan shipped is derived from git, not stored in the doc. Do not
|
||||
add a `status` field or an `active → completed` lifecycle.
|
||||
|
||||
### Optional but well-known
|
||||
|
||||
These fields are not required, but when set they have fixed names and
|
||||
@@ -243,8 +243,8 @@ semantics so downstream tooling can rely on them:
|
||||
|
||||
Field names are stable across plan revisions — never rename a field or
|
||||
repurpose its semantics. Agents composing new plans MUST use these exact
|
||||
names; adding new fields is fine, but renaming `status` to `state` or
|
||||
`origin` to `source` breaks the downstream consumers above.
|
||||
names; adding new fields is fine, but renaming `origin` to `source` or
|
||||
`date` to `created` breaks the downstream consumers above.
|
||||
|
||||
## ID and content rules
|
||||
|
||||
|
||||
@@ -111,7 +111,7 @@ Determine how to proceed based on what was provided in `<input_document>`.
|
||||
- If anything is unclear or ambiguous, ask clarifying questions now
|
||||
- If clarifying questions were needed above, get user approval on the resolved answers. If no clarifications were needed, proceed without a separate approval step — plan scope is the plan's authority, not something to renegotiate
|
||||
- **Do not skip this** - better to ask questions now than build the wrong thing
|
||||
- **Do not edit the plan body during execution.** The plan is a decision artifact; progress lives in git commits and the task tracker. The only plan mutation during ce-work is the final `status: active → completed` flip at shipping (see `references/shipping-workflow.md` Phase 4 Step 2). Legacy plans may contain `- [ ]` / `- [x]` marks on unit headings — ignore them as state; per-unit completion is determined during execution by reading the current file state.
|
||||
- **Do not edit the plan body during execution.** The plan is a decision artifact; progress lives in git commits and the task tracker, not the plan. `ce-work` does not mutate the plan — whether it shipped is derived from git, not recorded in the doc. Legacy plans may contain `- [ ]` / `- [x]` marks on unit headings or a `status:` field — ignore them as state; per-unit completion is determined during execution by reading the current file state.
|
||||
|
||||
2. **Setup Environment**
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ Do **not** run any of the code-shipping machinery — it does not fit knowledge
|
||||
- No branch/worktree setup (Phase 1 Step 2).
|
||||
- No task-list-from-implementation-units, no execution-strategy/subagent dispatch keyed on `Files:`.
|
||||
- No Test Discovery, no test-scenario completeness, no system-wide test check.
|
||||
- No incremental code commits, and none of `references/shipping-workflow.md` (no PR, no CI, no `active → completed` flip on a code plan).
|
||||
- No incremental code commits, and none of `references/shipping-workflow.md` (no PR, no CI).
|
||||
|
||||
## Execute the production plan
|
||||
|
||||
|
||||
@@ -91,14 +91,7 @@ This file contains the shipping workflow (Phase 3-4). Load it only when all Phas
|
||||
|
||||
Note whether the completed work has observable behavior (UI rendering, CLI output, API/library behavior with a runnable example, generated artifacts, or workflow output). The `ce-commit-push-pr` skill will ask whether to capture evidence only when evidence is possible.
|
||||
|
||||
2. **Update Plan Status**
|
||||
|
||||
If the input document has YAML frontmatter with a `status` field, update it to `completed`:
|
||||
```
|
||||
status: active -> status: completed
|
||||
```
|
||||
|
||||
3. **Commit and Create Pull Request**
|
||||
2. **Commit and Create Pull Request**
|
||||
|
||||
Load the `ce-commit-push-pr` skill to handle committing, pushing, and PR creation. The skill handles convention detection, branch safety, logical commit splitting, adaptive PR descriptions, and attribution badges.
|
||||
|
||||
@@ -112,7 +105,7 @@ This file contains the shipping workflow (Phase 3-4). Load it only when all Phas
|
||||
|
||||
If the user prefers to commit without creating a PR, load the `ce-commit` skill instead.
|
||||
|
||||
4. **Notify User**
|
||||
3. **Notify User**
|
||||
- Summarize what was completed
|
||||
- Link to PR (if one was created)
|
||||
- Note any follow-up work needed
|
||||
|
||||
@@ -58,7 +58,7 @@ Determine how to proceed based on what was provided in `<input_document>`.
|
||||
- If anything is unclear or ambiguous, ask clarifying questions now
|
||||
- If clarifying questions were needed above, get user approval on the resolved answers. If no clarifications were needed, proceed without a separate approval step — plan scope is the plan's authority, not something to renegotiate
|
||||
- **Do not skip this** - better to ask questions now than build the wrong thing
|
||||
- **Do not edit the plan body during execution.** The plan is a decision artifact; progress lives in git commits and the task tracker. The only plan mutation during ce-work is the final `status: active → completed` flip at shipping (see `references/shipping-workflow.md` Phase 4 Step 2). Legacy plans may contain `- [ ]` / `- [x]` marks on unit headings — ignore them as state; per-unit completion is determined during execution by reading the current file state.
|
||||
- **Do not edit the plan body during execution.** The plan is a decision artifact; progress lives in git commits and the task tracker, not the plan. `ce-work` does not mutate the plan — whether it shipped is derived from git, not recorded in the doc. Legacy plans may contain `- [ ]` / `- [x]` marks on unit headings or a `status:` field — ignore them as state; per-unit completion is determined during execution by reading the current file state.
|
||||
|
||||
2. **Setup Environment**
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ Do **not** run any of the code-shipping machinery — it does not fit knowledge
|
||||
- No branch/worktree setup (Phase 1 Step 2).
|
||||
- No task-list-from-implementation-units, no execution-strategy/subagent dispatch keyed on `Files:`.
|
||||
- No Test Discovery, no test-scenario completeness, no system-wide test check.
|
||||
- No incremental code commits, and none of `references/shipping-workflow.md` (no PR, no CI, no `active → completed` flip on a code plan).
|
||||
- No incremental code commits, and none of `references/shipping-workflow.md` (no PR, no CI).
|
||||
|
||||
## Execute the production plan
|
||||
|
||||
|
||||
@@ -91,26 +91,7 @@ This file contains the shipping workflow (Phase 3-4). It is loaded when all Phas
|
||||
|
||||
Note whether the completed work has observable behavior (UI rendering, CLI output, API/library behavior with a runnable example, generated artifacts, or workflow output). The `ce-commit-push-pr` skill will ask whether to capture evidence only when evidence is possible.
|
||||
|
||||
2. **Update Plan Status**
|
||||
|
||||
Update the plan's `status` field from `active` to `completed`. The
|
||||
mechanic depends on the plan's format:
|
||||
|
||||
- **Markdown plan (`.md`).** YAML frontmatter at the top of the file
|
||||
carries the status. Edit the YAML directly:
|
||||
```
|
||||
status: active -> status: completed
|
||||
```
|
||||
- **HTML plan (`.html`).** Status lives as visible text in the rendered
|
||||
header (typically `<span class="status">active</span>` or similar).
|
||||
Edit the visible element's text content directly. There is no hidden
|
||||
JSON-frontmatter copy to keep in sync — HTML metadata is a single
|
||||
source of truth in visible text per the html-rendering invariants.
|
||||
|
||||
If no status field exists in either format, skip this step — some
|
||||
plans omit frontmatter entirely.
|
||||
|
||||
3. **Commit and Create Pull Request**
|
||||
2. **Commit and Create Pull Request**
|
||||
|
||||
Load the `ce-commit-push-pr` skill to handle committing, pushing, and PR creation. The skill handles convention detection, branch safety, logical commit splitting, adaptive PR descriptions, and attribution badges.
|
||||
|
||||
@@ -124,7 +105,7 @@ This file contains the shipping workflow (Phase 3-4). It is loaded when all Phas
|
||||
|
||||
If the user prefers to commit without creating a PR, load the `ce-commit` skill instead.
|
||||
|
||||
4. **Notify User**
|
||||
3. **Notify User**
|
||||
- Summarize what was completed
|
||||
- Link to PR (if one was created)
|
||||
- Note any follow-up work needed
|
||||
|
||||
@@ -80,16 +80,14 @@ describe("ce-brainstorm metadata field contract", () => {
|
||||
}
|
||||
})
|
||||
|
||||
test("brainstorm-sections.md states that the status flip mechanic does not apply", () => {
|
||||
// The shared HTML rendering reference describes `<span class="status">`
|
||||
// as a load-bearing hook for ce-work's active → completed flip. That
|
||||
// mechanic is plan-side; brainstorm has no status lifecycle. The
|
||||
// contract must say so explicitly so an agent reading
|
||||
// brainstorm-sections.md + html-rendering.md together doesn't invent
|
||||
// a status field for brainstorm artifacts.
|
||||
test("brainstorm-sections.md states brainstorms carry no status field", () => {
|
||||
// No CE artifact carries a mutable status field — the active → completed
|
||||
// lifecycle was removed (ce-work no longer mutates plans; completion is
|
||||
// derived from git). The contract must say so explicitly so an agent
|
||||
// composing a brainstorm doesn't invent a status field.
|
||||
expect(
|
||||
/no `?status`? field|status flip does not apply|no.*active.*completed|plan-side mechanic/i.test(BODY),
|
||||
"brainstorm-sections.md must explicitly state that the `status` field / `active → completed` flip mechanic does not apply to brainstorms.",
|
||||
/no `?status`? field|no.*active.*completed/i.test(BODY),
|
||||
"brainstorm-sections.md must explicitly state that brainstorms carry no `status` field / `active → completed` lifecycle.",
|
||||
).toBe(true)
|
||||
})
|
||||
})
|
||||
|
||||
@@ -205,14 +205,13 @@ describe("ce-plan output:html mode", () => {
|
||||
// (plan-sections.md) + format-rendering refs. markdown-rendering.md now
|
||||
// says "Per-skill frontmatter fields are defined in each skill's section
|
||||
// contract" — so plan-sections.md MUST actually list them or downstream
|
||||
// tooling that keys on these field names (Phase 0.1 resume fast path on
|
||||
// `status: active`, ce-work's active→completed flip, deepening's
|
||||
// tooling that keys on these field names (deepening's
|
||||
// `deepened: YYYY-MM-DD`, HITL Proof's `origin:` traceback) breaks
|
||||
// silently when agents compose plans from the new refs.
|
||||
const body = readFileSync(PLAN_SECTIONS_PATH, "utf8")
|
||||
|
||||
// Required field names that downstream consumers depend on.
|
||||
for (const field of ["title", "type", "status", "date"]) {
|
||||
for (const field of ["title", "type", "date"]) {
|
||||
expect(
|
||||
new RegExp(`\\b${field}\\b`).test(body),
|
||||
`plan-sections.md must name the required '${field}' metadata field — downstream tooling keys on it.`,
|
||||
@@ -228,12 +227,13 @@ describe("ce-plan output:html mode", () => {
|
||||
).toBe(true)
|
||||
}
|
||||
|
||||
// The contract must explicitly state that status flips active → completed
|
||||
// so the field's mutability isn't lost when an agent reads the contract
|
||||
// without the markdown-rendering reference.
|
||||
// Plans carry NO status field — the active → completed lifecycle was
|
||||
// removed (ce-work no longer mutates the plan; completion is derived from
|
||||
// git). The contract must say so explicitly so an agent reading it does
|
||||
// not reintroduce a status field.
|
||||
expect(
|
||||
/active.*completed|completed.*active/i.test(body),
|
||||
"plan-sections.md must state the status field's active → completed transition so the mutability semantics survive on their own.",
|
||||
/no .{0,3}status.{0,3} field|carry .{0,6}no .{0,12}status/i.test(body),
|
||||
"plan-sections.md must state plans carry NO status field.",
|
||||
).toBe(true)
|
||||
})
|
||||
|
||||
|
||||
Reference in New Issue
Block a user