# Restatement of `plan.md`

## What `malvin plan` is meant to do

`malvin plan PLAN_PATH` is a proposed malvin subcommand that runs **three sequential agent prompts** against **one persistent agent session**. Each prompt is sent only after the previous response completes. The agent reads and writes the plan file at `PLAN_PATH`.

## Prompt 1 — Restate, critique, and collect questions

The agent appends to `PLAN_PATH` in this order:

1. A horizontal rule (`---`).
2. The marker line `BEGIN_MALVIN`.
3. A **clear restatement** of the plan (in the agent's own words).
4. A **critique** of the plan, addressing at least:
   - Are there errors?
   - Is the plan sound?
   - Is the plan as simple as it could be?
   - Will each concept, behavior, and constraint be enforced by a unit test?
   - Does the plan guard against overfitting to a spec, test, or metric?
5. Any **open questions** the agent cannot resolve from the plan alone.

Content above the horizontal rule (the user's original plan) is left untouched.

## Prompt 2 — Research and decide

The agent:

- Researches answers to the open questions from Prompt 1, using the codebase, malvin logs (user preferences and prior sessions), and external sources (e.g. arXiv) where appropriate.
- Makes its **best decision** on any questions that remain unanswered, favoring correctness and requiring evidence where feasible.

Prompt 2 does not rewrite the plan file; it resolves uncertainty for Prompt 3.

## Prompt 3 — Rewrite the plan

The agent **overwrites everything from `BEGIN_MALVIN` onward** in `PLAN_PATH`, producing a revised plan that incorporates the critique and the answers/decisions from Prompt 2. The user's original text above the horizontal rule remains.

## Intended file shape

After Prompt 1:

```text
[user-authored plan]

---
BEGIN_MALVIN
[restatement]
[critique]
[open questions]
```

After Prompt 3:

```text
[user-authored plan]

---
BEGIN_MALVIN
[revised plan]
```

The restatement, critique, and questions from Prompt 1 are replaced by the final rewrite.

---

## Critique

### Errors and gaps

**Claim:** `malvin plan` is not yet a registered subcommand. `malvin --help` lists `init`, `do`, `invent`, `code`, `tidy`, and `models` only; `default_prompts/docs/malvin.md` matches that list. `plan.md` is a design sketch, not wired CLI behavior.

**Claim:** Prompt 2 has no specified artifact. Research conclusions and decision rationale live only in agent session memory unless the run logs happen to capture them. Prompt 3 must reconstruct that work from context, which is fragile across long sessions or truncated context windows.

**Hypothesis:** The horizontal-rule / `BEGIN_MALVIN` cut is easy to mis-parse if the user's plan already contains `---` or the string `BEGIN_MALVIN`.
- **Predictions:** Duplicate markers or ambiguous boundaries if user content contains those tokens.
- **Test:** Feed a plan whose body includes `---` and `BEGIN_MALVIN`; verify Prompt 3 overwrites the correct span.
- **Confounders:** Agent might treat only the last marker as authoritative; no mechanical parser is specified.

### Soundness

The three-phase shape (reflect → research → revise) is sound as a human review workflow. Separating critique from rewrite avoids the common failure mode where an agent "fixes" a plan while restating it, smuggling changes past review.

Using one persistent session is reasonable for coherence: Prompt 3 can refer to Prompt 1's critique without re-ingesting a separate file.

Weakness: Prompt 1 asks both for restatement and critique in one turn. Restating and critiquing together can cause **fix drift** — the restatement may already incorporate preferred fixes, blunting the critique. (Invent run `20260531_230804_fvpaf0qb` flagged this as a structural assumption worth negating.)

### Simplicity

The plan is simple at the CLI surface (one path argument, three prompts). It pushes complexity into prompt contracts and file conventions instead of new data structures.

It may be **simpler than necessary** in one dimension and **more complex than necessary** in another:

- **Too simple:** No schema for open questions (free prose vs numbered list), no evidence citation format for Prompt 2 decisions, no link to malvin's existing gate machinery (`constrain`, adversarial smell registry, KPop `KPOP_SOLVED`).
- **Too complex:** In-place file mutation with a overwrite boundary is harder to audit than separate artifacts (e.g. `plan.restate.md`, `plan.critique.md`, `plan.final.md`).

A metamorphic triple — user plan, machine restate, machine rewrite with explicit invariant preservation — would align with the adversarial vocabulary already in `adversarial.md` / `summary.md` but adds files.

### Unit-test enforcement

The critique checklist asks whether each concept, behavior, and constraint will be enforced by a unit test. **The plan itself does not enforce that property.** Nothing in the three prompts requires the rewritten plan to name a test, a smell-registry row, or a falsifying obligation before Prompt 3 completes.

For the adversarial system work in this repo (`adv_system.md`, `adversarial.md`, `summary.md`), that gap is material: the design already commits to structural MR/PBT obligations, null-plugin non-vacuity, and filesystem materialization — none of which appear in `plan.md`'s checklist as concrete acceptance criteria.

### Overfitting guard

The checklist mentions guarding against overfitting to a spec, test, or metric, which matches the repo's adversarial goal. But `plan.md` does not say **how** the plan command should invoke that guard:

- Should Prompt 1 critique map plan bullets to `smell_registry` rows?
- Should Prompt 3 require per-obligation headers (`principle`, `invariant`, `counterexample`) from `adversarial.md`?
- Should a clean `malvin adversarial exec` run be a gate before the rewritten plan is accepted?

Without those hooks, the overfitting question is rhetorical — easy to answer "yes" in prose without falsifiable structure.

### Operational concerns

- **Latency:** Three full agent turns on one session; no parallelization. Acceptable for plan quality, costly for tight iteration loops.
- **Audit trail:** Prompt 3 destroys Prompt 1's restatement and critique in the plan file. Run logs under `.malvin/logs/` are the only recovery path; the plan does not require archiving them.
- **Idempotency:** Re-running `malvin plan` on the same file appends another `---` / `BEGIN_MALVIN` block unless the command detects an existing marker. Unspecified.

---

## Open questions

1. **Implementation status:** Is `plan.md` a spec for imminent implementation, or a draft for review (this document)? Should `plan_2.md` feed Prompt 2/3 of a manual dry-run, or replace the need for `malvin plan` until the subcommand exists?

2. **Scope:** Is `malvin plan` intended only for adversarial-system plans, or as a generic pre-`code` / pre-`constrain` step for any repo?

3. **Prompt 2 artifact:** Should Prompt 2 append a `DECISIONS` section (or write `plan.decisions.md`) with cited evidence before Prompt 3 runs? Without that, what is the contract if session context is truncated?

4. **Restate vs critique ordering:** Should Prompt 1 be split — restate only, then critique against the original without restate-influenced drift — or is combined output acceptable?

5. **Marker robustness:** Should malvin parse `BEGIN_MALVIN` mechanically (byte offset in metadata) instead of trusting the agent to respect a text marker on overwrite?

6. **Adversarial integration:** For plans touching analysis modules, should Prompt 3 require explicit links to smell-registry rows, metamorphic relations, and materialization-harness milestones from `summary.md` gate 3?

7. **Re-run semantics:** If the user edits the plan above the horizontal rule and re-runs `malvin plan`, does the command replace the existing `BEGIN_MALVIN` block, append a new one, or fail?

8. **Relationship to `malvin code`:** Does the rewritten plan below `BEGIN_MALVIN` become the input contract for `malvin code @PLAN_PATH`, and if so, should the command validate that the file matches the expected post-Prompt-3 shape before `code` accepts it?

---

## Answers (Prompt 2)

Evidence: `malvin --help` and `src/cli/args.rs` (no `plan` subcommand); git status (untracked `plan.md`); session `20260531_230746_q8dosbwh` (Prompt 1 restate+critique); `malvin invent` session `20260531_231455_4adkx3ys`; `src/artifacts/create.rs` (whole-file copy for `code`); `default_prompts/code_constraints.md`; deprecated check-plan flags in `src/cli/code_flow.rs`.

### 1. Implementation status

**Claim:** `plan.md` is a design spec for imminent implementation, not shipped behavior. `plan_2.md` is the manual Prompt-1 output from session `20260531_230746_q8dosbwh`; this section is Prompt 2.

**Decision:** Continue the manual dry-run (`plan_2.md` → answers → future Prompt-3 rewrite) to validate prompt contracts before registering `Commands::Plan`. The dry-run does not replace the subcommand; it de-risks it.

### 2. Scope

**Decision:** Generic pre-`code` step for any repo, matching how `code` and `tidy` stay domain-agnostic.

**Optional adversarial profile:** When the plan path matches `*adversarial*`, `*adv_system*`, or `smell_registry.toml` exists in the work dir, inject extra critique checklist items and Prompt-3 obligations from `adversarial.md` / `summary.md`. No separate `plan-adv` subcommand unless simplicity testing shows the profile hook is insufficient.

### 3. Prompt 2 artifact

**Decision:** Yes. Prompt 2 appends `## DECISIONS` to `PLAN_PATH` immediately after the open-questions section. Each entry is numbered to match an open question, states a verdict, and cites evidence (code path, log id, URL).

Malvin also snapshots the post-Prompt-1 file to `.malvin/logs/<run>/plan.p1.md`. Prompt 3 must read DECISIONS from the file, not from session memory alone. This matches malvin's existing pattern of authoritative run-dir artifacts (`exp_log`, `kpop.log`).

### 4. Restate vs critique ordering

**Decision:** Split. Prompt 1a restates only (explicit instruction: no fixes). Prompt 1b critiques the **original user text** above `---`, using the restatement as a comprehension check.

Combined restate+critique is acceptable only for trivial plans where fix drift is unlikely. Invent session `20260531_230804_fvpaf0qb` and the prior KPop log flagged combined output as a structural weakness.

### 5. Marker robustness

**Decision:** Yes — malvin owns boundary operations. After Prompt 1 completes, record `user_span_end` (byte offset before `---`) in run metadata. Prompt 3 agent emits the revised plan in a fenced block; malvin splices from `user_span_end` to EOF.

Do not trust the agent to overwrite the correct span when user content contains `---` or `BEGIN_MALVIN`.

### 6. Adversarial integration

**Decision:** For adversarial-profile plans, Prompt 3 must include explicit links to:

- smell-registry row ids (`principle`, `invariant`, `counterexample_shape`)
- MR/PBT obligation class per row
- materialization-harness milestones from `summary.md` gate 3

Generic plans omit this requirement. The overfitting checklist in Prompt 1 becomes operational only under the adversarial profile.

### 7. Re-run semantics

**Decision:** Replace. On re-run, malvin replaces the machine block (from the first `---` after the user header through EOF) with a fresh Prompt-1→3 pass. User text above the horizontal rule is preserved.

If the file contains ambiguous marker pairs without metadata from a prior run, fail with a clear error rather than append a second block.

### 8. Relationship to `malvin code`

**Claim:** Today `malvin code` copies the entire `.md` file to the run dir (`src/artifacts/create.rs`) and `code_constraints.md` instructs the agent to satisfy constraints in the full `plan_path`. No `BEGIN_MALVIN` validation or stripping exists; the deprecated check-plan phase was removed (`code_flow.rs`).

**Intended contract:** The section below the last `BEGIN_MALVIN` is the implementation plan; content above `---` is user context only.

**Decision:** A post-Prompt-3 plan file is a valid `malvin code` input. Future enhancement: `malvin code` strips to the machine section or warns when `BEGIN_MALVIN` is absent. No pre-validation gate is required at launch, but documenting the expected post-Prompt-3 shape in `default_prompts/docs/plan.md` is worthwhile.
