@xenonbyte/req-2-plan 0.2.3

package/tools/workflow_cli/agent_templates/claude/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: req-to-plan
+description: Requirement-to-PLAN workflow skill (r2p {{R2P_VERSION}})
+---
+
+# req-to-plan Skill
+
+Use this skill to drive the 5-stage requirement-to-PLAN workflow in any project where r2p is installed.
+
+## Available Commands
+
+Run each via Bash using the scripts in `{{R2P_BIN_DIR}}`:
+
+| Command | Purpose |
+|---|---|
+| `{{R2P_BIN_DIR}}/r2p-start [--separate] ("<requirement>" \| --file <path>)` | Start a new workflow run |
+| `{{R2P_BIN_DIR}}/r2p-continue` | Continue the active run |
+| `{{R2P_BIN_DIR}}/r2p-tier-lock --work-id <id> --base <light\|standard> --confirm` | Lock the tier for a run |
+| `{{R2P_BIN_DIR}}/r2p-status [--all]` | Inspect run state (read-only) |
+| `{{R2P_BIN_DIR}}/r2p-switch --work-id <id>` | Switch active run pointer |
+| `{{R2P_BIN_DIR}}/r2p-reopen --from <work-id> --stage <stage> --reason "<text>"` | Reopen a closed run |
+
+## Usage Pattern
+
+1. `r2p-start ("<requirement>" | --file <path>)` — start a new run
+2. `r2p-continue` — repeatedly; runs safe automatic steps, stops and suggests the next command when a human action is needed
+   - Stops at: tier not locked, needs stage artifact content, needs stage ready mark, needs human checkpoint approval, entry gate failed, needs repair (Quality Gate failed or changes requested)
+   - When stopped at `needs_content` or `needs_repair`, write the required artifact content into the printed `content_file`, then run the printed `next:` command exactly
+   - For other stops, run the printed `next:` command exactly; if an `alt:` command is shown, use it only when that alternate decision is intended
+   - Auto-runs: eligible entry gates, eligible Quality Gates, opens checkpoint review (`review-checkpoint`)
+   - Auto-advances: moves to the next stage after non-PLAN checkpoint approval, then runs that stage's entry gate
+   - Auto-closes: closes the run when the PLAN checkpoint is approved and no open routes remain
+   - Does NOT auto-mark artifacts ready and does NOT auto-approve checkpoints — those are human steps
+3. When the run closes, hand the approved PLAN at `07-plan.md` directly to your executor — the PLAN is executor-neutral and needs no adaptation step.

package/tools/workflow_cli/agent_templates/claude/commands/r2p-continue.md

@@ -0,0 +1,16 @@
+---
+description: Continue the active requirement-to-PLAN workflow run
+---
+Run `{{R2P_BIN_DIR}}/r2p-continue` to resume the currently selected run.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-continue`
+
+Behavior:
+- Performs safe automatic operations only: eligible entry gates, Quality Gates, opening checkpoint review (`review-checkpoint`), stage advancement after non-PLAN checkpoint approval, and run closure after PLAN checkpoint approval with no open routes
+- Stops when human action is required: stage content generation, marking an artifact ready (`stage-ready`), Quality Gate failure or requested changes (repair), human checkpoint approval (`checkpoint-decide`), entry gate failure
+- Stops with `needs_subagent_review` on forced-review runs (a `migration`/`safety`/`cross_project` modifier at `design`/`spec`/`plan`) when the required review file is missing. You are authorized to run a read-only review subagent yourself for this step — no separate human approval is needed
+- Does NOT auto-mark artifacts ready and does NOT auto-approve checkpoints
+
+Call repeatedly until the output says `stop:` with a message indicating why the run paused. For `needs_content` and `needs_repair`, write the required artifact content into the printed `content_file`, then run the printed `next:` command exactly. For `needs_subagent_review`, run a review subagent to audit the stage artifact, write its findings to the printed `review_file`, then resume with `r2p-continue` (you do not need to ask for approval to spawn the review subagent). For other stops, run the printed `next:` command exactly. If an `alt:` command is shown, use it only when that alternate decision is intended. Resume with `r2p-continue` after completing that step.
+
+Use `r2p-status` to inspect progress without making changes.

package/tools/workflow_cli/agent_templates/claude/commands/r2p-gap-open.md

@@ -0,0 +1,8 @@
+---
+description: Route an upstream gap back to an owner stage on an open run
+---
+Run `{{R2P_BIN_DIR}}/r2p-gap-open` to route a discovered upstream gap on an OPEN run back to the stage that owns the missing decision. Downstream artifacts are marked stale and must be re-derived.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-gap-open --work-id <work-id> --owner-stage <stage> --required-action "<text>"`
+
+Example: `{{R2P_BIN_DIR}}/r2p-gap-open --work-id WF-20260604-login --owner-stage design --required-action "fixed-window burst flaw"`

