@navels/neal 0.1.0

package/docs/plan-format.md

@@ -0,0 +1,213 @@
+# Neal Plan Format
+
+This is the canonical public reference for executable Neal plan documents.
+The validator lives in `src/neal/plan-validation.ts` as `validatePlanDocument`.
+The selected-plan Git contract lives in `src/neal/plan-doc.ts` as
+`inspectPlanDocDisposition` and `toPlanDocMetadata`. Scope counting and status
+labels come from `getExecutionPlanScopeCount` and
+`getCurrentExecutionScopeDescriptor` in `src/neal/scopes.ts`.
+
+Executable plans are instructions for Neal's planner/coder/reviewer loop, not
+project requirements documents. They should be specific enough that one scope
+can be implemented, reviewed, and verified without relying on hidden operator
+intent.
+
+## Execution Shape
+
+Every executable plan must choose exactly one execution shape. The plan must
+include a literal `## Execution Shape` section, and that section must contain
+exactly one non-empty line:
+
+- `executionShape: one_shot`
+- `executionShape: multi_scope`
+- `executionShape: multi_scope_unknown`
+
+Use `one_shot` when the whole task fits in one bounded implementation scope.
+Use `multi_scope` when the task has a finite ordered queue of known scopes.
+Use `multi_scope_unknown` when Neal should repeat one bounded scope template
+until a concrete completion rule is satisfied, but the number of iterations is
+not knowable when the plan is written.
+
+## One-Shot Format
+
+`executionShape: one_shot` must not include a literal `## Execution Queue`
+section, a literal `## Execution Loop` section, or a standalone
+`## Completion Condition` section.
+
+Minimal valid example:
+
+```md
+# One Shot
+
+## Execution Shape
+
+executionShape: one_shot
+
+## Objective
+
+Complete one bounded change and verify it.
+```
+
+For status display, Neal treats a one-shot plan as one known scope. If the
+document has a level-one Markdown title, that title can be used as the scope
+display title; otherwise Neal falls back to a generic one-scope label.
+
+### `one_shot` Is Defended Through Plan Refinement, Not Clamped
+
+An author-declared `executionShape: one_shot` is captured once from the seed
+plan document and defended through refinement by both roles' prompts: the
+planner is instructed to keep the plan one scope and make the smallest complete
+change, and the plan reviewer is instructed to raise a blocking finding if the
+refined document declares any other execution shape or adds orchestration
+sections. That finding routes through the normal revision loop like any other.
+
+There is deliberately no hard mechanical clamp: if the review loop converges on
+a different shape (the reviewer accepts an expansion), Neal adopts the refined
+document's shape. An earlier version clamped the saved shape back to `one_shot`
+unconditionally, which caused non-convergence on complex plans — the planner
+could not produce an accurate single-scope plan, so review correctly rejected
+it until the round cap failed the run.
+
+This defense applies only to the top-level authored plan. A derived plan
+declares and owns its own execution shape. Plans authored `multi_scope` or
+`multi_scope_unknown` are unaffected — refinement may adjust their scope
+content as usual.
+
+## Multi-Scope Format
+
+`executionShape: multi_scope` must include a literal `## Execution Queue`
+section. It must not include a literal `## Execution Loop` section or a
+standalone `## Completion Condition` section.
+
+Inside `## Execution Queue`, use literal scope headings with contiguous numbers
+starting at 1:
+
+```md
+# Multi Scope
+
+## Execution Shape
+
+executionShape: multi_scope
+
+## Execution Queue
+
+### Scope 1: First bounded change
+- Goal: Implement one bounded slice.
+- Verification: `pnpm typecheck`
+- Success Condition: The first slice is complete and verified.
+
+### Scope 2: Regression coverage
+- Goal: Add focused coverage for the changed behavior.
+- Verification: `pnpm test`
+- Success Condition: The tests cover the new behavior and still pass.
+```
+
+Each scope entry must include these labeled bullets:
+
+- `- Goal:`
+- `- Verification:`
+- `- Success Condition:`
+
+The queue cannot skip or repeat numbers. Neal uses the queue headings to count
+known scopes and to show progress labels such as the current scope number and
+scope title.
+
+For a concrete in-repo multi-scope plan, see
+[../examples/issue-triage-js/PLAN.md](../examples/issue-triage-js/PLAN.md).
+
+## Multi-Scope-Unknown Format
+
+`executionShape: multi_scope_unknown` must include a literal
+`## Execution Loop` section with exactly one literal `### Recurring Scope`
+entry. It must also include a standalone, non-empty
+`## Completion Condition` section. It must not include a literal
+`## Execution Queue` section.
+
+Minimal valid example:
+
+```md
+# Recurring Scope
+
+## Execution Shape
+
+executionShape: multi_scope_unknown
+
+## Execution Loop
+
+### Recurring Scope
+- Goal: Implement one bounded recurring slice.
+- Verification: `pnpm typecheck`
+- Success Condition: The recurring slice is complete and reviewable.
+
+## Completion Condition
+
+Stop when the explicit completion rule is satisfied.
+```
+
+The recurring scope uses the same required bullets as a fixed queue. Neal treats
+the total scope count as unknown by contract, and status displays the recurring
+scope title rather than a finite total.
+
+## Verification And Acceptance
+
+A scope should name verification commands that are deterministic and
+noninteractive when possible. Examples include typecheck, test, lint, build,
+package verification, or a focused smoke command. If a command needs external
+state, credentials, network access, or manual setup, call that out in the plan
+so Neal can distinguish expected manual gates from unexpected blockers.
+
+The success condition should state what must be true after the scope is
+complete. It is not a prose summary of the goal; it is the reviewable exit
+criterion. Good success conditions mention the changed surface, the expected
+behavior or docs state, and the verification evidence required for acceptance.
+
+## Planning Normalization
+
+`neal plan` revises the selected plan file in place. It should preserve the
+user's product objective while making the document executable by Neal.
+
+During validation, Neal may normalize known legacy plan wording before checking
+the final shape. Current normalization can convert legacy queue section
+headings to `## Execution Queue`, normalize compatible scope labels to literal
+`### Scope N:` headings, and normalize known aliases for the verification and
+success-condition bullet labels. Normalization is still bounded by the same
+shape rules above; it is not a license to omit the execution shape or required
+scope fields.
+
+For `neal plan`, the original selected plan backup is stored under the run
+directory at `.neal/runs/<run-id>/PLAN_ORIGINAL.md`. Neal does not use a sibling
+repository backup directory for that copy.
+
+## Selected Plan Documents And Git
+
+Neal records selected-plan metadata with `inspectPlanDocDisposition` and
+`toPlanDocMetadata` from `src/neal/plan-doc.ts`.
+
+A selected plan document is eligible for ordinary Git inclusion only when it is
+repo-local, exists, is a regular file, and is not ignored. If that eligible
+plan document changes during a run, Neal may include it in the final tree using
+normal Git staging.
+
+The selected plan document can be the only allowed dirty path at writer-run
+start when it is the explicit plan under execution. Dirty work outside that
+selected plan still blocks writer-run start and queue continuation.
+
+## Ignored Or External Plan Documents
+
+Ignored plan files, plan files outside the repository, missing paths, and
+non-file paths are metadata-only. Neal records where they came from, but it does
+not force-add them to the repository and does not treat them as package or
+source artifacts.
+
+This distinction is useful for ignored local plans under `tmp/` or for plans
+stored outside the target repository. Those plans can drive a run, but they
+remain operator-local unless the operator intentionally copies their contents
+into a tracked document.
+
+## Protocol Boundary
+
+Neal's terminal control protocol is not Markdown artifact content. Plan files,
+derived plans, review notes, recovery guidance, and JSON artifacts should use
+their normal schema or prose fields instead of embedding terminal control marker
+words. This keeps executable plans portable and prevents transport signals from
+being misread as user instructions or repository documentation.