frontface-flashy 1.0.0__tar.gz

frontface_flashy-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Wesley Hitchcock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

frontface_flashy-1.0.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: frontface-flashy
+Version: 1.0.0
+Summary: Persistent execution discipline for long tasks: lock the objective, track milestones, detect drift and artificial stops, verify before done
+Author: Ryan Wesley Hitchcock
+License: MIT
+Project-URL: Homepage, https://github.com/ohpersonperson/frontface
+Keywords: execution,task-management,state-machine,agents,workflow
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Flashy — persistent execution discipline
+
+Prevents an agent from abandoning a build halfway. Locks the objective,
+expands it into milestones, tracks live execution state, scans for drift
+after every milestone, detects artificial stops ("here's a starting
+point"), checkpoints honestly on genuine limits, and gates completion on
+a quality checklist.
+
+Mission rule: **a draft is not a delivery.** Completion is measured by
+whether the user actually received the usable thing they asked for.
+
+No prerequisites. The mechanism is the whole product.
+
+*(Lineage: this is the front-facing conversion of the `flashy` skill from
+Ryan's skill-suite, MIT — itself a port of an execution-discipline
+protocol into skill format. What changed in the conversion is documented
+in CHANGELOG.md.)*
+
+## What it does
+
+For any substantial build/create/write task, run the core loop — **lock,
+move, verify**:
+
+1. **Lock the objective.** Extract three things from the request: the
+   stated deliverable, the implicit quality bar ("a login form" implies
+   validation and error states even if unsaid), and the implicit scope
+   boundaries. Once locked, the objective is immutable for the rest of the
+   task: subtasks don't replace the mission, explanations don't replace
+   execution, planning doesn't replace progress.
+2. **Expand into milestones.** Objective → Major Milestones → Subtasks →
+   Implementation Steps → Verification → Delivery.
+3. **Track execution state.** A real state machine —
+   `LOCKED → PLANNING → EXECUTING → VERIFYING → DONE`, with `BLOCKED`
+   reachable from `EXECUTING`/`VERIFYING` — enforces the transition rules
+   in code: no `VERIFYING → DONE` without every Quality Gate box checked,
+   no silent `EXECUTING → PLANNING` without an explicit user-driven scope
+   change, no `BLOCKED → EXECUTING` without an emitted checkpoint.
+4. **Scan for drift after every milestone.** Four questions: still solving
+   the original problem? wandered into explanation instead of building?
+   forgot earlier requirements? would the user call this finished? On
+   drift: discard the thread, restate the objective, resume from the last
+   verified milestone.
+5. **Detect artificial stops.** "Here's a starting point," "the rest follows
+   similarly," "due to space..." — these are execution failures, not
+   conclusions. The package scans output for the phrase list and flags
+   them; the operator rewrites the impulse as **Continue Working.**
+6. **Checkpoint honestly on genuine limits.** Context cutoff, tool error,
+   or a low-confidence blocker with no safe default — emit a checkpoint
+   with a resume token (`finish:<slug>-m<N>`) and continue next turn.
+   Fatigue and "this feels done" are failures, not checkpoints.
+7. **Verify before done.** The seven-box Quality Gate is a hard gate, not
+   a vibe check. Any unchecked box = IN PROGRESS.
+
+**Execution bias: build before briefing.** Build → Verify → Polish →
+Explain. Understanding the problem well enough to act is the signal to
+stop analyzing and start executing. And the end-of-response gate: a
+response ending is not a task ending — if useful progress can still be
+made, keep executing; don't hand the turn back for permission.
+
+**Pause only for implementation-changing decisions** — choice of
+database/language/framework, deployment target, a required credential, or
+an ambiguity where two reasonable interpretations produce meaningfully
+different deliverables. "Continue?" / "Should I keep going?" are never
+valid stopping points.
+
+## Why it works
+
+Most abandoned builds don't fail — they *decay*. The objective quietly
+gets replaced by a subtask. Explanation replaces execution. A response
+"feels long enough" and stops. Flashy attacks the decay mechanically:
+
+- **The state machine** makes the rules structural: you cannot declare
+  done without the gate, cannot silently re-plan, cannot resume from a
+  block without a checkpoint. The failure modes are `TransitionError`s,
+  not suggestions.
+- **Artificial-stop detection** catches the exact phrases long tasks die
+  on — as a string scan, in code, every time.
+- **The confidence engine** (High/Medium/Low) resolves ambiguity without
+  blocking: High proceeds silently, Medium proceeds stating the
+  assumption inline, only Low pauses. Most ambiguity never surfaces as a
+  stop.
+- **Checkpoints with resume tokens** make interruption recoverable without
+  the user re-explaining anything — which removes the incentive to
+  quietly abandon a task at a session break.
+
+## Quickstart
+
+Zero dependencies beyond Python 3.10+. No model, no network — this
+package is pure discipline machinery.
+
+```bash
+cd flashy
+python3 -m unittest discover -s tests     # 41 offline tests — prove the machinery first
+python3 examples/demo_session.py          # watch a session run LOCKED -> DONE
+```
+
+Or use it as a library:
+
+```python
+from flashy import MissionSession
+
+session = MissionSession(
+    "Deliver a functional, usable, in-browser debate simulator.",
+    slug="debate-sim",
+)
+session.plan(["Architecture", "UI", "Logic", "Persistence", "Testing", "Delivery"])
+session.start_executing()
+
+for milestone in ["Architecture", "UI", "Logic", "Persistence", "Testing", "Delivery"]:
+    assert session.end_of_response_gate() == "continue"
+    session.complete_milestone(milestone)
+    print(session.dashboard())
+
+session.begin_verification()
+session.gate.check_all()
+session.finish()  # raises unless every box is checked
+assert session.machine.state == "DONE"
+```
+
+## Inputs, outputs
+
+- **Input:** a locked objective (the finished thing, not the artifact
+  type), milestones, constraints, pending decisions.
+- **Output:** a driven session — dashboard state, checkpoints with resume
+  tokens, and a DONE that actually means done. The package never writes
+  files; your harness owns persistence.
+
+## Worked examples
+
+Three in `examples/`, a stranger can follow all of them:
+
+1. `example-1-debate-simulator-walkthrough.md` — the full loop end to end
+   on a browser debate simulator (ported from the original skill, unchanged).
+2. `example-2-anti-patterns.md` — before/after pairs: artificial-stop
+   language vs. the corrected continuation (ported, unchanged).
+3. `example-3-flashy-session.md` — the machinery itself: every
+   transition, gate, and checkpoint shown as the code enforces it. Run
+   `demo_session.py` to watch it execute.
+
+*All fields are constructed for teaching — they show the discipline's
+shape, not real findings.*
+
+## FAQ
+
+**Does this make the model smarter?** No. It makes it finish things.
+Execution discipline, not reasoning quality.
+
+**Does it need an internet connection?** No. No model calls at all — the
+41 unit tests and the demo run fully offline.
+
+**What does it cost?** Nothing. Free, dependency-free, offline.
+
+**When should it *not* fire?** Trivial tasks (a single short answer),
+genuine user decisions pending, safety constraints, or real platform
+limits. Never deactivate because a response "feels long enough."
+
+## License
+
+MIT. See LICENSE.

frontface_flashy-1.0.0/README.md

@@ -0,0 +1,159 @@
+# Flashy — persistent execution discipline
+
+Prevents an agent from abandoning a build halfway. Locks the objective,
+expands it into milestones, tracks live execution state, scans for drift
+after every milestone, detects artificial stops ("here's a starting
+point"), checkpoints honestly on genuine limits, and gates completion on
+a quality checklist.
+
+Mission rule: **a draft is not a delivery.** Completion is measured by
+whether the user actually received the usable thing they asked for.
+
+No prerequisites. The mechanism is the whole product.
+
+*(Lineage: this is the front-facing conversion of the `flashy` skill from
+Ryan's skill-suite, MIT — itself a port of an execution-discipline
+protocol into skill format. What changed in the conversion is documented
+in CHANGELOG.md.)*
+
+## What it does
+
+For any substantial build/create/write task, run the core loop — **lock,
+move, verify**:
+
+1. **Lock the objective.** Extract three things from the request: the
+   stated deliverable, the implicit quality bar ("a login form" implies
+   validation and error states even if unsaid), and the implicit scope
+   boundaries. Once locked, the objective is immutable for the rest of the
+   task: subtasks don't replace the mission, explanations don't replace
+   execution, planning doesn't replace progress.
+2. **Expand into milestones.** Objective → Major Milestones → Subtasks →
+   Implementation Steps → Verification → Delivery.
+3. **Track execution state.** A real state machine —
+   `LOCKED → PLANNING → EXECUTING → VERIFYING → DONE`, with `BLOCKED`
+   reachable from `EXECUTING`/`VERIFYING` — enforces the transition rules
+   in code: no `VERIFYING → DONE` without every Quality Gate box checked,
+   no silent `EXECUTING → PLANNING` without an explicit user-driven scope
+   change, no `BLOCKED → EXECUTING` without an emitted checkpoint.
+4. **Scan for drift after every milestone.** Four questions: still solving
+   the original problem? wandered into explanation instead of building?
+   forgot earlier requirements? would the user call this finished? On
+   drift: discard the thread, restate the objective, resume from the last
+   verified milestone.
+5. **Detect artificial stops.** "Here's a starting point," "the rest follows
+   similarly," "due to space..." — these are execution failures, not
+   conclusions. The package scans output for the phrase list and flags
+   them; the operator rewrites the impulse as **Continue Working.**
+6. **Checkpoint honestly on genuine limits.** Context cutoff, tool error,
+   or a low-confidence blocker with no safe default — emit a checkpoint
+   with a resume token (`finish:<slug>-m<N>`) and continue next turn.
+   Fatigue and "this feels done" are failures, not checkpoints.
+7. **Verify before done.** The seven-box Quality Gate is a hard gate, not
+   a vibe check. Any unchecked box = IN PROGRESS.
+
+**Execution bias: build before briefing.** Build → Verify → Polish →
+Explain. Understanding the problem well enough to act is the signal to
+stop analyzing and start executing. And the end-of-response gate: a
+response ending is not a task ending — if useful progress can still be
+made, keep executing; don't hand the turn back for permission.
+
+**Pause only for implementation-changing decisions** — choice of
+database/language/framework, deployment target, a required credential, or
+an ambiguity where two reasonable interpretations produce meaningfully
+different deliverables. "Continue?" / "Should I keep going?" are never
+valid stopping points.
+
+## Why it works
+
+Most abandoned builds don't fail — they *decay*. The objective quietly
+gets replaced by a subtask. Explanation replaces execution. A response
+"feels long enough" and stops. Flashy attacks the decay mechanically:
+
+- **The state machine** makes the rules structural: you cannot declare
+  done without the gate, cannot silently re-plan, cannot resume from a
+  block without a checkpoint. The failure modes are `TransitionError`s,
+  not suggestions.
+- **Artificial-stop detection** catches the exact phrases long tasks die
+  on — as a string scan, in code, every time.
+- **The confidence engine** (High/Medium/Low) resolves ambiguity without
+  blocking: High proceeds silently, Medium proceeds stating the
+  assumption inline, only Low pauses. Most ambiguity never surfaces as a
+  stop.
+- **Checkpoints with resume tokens** make interruption recoverable without
+  the user re-explaining anything — which removes the incentive to
+  quietly abandon a task at a session break.
+
+## Quickstart
+
+Zero dependencies beyond Python 3.10+. No model, no network — this
+package is pure discipline machinery.
+
+```bash
+cd flashy
+python3 -m unittest discover -s tests     # 41 offline tests — prove the machinery first
+python3 examples/demo_session.py          # watch a session run LOCKED -> DONE
+```
+
+Or use it as a library:
+
+```python
+from flashy import MissionSession
+
+session = MissionSession(
+    "Deliver a functional, usable, in-browser debate simulator.",
+    slug="debate-sim",
+)
+session.plan(["Architecture", "UI", "Logic", "Persistence", "Testing", "Delivery"])
+session.start_executing()
+
+for milestone in ["Architecture", "UI", "Logic", "Persistence", "Testing", "Delivery"]:
+    assert session.end_of_response_gate() == "continue"
+    session.complete_milestone(milestone)
+    print(session.dashboard())
+
+session.begin_verification()
+session.gate.check_all()
+session.finish()  # raises unless every box is checked
+assert session.machine.state == "DONE"
+```
+
+## Inputs, outputs
+
+- **Input:** a locked objective (the finished thing, not the artifact
+  type), milestones, constraints, pending decisions.
+- **Output:** a driven session — dashboard state, checkpoints with resume
+  tokens, and a DONE that actually means done. The package never writes
+  files; your harness owns persistence.
+
+## Worked examples
+
+Three in `examples/`, a stranger can follow all of them:
+
+1. `example-1-debate-simulator-walkthrough.md` — the full loop end to end
+   on a browser debate simulator (ported from the original skill, unchanged).
+2. `example-2-anti-patterns.md` — before/after pairs: artificial-stop
+   language vs. the corrected continuation (ported, unchanged).
+3. `example-3-flashy-session.md` — the machinery itself: every
+   transition, gate, and checkpoint shown as the code enforces it. Run
+   `demo_session.py` to watch it execute.
+
+*All fields are constructed for teaching — they show the discipline's
+shape, not real findings.*
+
+## FAQ
+
+**Does this make the model smarter?** No. It makes it finish things.
+Execution discipline, not reasoning quality.
+
+**Does it need an internet connection?** No. No model calls at all — the
+41 unit tests and the demo run fully offline.
+
+**What does it cost?** Nothing. Free, dependency-free, offline.
+
+**When should it *not* fire?** Trivial tasks (a single short answer),
+genuine user decisions pending, safety constraints, or real platform
+limits. Never deactivate because a response "feels long enough."
+
+## License
+
+MIT. See LICENSE.

frontface_flashy-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "frontface-flashy"
+version = "1.0.0"
+description = "Persistent execution discipline for long tasks: lock the objective, track milestones, detect drift and artificial stops, verify before done"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Ryan Wesley Hitchcock" }]
+keywords = ["execution", "task-management", "state-machine", "agents", "workflow"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/ohpersonperson/frontface"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

frontface_flashy-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

frontface_flashy-1.0.0/src/flashy/__init__.py

@@ -0,0 +1,42 @@
+"""flashy — front-facing conversion of the flashy execution skill.
+
+Persistent execution discipline for long tasks: lock the objective,
+expand it into milestones, track live state, detect drift and artificial
+stopping points, checkpoint honestly on genuine limits, and gate
+completion on a quality checklist. A draft is not a delivery.
+
+No prerequisites. The mechanism is the whole product.
+See README.md for the plain-language version. See CHANGELOG.md for what
+was decoupled from the original skill.
+"""
+
+from . import checkpoints, detectors, quality_gate, session, state_machine
+from .checkpoints import (
+    Checkpoint, CheckpointError, make_resume_token, parse_resume_token,
+)
+from .detectors import (
+    ARTIFICIAL_STOP_PHRASES, PERMISSION_PHRASES, DRIFT_QUESTIONS,
+    DRIFT_CORRECTION, HIGH, MEDIUM, LOW, CONFIDENCE_LEVELS,
+    CONFIDENCE_GUIDANCE, DetectorError, detect_artificial_stop,
+    asks_permission_to_continue, should_pause, is_implementation_changing,
+)
+from .quality_gate import QualityGate, GateError, GATE_ITEMS
+from .session import MissionSession, Milestone
+from .state_machine import (
+    ExecutionStateMachine, TransitionError,
+    LOCKED, PLANNING, EXECUTING, VERIFYING, DONE, BLOCKED,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "checkpoints", "detectors", "quality_gate", "session", "state_machine",
+    "Checkpoint", "CheckpointError", "make_resume_token", "parse_resume_token",
+    "ARTIFICIAL_STOP_PHRASES", "PERMISSION_PHRASES", "DRIFT_QUESTIONS",
+    "DRIFT_CORRECTION", "HIGH", "MEDIUM", "LOW", "CONFIDENCE_LEVELS",
+    "CONFIDENCE_GUIDANCE", "DetectorError", "detect_artificial_stop",
+    "asks_permission_to_continue", "should_pause", "is_implementation_changing",
+    "QualityGate", "GateError", "GATE_ITEMS",
+    "MissionSession", "Milestone",
+    "ExecutionStateMachine", "TransitionError",
+    "LOCKED", "PLANNING", "EXECUTING", "VERIFYING", "DONE", "BLOCKED",
+]

frontface_flashy-1.0.0/src/flashy/checkpoints.py

@@ -0,0 +1,195 @@
+"""Checkpoints and resume tokens: honest "not done yet" state.
+
+A checkpoint is emitted only on a genuine limit — a context/length limit,
+a session or tool interruption, or a low-confidence blocker with no safe
+default. Never on fatigue, never on "this section feels done," never as a
+soft way to stop early.
+
+The resume token is a short, copy-pasteable pointer, not a cryptographic
+token: `finish:<slug>-m<N>` (package:slug-milestoneIndex). Quoting it on
+resume must let the session reconstruct where things stood from the
+checkpoint block alone.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass, field
+
+TOKEN_RE = re.compile(r"^finish:([a-z0-9][a-z0-9-]*)-m(\d+)$")
+
+
+class CheckpointError(ValueError):
+    """A malformed checkpoint or resume token."""
+
+
+def make_resume_token(slug: str, milestone_index: int) -> str:
+    """Build a resume token like `finish:debate-sim-m3`."""
+    slug = slug.strip().lower().replace(" ", "-")
+    if not slug or milestone_index < 0:
+        raise CheckpointError("Resume token needs a slug and a non-negative index.")
+    return f"finish:{slug}-m{milestone_index}"
+
+
+def parse_resume_token(token: str) -> tuple[str, int]:
+    """Split a resume token into (slug, milestone_index). Validates format."""
+    m = TOKEN_RE.match(token.strip())
+    if not m:
+        raise CheckpointError(
+            f"Malformed resume token: {token!r}. Expected finish:<slug>-m<N>."
+        )
+    return m.group(1), int(m.group(2))
+
+
+@dataclass
+class Checkpoint:
+    objective: str
+    done: list[str] = field(default_factory=list)
+    current: str = ""
+    remaining: list[str] = field(default_factory=list)
+    next_action: str = ""
+    resume_token: str = ""
+    blockers: list[str] = field(default_factory=list)
+    # PARAM-FLASHY-004: SHA-256 binding over the content fields, stamped at
+    # write time. resume() verifies it; a mismatch aborts the resume.
+    digest: str = ""
+    # Set only via resume(allow_manual_edit=True): the operator explicitly
+    # acknowledged a hand edit. Rendered into the block so the override is
+    # visible, never silent. Excluded from the digest input.
+    manual_edit_override: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.objective.strip():
+            raise CheckpointError("A checkpoint needs the locked objective.")
+        if not self.resume_token.strip():
+            raise CheckpointError("A checkpoint needs a resume token.")
+        parse_resume_token(self.resume_token)  # validate format now
+        if not self.digest:
+            self.digest = self._compute_digest()
+
+    def _compute_digest(self) -> str:
+        """SHA-256 over the canonical content payload.
+
+        Covers objective, done-list, and core state. The resume token is a
+        pointer, not content; the digest itself and the override flag are
+        resume-act metadata — all three are excluded.
+        """
+        payload = json.dumps(
+            {
+                "objective": self.objective,
+                "done": list(self.done),
+                "current": self.current,
+                "remaining": list(self.remaining),
+                "next_action": self.next_action,
+                "blockers": list(self.blockers),
+            },
+            sort_keys=True,
+        )
+        return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+    def verify(self) -> None:
+        """Verify the checkpoint's content against its digest binding.
+
+        Raises CheckpointError on a missing digest (predates binding) or a
+        mismatch (content modified after the checkpoint was written).
+        """
+        if not self.digest:
+            raise CheckpointError(
+                "Checkpoint carries no digest — it predates digest binding "
+                "and cannot be integrity-verified. Re-emit the checkpoint "
+                "to bind it."
+            )
+        if self.digest != self._compute_digest():
+            raise CheckpointError(
+                "Checkpoint digest mismatch: the content was modified after "
+                "the checkpoint was written. Resume aborted — re-verify the "
+                "checkpoint, or resume with allow_manual_edit=True to "
+                "acknowledge the hand edit explicitly."
+            )
+
+    @classmethod
+    def resume(cls, text: str, *, allow_manual_edit: bool = False) -> "Checkpoint":
+        """Parse a checkpoint block and verify its digest binding.
+
+        Returns the reconstructed Checkpoint. On digest mismatch the resume
+        aborts with CheckpointError — unless allow_manual_edit=True, in
+        which case the checkpoint is returned with manual_edit_override set
+        (the override is rendered into the block, never silent).
+        """
+        cp = cls.parse(text)
+        if not cp.digest:
+            # Pre-binding block: no write-time attestation exists. The
+            # bypass is for acknowledged hand edits (digest mismatch), not
+            # for unverifiable provenance — refuse outright, no override.
+            raise CheckpointError(
+                "Checkpoint carries no digest — it predates digest binding "
+                "and cannot be integrity-verified. Re-emit the checkpoint "
+                "to bind it."
+            )
+        try:
+            cp.verify()
+        except CheckpointError:
+            if not allow_manual_edit:
+                raise
+            cp.manual_edit_override = True
+        return cp
+
+    def render(self) -> str:
+        lines = [
+            "FLASHY CHECKPOINT",
+            f"OBJECTIVE  -> {self.objective}",
+            f"DONE       -> {', '.join(self.done) if self.done else '(none yet)'}",
+            f"CURRENT    -> {self.current or '(not started)'}",
+            f"REMAINING  -> {', '.join(self.remaining) if self.remaining else '(none)'}",
+            f"NEXT       -> {self.next_action or '(none recorded)'}",
+            f"RESUME     -> {self.resume_token}",
+            f"DIGEST     -> {self.digest}",
+        ]
+        if self.blockers:
+            lines.append(f"BLOCKERS   -> {', '.join(self.blockers)}")
+        if self.manual_edit_override:
+            lines.append("OVERRIDE   -> manual edit acknowledged by operator")
+        lines.append("")
+        lines.append("Continuing...")
+        return "\n".join(lines)
+
+    @classmethod
+    def parse(cls, text: str) -> "Checkpoint":
+        """Parse a rendered checkpoint back. Raises CheckpointError on bad input."""
+        if "FLASHY CHECKPOINT" not in text:
+            raise CheckpointError("Not a Flashy checkpoint.")
+        fields: dict[str, str] = {}
+        for line in text.splitlines():
+            if "->" in line:
+                key, _, value = line.partition("->")
+                fields[key.strip()] = value.strip()
+
+        def split_list(value: str) -> list[str]:
+            value = value.strip()
+            if not value or value in ("(none yet)", "(none)"):
+                return []
+            return [p.strip() for p in value.split(",") if p.strip()]
+
+        try:
+            cp = cls(
+                objective=fields["OBJECTIVE"],
+                done=split_list(fields.get("DONE", "")),
+                current="" if fields.get("CURRENT") == "(not started)" else fields.get("CURRENT", ""),
+                remaining=split_list(fields.get("REMAINING", "")),
+                next_action="" if fields.get("NEXT") == "(none recorded)" else fields.get("NEXT", ""),
+                resume_token=fields["RESUME"],
+                blockers=split_list(fields.get("BLOCKERS", "")),
+                digest=fields.get("DIGEST", ""),
+                manual_edit_override="OVERRIDE" in fields,
+            )
+        except KeyError as exc:
+            raise CheckpointError(f"Checkpoint missing field: {exc}") from exc
+        if not fields.get("DIGEST"):
+            # Pre-binding block: __post_init__ computed a fresh digest, but
+            # no write-time attestation exists — clear it so verify()
+            # refuses explicitly instead of blessing content that was never
+            # bound.
+            cp.digest = ""
+        return cp