package/tools/workflow_cli/agent_templates/claude/commands/r2p-gap-resolve.md

@@ -0,0 +1,8 @@
+---
+description: Resolve an open upstream-gap route after the owner stage passes gate-quality
+---
+Run `{{R2P_BIN_DIR}}/r2p-gap-resolve` after the owner stage has been re-worked, marked `ready`, and passed `gate-quality`. It closes the route so the owner can be re-approved and the downstream re-derived.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-gap-resolve --work-id <work-id> --route-id <route-id>`
+
+Example: `{{R2P_BIN_DIR}}/r2p-gap-resolve --work-id WF-20260604-login --route-id R-1`

package/tools/workflow_cli/agent_templates/claude/commands/r2p-reopen.md

@@ -0,0 +1,8 @@
+---
+description: Reopen a closed workflow run from a specific stage
+---
+Run `{{R2P_BIN_DIR}}/r2p-reopen` to reopen a run that was closed at the PLAN checkpoint.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-reopen --from <work-id> --stage <stage> --reason "<text>"`
+
+Example: `{{R2P_BIN_DIR}}/r2p-reopen --from WF-20260527-login-rate-limit --stage spec --reason "spec gap found"`

package/tools/workflow_cli/agent_templates/claude/commands/r2p-start.md

@@ -0,0 +1,10 @@
+---
+description: Start a new requirement-to-PLAN workflow run
+---
+Run `{{R2P_BIN_DIR}}/r2p-start` with the requirement as a positional argument.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-start [--separate] ("<raw requirement>" | --file <path>)`
+
+To start from a requirement document, pass `--file <path>` instead of inline text — r2p reads the file contents as the requirement (the path itself is never stored as the requirement): `{{R2P_BIN_DIR}}/r2p-start [--separate] --file ./requirement.md`. `--file` and a positional requirement are mutually exclusive.
+
+Use `--separate` to create an independent run when another open run exists.

package/tools/workflow_cli/agent_templates/claude/commands/r2p-status.md

@@ -0,0 +1,8 @@
+---
+description: Inspect the current or all requirement-to-PLAN workflow runs (read-only)
+---
+Run `{{R2P_BIN_DIR}}/r2p-status` to inspect the active run state.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-status [--all]`
+
+Use `--all` to list status for every run in the project.

package/tools/workflow_cli/agent_templates/claude/commands/r2p-switch.md

@@ -0,0 +1,8 @@
+---
+description: Switch the active run pointer to a different workflow run
+---
+Run `{{R2P_BIN_DIR}}/r2p-switch` to change the selected active run.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-switch --work-id <id>`
+
+Use `r2p-status --all` to discover available work IDs.

package/tools/workflow_cli/agent_templates/claude/commands/r2p-tier-lock.md

@@ -0,0 +1,8 @@
+---
+description: Lock the complexity tier for an active requirement-to-PLAN workflow run
+---
+Run `{{R2P_BIN_DIR}}/r2p-tier-lock` with the work ID and selected base tier.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-tier-lock --work-id <work-id> --base <light|standard> [--modifiers <modifier,...>] --confirm`
+
+Use this when `r2p-continue` stops with `tier_not_locked`.

package/tools/workflow_cli/agent_templates/codex/skills/r2p-continue/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: r2p-continue
+description: Continue the active requirement-to-PLAN workflow run. Use when the user asks to run r2p-continue, continue r2p, resume the active r2p run, or advance the current requirement-to-PLAN workflow.
+---
+
+# r2p-continue
+
+Run `{{R2P_BIN_DIR}}/r2p-continue` to resume the currently selected run.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-continue`
+
+Call repeatedly until the run reaches the closed state. For `needs_content` and `needs_repair` stops, write the required artifact content into the printed `content_file`, then run the printed `next:` command exactly. For a `needs_subagent_review` stop (forced-review runs: a `migration`/`safety`/`cross_project` modifier at `design`/`spec`/`plan`), run a read-only review subagent to audit the stage artifact yourself — no separate human approval is needed — write its findings to the printed `review_file`, then resume with `r2p-continue`. For other stops, run the printed `next:` command exactly. If an `alt:` command is shown, use it only when that alternate decision is intended. Use `r2p-status` to inspect progress.

package/tools/workflow_cli/agent_templates/codex/skills/r2p-gap-open/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: r2p-gap-open
+description: Route an upstream gap on an open requirement-to-PLAN run back to the stage that owns the missing decision. Use when the user asks to run r2p-gap-open or route an upstream gap on an open run.
+---
+
+# r2p-gap-open
+
+Run `{{R2P_BIN_DIR}}/r2p-gap-open` to route a discovered upstream gap on an OPEN run back to the stage that owns the missing decision. Downstream artifacts are marked stale and must be re-derived.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-gap-open --work-id <work-id> --owner-stage <stage> --required-action "<text>"`
+
+Example: `{{R2P_BIN_DIR}}/r2p-gap-open --work-id WF-20260604-login --owner-stage design --required-action "fixed-window burst flaw"`

package/tools/workflow_cli/agent_templates/codex/skills/r2p-gap-resolve/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: r2p-gap-resolve
+description: Resolve an open upstream-gap route after the owner stage is re-worked and passes gate-quality. Use when the user asks to run r2p-gap-resolve or close a gap route.
+---
+
+# r2p-gap-resolve
+
+Run `{{R2P_BIN_DIR}}/r2p-gap-resolve` after the owner stage has been re-worked, marked `ready`, and passed `gate-quality`. It closes the route so the owner can be re-approved and the downstream re-derived.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-gap-resolve --work-id <work-id> --route-id <route-id>`
+
+Example: `{{R2P_BIN_DIR}}/r2p-gap-resolve --work-id WF-20260604-login --route-id R-1`

package/tools/workflow_cli/agent_templates/codex/skills/r2p-reopen/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: r2p-reopen
+description: Reopen a closed requirement-to-PLAN workflow run from a specific stage. Use when the user asks to run r2p-reopen or reopen an r2p run because an upstream stage needs repair.
+---
+
+# r2p-reopen
+
+Run `{{R2P_BIN_DIR}}/r2p-reopen` to reopen a run that was closed at the PLAN checkpoint.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-reopen --from <work-id> --stage <stage> --reason "<text>"`
+
+Example: `{{R2P_BIN_DIR}}/r2p-reopen --from WF-20260527-login-rate-limit --stage spec --reason "spec gap found"`

package/tools/workflow_cli/agent_templates/codex/skills/r2p-start/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: r2p-start
+description: Start a new requirement-to-PLAN workflow run from a raw requirement. Use when the user asks to run r2p-start, start r2p, begin the requirement-to-PLAN workflow, or turn a requirement into a PLAN.
+---
+
+# r2p-start
+
+Run `{{R2P_BIN_DIR}}/r2p-start` with the requirement as a positional argument.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-start [--separate] ("<raw requirement>" | --file <path>)`
+
+To start from a requirement document, pass `--file <path>` instead of inline text — r2p reads the file contents as the requirement (the path itself is never stored as the requirement): `{{R2P_BIN_DIR}}/r2p-start [--separate] --file ./requirement.md`. `--file` and a positional requirement are mutually exclusive.
+
+Use `--separate` to create an independent run when another open run exists.

package/tools/workflow_cli/agent_templates/codex/skills/r2p-status/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: r2p-status
+description: Inspect current or all requirement-to-PLAN workflow runs without writing state. Use when the user asks to run r2p-status, check r2p status, list r2p runs, or inspect the active r2p run.
+---
+
+# r2p-status
+
+Run `{{R2P_BIN_DIR}}/r2p-status` to inspect the active run state.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-status [--all]`
+
+Use `--all` to list status for every run in the project.

package/tools/workflow_cli/agent_templates/codex/skills/r2p-switch/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: r2p-switch
+description: Switch the active requirement-to-PLAN run pointer to a different work ID. Use when the user asks to run r2p-switch, select an r2p run, or change the active r2p workflow run.
+---
+
+# r2p-switch
+
+Run `{{R2P_BIN_DIR}}/r2p-switch` to change the selected active run.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-switch --work-id <id>`
+
+Use `r2p-status --all` to discover available work IDs.

package/tools/workflow_cli/agent_templates/codex/skills/r2p-tier-lock/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: r2p-tier-lock
+description: Lock the complexity tier for the active requirement-to-PLAN workflow run. Use when r2p-continue stops with tier_not_locked or asks for r2p-tier-lock.
+---
+
+# r2p-tier-lock
+
+Run `{{R2P_BIN_DIR}}/r2p-tier-lock` with the work ID and selected base tier.
+
+Usage: `{{R2P_BIN_DIR}}/r2p-tier-lock --work-id <work-id> --base <light|standard> [--modifiers <modifier,...>] --confirm`
+
+Use this only after choosing the tier floor shown by the workflow output.

package/tools/workflow_cli/agent_templates/gemini/commands/r2p-continue.toml

@@ -0,0 +1,4 @@
+name = "r2p-continue"
+description = "Continue the active requirement-to-PLAN workflow run"
+command = "{{R2P_BIN_DIR}}/r2p-continue"
+version = "{{R2P_VERSION}}"

package/tools/workflow_cli/agent_templates/gemini/commands/r2p-gap-open.toml

@@ -0,0 +1,4 @@
+name = "r2p-gap-open"
+description = "Route an upstream gap back to an owner stage on an open run"
+command = "{{R2P_BIN_DIR}}/r2p-gap-open"
+version = "{{R2P_VERSION}}"

package/tools/workflow_cli/agent_templates/gemini/commands/r2p-gap-resolve.toml

@@ -0,0 +1,4 @@
+name = "r2p-gap-resolve"
+description = "Resolve an open upstream-gap route after the owner stage passes gate-quality"
+command = "{{R2P_BIN_DIR}}/r2p-gap-resolve"
+version = "{{R2P_VERSION}}"

package/tools/workflow_cli/agent_templates/gemini/commands/r2p-reopen.toml

@@ -0,0 +1,4 @@
+name = "r2p-reopen"
+description = "Reopen a closed workflow run from a specific stage"
+command = "{{R2P_BIN_DIR}}/r2p-reopen"
+version = "{{R2P_VERSION}}"

package/tools/workflow_cli/agent_templates/gemini/commands/r2p-start.toml

@@ -0,0 +1,4 @@
+name = "r2p-start"
+description = "Start a new requirement-to-PLAN workflow run"
+command = "{{R2P_BIN_DIR}}/r2p-start"
+version = "{{R2P_VERSION}}"

package/tools/workflow_cli/agent_templates/gemini/commands/r2p-status.toml

@@ -0,0 +1,4 @@
+name = "r2p-status"
+description = "Inspect the current or all requirement-to-PLAN workflow runs"
+command = "{{R2P_BIN_DIR}}/r2p-status"
+version = "{{R2P_VERSION}}"

package/tools/workflow_cli/agent_templates/gemini/commands/r2p-switch.toml

@@ -0,0 +1,4 @@
+name = "r2p-switch"
+description = "Switch the active run pointer to a different workflow run"
+command = "{{R2P_BIN_DIR}}/r2p-switch"
+version = "{{R2P_VERSION}}"

package/tools/workflow_cli/agent_templates/gemini/commands/r2p-tier-lock.toml

@@ -0,0 +1,4 @@
+name = "r2p-tier-lock"
+description = "Lock the complexity tier for an active requirement-to-PLAN workflow run"
+command = "{{R2P_BIN_DIR}}/r2p-tier-lock"
+version = "{{R2P_VERSION}}"

package/tools/workflow_cli/artifact.py

@@ -0,0 +1,228 @@
+"""
+Artifact lifecycle manager for req-to-plan workflow runs.
+
+Each stage produces an artifact file in .req-to-plan/<work-id>/.
+Files use YAML frontmatter to track version, status, and timestamps.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+from tools.workflow_cli.models import Stage, STAGE_ARTIFACT_MAP
+
+
+# ---------------------------------------------------------------------------
+# Path helpers
+# ---------------------------------------------------------------------------
+
+
+def artifact_path(run_dir: Path, stage: Stage) -> Path:
+    """Return the expected filesystem path for a stage artifact."""
+    return run_dir / STAGE_ARTIFACT_MAP[stage]
+
+
+def artifact_exists(run_dir: Path, stage: Stage) -> bool:
+    """Return True if the artifact file for this stage exists."""
+    return artifact_path(run_dir, stage).exists()
+
+
+# ---------------------------------------------------------------------------
+# Frontmatter helpers
+# ---------------------------------------------------------------------------
+
+
+def _frontmatter(
+    stage: Stage,
+    version: int,
+    status: str,
+    created_at: str,
+    updated_at: str,
+) -> str:
+    return (
+        f"---\n"
+        f"r2p_stage: {stage.value}\n"
+        f"r2p_version: {version}\n"
+        f"r2p_status: {status}\n"
+        f"r2p_created_at: {created_at}\n"
+        f"r2p_updated_at: {updated_at}\n"
+        f"---\n\n"
+    )
+
+
+def _parse_frontmatter(text: str) -> tuple[dict, str]:
+    """Return (frontmatter_dict, body_content).
+
+    Expects YAML frontmatter delimited by ``---`` lines.
+    Returns empty dict and original text when no frontmatter is present.
+    """
+    if not text.startswith("---\n"):
+        return {}, text
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return {}, text
+    fm_text = text[4:end]
+    body = text[end + 5:].lstrip("\n")
+    fm: dict[str, str] = {}
+    for line in fm_text.splitlines():
+        if ": " in line:
+            key, val = line.split(": ", 1)
+            fm[key.strip()] = val.strip()
+    return fm, body
+
+
+# ---------------------------------------------------------------------------
+# Core read / write functions
+# ---------------------------------------------------------------------------
+
+
+def write_artifact(
+    run_dir: Path,
+    stage: Stage,
+    content: str,
+    version: int = 1,
+    status: str = "draft",
+) -> Path:
+    """Write (or overwrite) a stage artifact with YAML frontmatter.
+
+    Preserves the original ``r2p_created_at`` timestamp when the file
+    already exists.
+
+    Returns the path of the written file.
+    """
+    path = artifact_path(run_dir, stage)
+    run_dir.mkdir(parents=True, exist_ok=True)
+    now = datetime.now(timezone.utc).isoformat()
+    created_at = now
+    if path.exists():
+        fm, _ = _parse_frontmatter(path.read_text(encoding="utf-8"))
+        created_at = fm.get("r2p_created_at", now)
+    full_text = _frontmatter(stage, version, status, created_at, now) + content
+    path.write_text(full_text, encoding="utf-8")
+    return path
+
+
+def read_artifact(run_dir: Path, stage: Stage) -> str:
+    """Return artifact body content (without frontmatter).
+
+    Raises FileNotFoundError when the artifact does not exist.
+    """
+    path = artifact_path(run_dir, stage)
+    if not path.exists():
+        raise FileNotFoundError(f"Artifact not found: {path}")
+    _, body = _parse_frontmatter(path.read_text(encoding="utf-8"))
+    return body
+
+
+def get_artifact_version(run_dir: Path, stage: Stage) -> int:
+    """Return the current version number from frontmatter, or 0 if absent."""
+    path = artifact_path(run_dir, stage)
+    if not path.exists():
+        return 0
+    fm, _ = _parse_frontmatter(path.read_text(encoding="utf-8"))
+    try:
+        return int(fm.get("r2p_version", 0))
+    except (ValueError, TypeError):
+        return 0
+
+
+def get_artifact_status(run_dir: Path, stage: Stage) -> str:
+    """Return the current status string from frontmatter, or 'missing' if absent."""
+    path = artifact_path(run_dir, stage)
+    if not path.exists():
+        return "missing"
+    fm, _ = _parse_frontmatter(path.read_text(encoding="utf-8"))
+    return fm.get("r2p_status", "unknown")
+
+
+def update_artifact_status(run_dir: Path, stage: Stage, new_status: str) -> None:
+    """Rewrite the artifact preserving content and version but updating status.
+
+    Raises FileNotFoundError when the artifact does not exist.
+    """
+    path = artifact_path(run_dir, stage)
+    if not path.exists():
+        raise FileNotFoundError(f"Artifact not found: {path}")
+    fm, body = _parse_frontmatter(path.read_text(encoding="utf-8"))
+    write_artifact(
+        run_dir,
+        stage,
+        body,
+        version=int(fm.get("r2p_version", 1)),
+        status=new_status,
+    )
+
+
+# ---------------------------------------------------------------------------
+# ArtifactManager class
+# ---------------------------------------------------------------------------
+
+
+class ArtifactManager:
+    """High-level interface for managing stage artifacts in a run directory."""
+
+    def __init__(self, run_dir: Path) -> None:
+        self.run_dir = run_dir
+
+    def stage_produce(self, stage: Stage, content: str) -> Path:
+        """Write the initial version (v1, draft) of a stage artifact.
+
+        Raises FileExistsError if the artifact already exists at version > 1
+        or with a non-draft status. Use stage_update to create a new version.
+        """
+        version = get_artifact_version(self.run_dir, stage)
+        status = get_artifact_status(self.run_dir, stage)
+        if version > 1:
+            raise FileExistsError(
+                f"Artifact for stage {stage.value!r} is already at version {version}. "
+                "Use stage_update to create a new version."
+            )
+        if status not in ("draft", "missing"):
+            raise FileExistsError(
+                f"Artifact for stage {stage.value!r} has status {status!r}. "
+                "Cannot re-produce a non-draft artifact; use stage_update instead."
+            )
+        return write_artifact(self.run_dir, stage, content, version=1, status="draft")
+
+    def stage_update(self, stage: Stage, content: str) -> Path:
+        """Increment the version and overwrite content, keeping status as draft."""
+        current_version = get_artifact_version(self.run_dir, stage)
+        return write_artifact(
+            self.run_dir,
+            stage,
+            content,
+            version=current_version + 1,
+            status="draft",
+        )
+
+    def stage_ready(self, stage: Stage) -> None:
+        """Mark a stage artifact as ready (content unchanged)."""
+        status = get_artifact_status(self.run_dir, stage)
+        if status == "stale":
+            raise ValueError(
+                f"Artifact for stage {stage.value!r} is stale. "
+                "Use stage_update to create a new version before marking it ready."
+            )
+        update_artifact_status(self.run_dir, stage, "ready")
+
+    def mark_stale(self, stage: Stage, reason: str, replaced_by: str) -> None:
+        """Mark a stage artifact as stale, recording reason and replaced_by in frontmatter."""
+        path = artifact_path(self.run_dir, stage)
+        if not path.exists():
+            raise FileNotFoundError(f"Artifact not found: {path}")
+        fm, body = _parse_frontmatter(path.read_text(encoding="utf-8"))
+        now = datetime.now(timezone.utc).isoformat()
+        created_at = fm.get("r2p_created_at", now)
+        version = int(fm.get("r2p_version", 1))
+        content = (
+            f"---\n"
+            f"r2p_stage: {stage.value}\n"
+            f"r2p_version: {version}\n"
+            f"r2p_status: stale\n"
+            f"r2p_created_at: {created_at}\n"
+            f"r2p_updated_at: {now}\n"
+            f"r2p_stale_reason: {reason}\n"
+            f"r2p_replaced_by: {replaced_by}\n"
+            f"---\n\n"
+        ) + body
+        path.write_text(content, encoding="utf-8")