frontface-flashy 1.0.0__py3-none-any.whl

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",
+]

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

flashy/detectors.py

@@ -0,0 +1,111 @@
+"""Detectors: artificial stops, drift, and the confidence engine.
+
+Two of these are data plus small functions; the third is a discipline the
+package makes explicit rather than automatic.
+
+- Artificial-stop detection is genuinely codeable: the phrases are a fixed
+  list, and matching them in output text is a string scan.
+- Drift detection is four questions, not a function — the package carries
+  the questions and the snap-back rule; the judgment call stays with the
+  operator (human or agent).
+- The confidence engine is three levels with a hard rule: High and Medium
+  never block; only Low pauses, and only for decisions that materially
+  change the implementation.
+"""
+
+from __future__ import annotations
+
+# Phrases that signal an artificial stop — an execution failure unless a
+# genuine limit (context window, missing info, missing permission, safety)
+# forces them. Ported verbatim from the original skill's list.
+ARTIFICIAL_STOP_PHRASES = (
+    "here's a starting point",
+    "here's a foundation",
+    "this should get you started",
+    "you can expand this",
+    "you can build upon this",
+    "build upon this",
+    "the rest follows similarly",
+    "due to space",
+    "here's part 1",
+)
+
+# Permission-to-continue phrases: not valid stopping points. The default
+# assumption is to continue unless genuinely blocked.
+PERMISSION_PHRASES = (
+    "continue?",
+    "should i keep going?",
+    "want more?",
+    "need anything else?",
+    "shall i finish?",
+)
+
+
+def detect_artificial_stop(text: str) -> list[str]:
+    """Return the artificial-stop phrases found in the text (case-insensitive)."""
+    lowered = text.lower()
+    return [p for p in ARTIFICIAL_STOP_PHRASES if p in lowered]
+
+
+def asks_permission_to_continue(text: str) -> list[str]:
+    """Return permission-to-continue phrases found (also not valid stops)."""
+    lowered = text.lower()
+    return [p for p in PERMISSION_PHRASES if p in lowered]
+
+
+# The four drift questions, run after every milestone and whenever output
+# starts feeling like explanation instead of building.
+DRIFT_QUESTIONS = (
+    "Am I still solving the original problem?",
+    "Have I wandered into explanation instead of building?",
+    "Did I forget earlier requirements?",
+    "Would the user consider this actually finished?",
+)
+
+#: The snap-back rule, stated once so every consumer applies it identically.
+DRIFT_CORRECTION = (
+    "On drift: discard the drifted thread, restate the locked objective, "
+    "resume from the last verified milestone. Correct and continue — no apology theater."
+)
+
+# --- Confidence engine --------------------------------------------------------
+
+HIGH = "high"
+MEDIUM = "medium"
+LOW = "low"
+CONFIDENCE_LEVELS = (HIGH, MEDIUM, LOW)
+
+CONFIDENCE_GUIDANCE = {
+    HIGH: "One reasonable interpretation, low cost if wrong — proceed silently.",
+    MEDIUM: "Multiple reasonable interpretations, but cheap/reversible to redo — "
+            "proceed, state the assumption inline, don't block on it.",
+    LOW: "Materially different deliverables result, or it is expensive/irreversible — "
+         "pause and ask. This is the ONLY legitimate pause trigger.",
+}
+
+
+class DetectorError(ValueError):
+    """An invalid confidence level or detector input."""
+
+
+def should_pause(confidence: str) -> bool:
+    """Only Low confidence pauses — and only for implementation-changing decisions."""
+    if confidence not in CONFIDENCE_LEVELS:
+        raise DetectorError(f"Confidence must be one of {CONFIDENCE_LEVELS}.")
+    return confidence == LOW
+
+
+def is_implementation_changing(decision: str) -> bool:
+    """Heuristic: does this decision materially change the implementation?
+
+    Examples that do: choice of database/language/framework, deployment
+    target, a required API key or credential, an ambiguity where two
+    reasonable interpretations produce meaningfully different deliverables.
+    The package can't decide this for you — this helper documents the
+    bar so callers apply it consistently.
+    """
+    markers = (
+        "database", "framework", "language", "deploy", "api key",
+        "credential", "infrastructure", "architecture",
+    )
+    return any(m in decision.lower() for m in markers)

flashy/ledger.py

@@ -0,0 +1,132 @@
+"""Append-only local ledger. Vendored per tool; stdlib only.
+
+CANONICAL COPY: edit this file, then re-vendor with vendor.sh.
+Do not edit the vendored copies in place.
+
+Privacy rule (non-negotiable): the ledger NEVER stores raw input text.
+Records carry SHA-256 digests of inputs plus structural summaries
+(counts, verdicts, deltas). What happened, and what kind — never the words.
+
+Location: ~/.frontface/<tool>/ledger.jsonl
+  override: FRONTFACE_LEDGER_DIR=<dir>   (ledgers go to <dir>/<tool>/)
+  disable:  FRONTFACE_NO_LEDGER=1         (record() becomes a silent no-op)
+
+The ledger must never break the tool it serves: record() swallows OSError
+and returns False instead of raising.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+try:
+    import fcntl
+except ImportError:  # pragma: no cover — Windows has no fcntl
+    fcntl = None  # type: ignore[assignment]
+
+
+def _base_dir() -> str:
+    return os.environ.get("FRONTFACE_LEDGER_DIR") or os.path.join(
+        os.path.expanduser("~"), ".frontface"
+    )
+
+
+def _disabled() -> bool:
+    return os.environ.get("FRONTFACE_NO_LEDGER") == "1"
+
+
+class Ledger:
+    """One JSONL ledger per tool. Cheap to construct; construct per use."""
+
+    def __init__(self, tool: str) -> None:
+        self.tool = tool
+        self.dir = os.path.join(_base_dir(), tool)
+        self.path = os.path.join(self.dir, "ledger.jsonl")
+
+    @property
+    def version(self) -> str:
+        """The owning package's __version__, resolved lazily."""
+        try:
+            pkg = sys.modules.get(__package__ or "")
+            return str(getattr(pkg, "__version__", "unknown"))
+        except Exception:
+            return "unknown"
+
+    @staticmethod
+    def digest(text: str) -> str:
+        return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+    def record(
+        self,
+        event: str,
+        summary: dict,
+        *,
+        input_text: str | None = None,
+    ) -> bool:
+        """Append one record. Returns False when disabled or on I/O error.
+
+        Never raises. Never stores raw input text — only its digest.
+        """
+        if _disabled():
+            return False
+        rec: dict = {
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "tool": self.tool,
+            "tool_version": self.version,
+            "event": event,
+            "summary": summary,
+        }
+        if input_text is not None:
+            rec["input_digest"] = self.digest(input_text)
+        try:
+            os.makedirs(self.dir, exist_ok=True)
+            with open(self.path, "a", encoding="utf-8") as f:
+                if fcntl is not None:
+                    fcntl.flock(f, fcntl.LOCK_EX)
+                    try:
+                        f.write(json.dumps(rec) + "\n")
+                        f.flush()
+                        os.fsync(f.fileno())
+                    finally:
+                        fcntl.flock(f, fcntl.LOCK_UN)
+                else:
+                    f.write(json.dumps(rec) + "\n")
+        except OSError:
+            return False
+        return True
+
+    def read(self, limit: int | None = None) -> list[dict]:
+        """All records, oldest first. Empty list when there's no ledger."""
+        try:
+            with open(self.path, encoding="utf-8") as f:
+                lines = f.read().splitlines()
+        except OSError:
+            return []
+        recs = []
+        for line in lines:
+            line = line.strip()
+            if line:
+                try:
+                    recs.append(json.loads(line))
+                except ValueError:
+                    continue  # never let a corrupt line kill the read
+        return recs[-limit:] if limit else recs
+
+    def summary(self) -> dict:
+        """Counts by event plus first/last timestamps."""
+        recs = self.read()
+        by_event: dict[str, int] = {}
+        for r in recs:
+            ev = str(r.get("event", "?"))
+            by_event[ev] = by_event.get(ev, 0) + 1
+        return {
+            "tool": self.tool,
+            "records": len(recs),
+            "events": by_event,
+            "first": recs[0]["ts"] if recs else None,
+            "last": recs[-1]["ts"] if recs else None,
+        }

flashy/quality_gate.py

@@ -0,0 +1,51 @@
+"""The Quality Gate: the launch checklist that guards VERIFYING -> DONE.
+
+There is no partial credit. Every box checked or the task is not done —
+status stays IN PROGRESS, not "mostly done."
+"""
+
+from __future__ import annotations
+
+GATE_ITEMS = (
+    "Everything requested exists",
+    "Everything builds/holds together logically",
+    "Nothing obvious is missing",
+    "No placeholder implementations remain",
+    "No TODOs remain",
+    "No incomplete sections remain",
+    "No artificial stopping points remain",
+)
+
+
+class GateError(ValueError):
+    """An unknown gate item was referenced."""
+
+
+class QualityGate:
+    """Seven boxes. Check them all or stay in VERIFYING."""
+
+    def __init__(self) -> None:
+        self._boxes: dict[str, bool] = {item: False for item in GATE_ITEMS}
+
+    def check(self, item: str) -> None:
+        if item not in self._boxes:
+            raise GateError(f"Unknown gate item: {item!r}")
+        self._boxes[item] = True
+
+    def uncheck(self, item: str) -> None:
+        if item not in self._boxes:
+            raise GateError(f"Unknown gate item: {item!r}")
+        self._boxes[item] = False
+
+    def all_checked(self) -> bool:
+        return all(self._boxes.values())
+
+    def missing(self) -> list[str]:
+        return [item for item, checked in self._boxes.items() if not checked]
+
+    def check_all(self) -> None:
+        for item in self._boxes:
+            self._boxes[item] = True
+
+    def status(self) -> str:
+        return "DONE" if self.all_checked() else "IN PROGRESS"

flashy/session.py

@@ -0,0 +1,181 @@
+"""Mission session: the objective, its milestones, and the live dashboard.
+
+A session binds the three codeable pieces together — the state machine,
+the quality gate, and checkpoints — around one locked objective. It also
+carries the mission dashboard (objective / now / done / next / blockers)
+and the end-of-response gate: a response ending is not a task ending.
+
+Mission rule: a draft is not a delivery. Completion is measured by whether
+the user actually received the usable thing they asked for.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .checkpoints import Checkpoint, make_resume_token
+from .ledger import Ledger
+from .quality_gate import QualityGate
+from .state_machine import (
+    BLOCKED, DONE, EXECUTING, LOCKED, PLANNING, VERIFYING,
+    ExecutionStateMachine, TransitionError,
+)
+
+PENDING = "pending"
+ACTIVE = "active"
+MILESTONE_DONE = "done"
+DESCOPED = "descoped"
+
+
+@dataclass
+class Milestone:
+    name: str
+    status: str = PENDING
+
+    def __post_init__(self) -> None:
+        if not self.name.strip():
+            raise TransitionError("Milestones need names.")
+        if self.status not in (PENDING, ACTIVE, MILESTONE_DONE, DESCOPED):
+            raise TransitionError(f"Bad milestone status: {self.status!r}")
+
+
+class MissionSession:
+    """One locked objective, driven through the state machine to DONE."""
+
+    def __init__(self, objective: str, *, slug: str,
+                 implicit_quality_bar: str = "",
+                 scope_boundaries: str = "") -> None:
+        self.machine = ExecutionStateMachine(objective)
+        self.slug = slug
+        self.implicit_quality_bar = implicit_quality_bar
+        self.scope_boundaries = scope_boundaries
+        self.milestones: list[Milestone] = []
+        self.gate = QualityGate()
+        self.constraints: list[str] = []
+        self.pending_decisions: list[str] = []
+        self.risks: list[str] = []
+        self._ledger = Ledger("flashy")
+        self._ledger.record("session_start", {"slug": slug},
+                            input_text=objective)
+
+    # -- planning -----------------------------------------------------------
+
+    def plan(self, milestones: list[str]) -> None:
+        """Expand the objective into milestones and enter PLANNING."""
+        if self.machine.state != LOCKED:
+            raise TransitionError("plan() runs once, from LOCKED.")
+        self.milestones = [Milestone(name=m) for m in milestones]
+        if self.milestones:
+            self.milestones[0].status = ACTIVE
+        self.machine.transition(PLANNING)
+
+    def start_executing(self) -> None:
+        self.machine.transition(EXECUTING)
+
+    # -- execution ----------------------------------------------------------
+
+    @property
+    def current_milestone(self) -> Milestone | None:
+        for m in self.milestones:
+            if m.status == ACTIVE:
+                return m
+        return None
+
+    def complete_milestone(self, name: str) -> None:
+        """Mark a milestone done and advance to the next pending one."""
+        target = next((m for m in self.milestones if m.name == name), None)
+        if target is None:
+            raise TransitionError(f"Unknown milestone: {name!r}")
+        target.status = MILESTONE_DONE
+        nxt = next((m for m in self.milestones if m.status == PENDING), None)
+        if nxt is not None:
+            nxt.status = ACTIVE
+        self._ledger.record(
+            "milestone",
+            {"slug": self.slug,
+             "completed": len(self.completed()),
+             "remaining": len(self.remaining())},
+            input_text=name,
+        )
+
+    def descope(self, name: str) -> None:
+        """Explicit user descope only — milestones never silently shrink."""
+        target = next((m for m in self.milestones if m.name == name), None)
+        if target is None:
+            raise TransitionError(f"Unknown milestone: {name!r}")
+        target.status = DESCOPED
+        nxt = next((m for m in self.milestones if m.status == PENDING), None)
+        if nxt is not None and self.current_milestone is None:
+            nxt.status = ACTIVE
+        self._ledger.record(
+            "descope",
+            {"slug": self.slug,
+             "completed": len(self.completed()),
+             "remaining": len(self.remaining())},
+            input_text=name,
+        )
+
+    def remaining(self) -> list[str]:
+        return [m.name for m in self.milestones
+                if m.status in (PENDING, ACTIVE)]
+
+    def completed(self) -> list[str]:
+        return [m.name for m in self.milestones if m.status == MILESTONE_DONE]
+
+    # -- dashboard ----------------------------------------------------------
+
+    def dashboard(self) -> str:
+        """The compact mission dashboard, refreshed after every milestone."""
+        current = self.current_milestone
+        lines = [
+            f"OBJECTIVE  -> {self.machine.objective}",
+            f"NOW        -> {current.name if current else '(none — all milestones resolved)'}",
+            f"DONE       -> {', '.join(self.completed()) or '(none yet)'}",
+            f"NEXT       -> {self.next_action()}",
+            f"BLOCKERS   -> {', '.join(self.pending_decisions) or 'none'}",
+        ]
+        return "\n".join(lines)
+
+    def next_action(self) -> str:
+        current = self.current_milestone
+        if current:
+            return f"Continue: {current.name}"
+        if self.remaining():
+            return f"Continue: {self.remaining()[0]}"
+        return "Verify against the Quality Gate"
+
+    # -- end-of-response gate -----------------------------------------------
+
+    def end_of_response_gate(self) -> str:
+        """A response ending is not a task ending. Returns the verdict:
+
+        - "verify" — no milestones remain; run the Quality Gate.
+        - "continue" — useful progress can still be made; keep executing.
+        - "checkpoint" — genuinely blocked; emit a checkpoint.
+        """
+        if self.machine.state == BLOCKED:
+            return "checkpoint"
+        if not self.remaining():
+            return "verify"
+        return "continue"
+
+    def checkpoint(self, milestone_index: int) -> Checkpoint:
+        """Emit an honest checkpoint for a genuine limit. Never a soft stop."""
+        return Checkpoint(
+            objective=self.machine.objective,
+            done=self.completed(),
+            current=self.current_milestone.name if self.current_milestone else "",
+            remaining=self.remaining(),
+            next_action=self.next_action(),
+            resume_token=make_resume_token(self.slug, milestone_index),
+            blockers=list(self.pending_decisions),
+        )
+
+    # -- verification -------------------------------------------------------
+
+    def begin_verification(self) -> None:
+        self.machine.transition(VERIFYING)
+
+    def finish(self) -> None:
+        """VERIFYING -> DONE. Raises unless every Quality Gate box is checked."""
+        self.machine.transition(DONE, quality_gate=self.gate)

flashy/state_machine.py

@@ -0,0 +1,117 @@
+"""The execution state machine: the one codeable core of Flashy.
+
+States: LOCKED -> PLANNING -> EXECUTING -> VERIFYING -> DONE, with BLOCKED
+reachable from EXECUTING or VERIFYING. The rules are the point — they are
+what stops a long task from quietly degrading into "here's a starting
+point":
+
+- VERIFYING -> DONE is forbidden unless every Quality Gate box is checked.
+- EXECUTING -> PLANNING is forbidden without an explicit, user-driven
+  scope change. Silent re-planning is how objectives get replaced.
+- BLOCKED -> EXECUTING is forbidden until a checkpoint has been emitted.
+  A blocked session that resumes with no checkpoint is a session that
+  forgot where it was.
+- DONE is terminal. Nothing transitions out of DONE.
+"""
+
+from __future__ import annotations
+
+LOCKED = "LOCKED"
+PLANNING = "PLANNING"
+EXECUTING = "EXECUTING"
+VERIFYING = "VERIFYING"
+DONE = "DONE"
+BLOCKED = "BLOCKED"
+
+STATES = (LOCKED, PLANNING, EXECUTING, VERIFYING, DONE, BLOCKED)
+
+_ALLOWED = {
+    LOCKED: {PLANNING},
+    PLANNING: {EXECUTING},
+    EXECUTING: {VERIFYING, BLOCKED, PLANNING},
+    VERIFYING: {DONE, EXECUTING, BLOCKED},
+    BLOCKED: {EXECUTING},
+    DONE: set(),
+}
+
+
+class TransitionError(ValueError):
+    """An illegal state transition was attempted."""
+
+
+class ExecutionStateMachine:
+    """Tracks one task's execution state and enforces the transition rules."""
+
+    def __init__(self, objective: str) -> None:
+        if not objective.strip():
+            raise TransitionError("An execution state machine needs a locked objective.")
+        self.objective = objective
+        self.state = LOCKED
+        self.history: list[tuple[str, str]] = [(LOCKED, "objective locked")]
+        self._checkpoint_emitted = False
+        self._block_reason = ""
+
+    def transition(self, target: str, *, scope_change: bool = False,
+                   quality_gate: object | None = None) -> str:
+        """Move to a new state, enforcing the rules. Returns the new state."""
+        if target not in STATES:
+            raise TransitionError(f"Unknown state: {target!r}")
+        if target not in _ALLOWED[self.state]:
+            raise TransitionError(
+                f"Illegal transition: {self.state} -> {target}. "
+                f"Allowed: {sorted(_ALLOWED[self.state]) or 'none (terminal)'}."
+            )
+        if self.state == EXECUTING and target == PLANNING and not scope_change:
+            raise TransitionError(
+                "EXECUTING -> PLANNING requires an explicit user-driven scope "
+                "change (scope_change=True). Silent re-planning is how the "
+                "objective gets replaced."
+            )
+        if self.state == VERIFYING and target == DONE:
+            gate = quality_gate
+            if gate is None or not gate.all_checked():
+                missing = (
+                    gate.missing() if gate is not None else ["no quality gate supplied"]
+                )
+                raise TransitionError(
+                    "VERIFYING -> DONE requires every Quality Gate box checked. "
+                    f"Missing: {missing}."
+                )
+        if self.state == BLOCKED and target == EXECUTING:
+            if not self._checkpoint_emitted:
+                raise TransitionError(
+                    "BLOCKED -> EXECUTING requires a checkpoint to have been "
+                    "emitted first. Call emit_checkpoint() (see checkpoints.py)."
+                )
+            self._checkpoint_emitted = False  # checkpoint consumed by the resume
+
+        reason = ""
+        if target == BLOCKED:
+            reason = "blocked"
+        self.state = target
+        self.history.append((target, reason))
+        return self.state
+
+    def block(self, reason: str) -> str:
+        """Enter BLOCKED with a recorded reason."""
+        if not reason.strip():
+            raise TransitionError("Blocking requires a stated reason.")
+        self._block_reason = reason
+        return self.transition(BLOCKED)
+
+    def emit_checkpoint(self) -> None:
+        """Record that a checkpoint was emitted (see checkpoints.py).
+
+        The checkpoint content itself lives in checkpoints.py; the machine
+        only tracks that one was emitted, which unblocks BLOCKED -> EXECUTING.
+        """
+        self._checkpoint_emitted = True
+        self.history.append((self.state, "checkpoint emitted"))
+
+    @property
+    def block_reason(self) -> str:
+        return self._block_reason
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.state == DONE

frontface_flashy-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+flashy/__init__.py,sha256=1GqoxTAW-BSBO1l48QLknm6KyOee4Mhi9HqI4lbsIS0,1905
+flashy/checkpoints.py,sha256=VJUUPnO-JZqAdWXEQhvauWVQR7hwnOQB3RReOdZq50s,8104
+flashy/detectors.py,sha256=Q7Xx7AFNA6v9Q5xduNUzn4ZnsKZqxWLybxI6oByFwUU,4195
+flashy/ledger.py,sha256=x8TH2et1Jt_UTzLMn49R8YKEiMMykYTW6UoMz-l8qCU,4245
+flashy/quality_gate.py,sha256=R_fwlD7fA4chJgIH_kdnPiLBmiW1zjgZLRZuP0OC7lk,1519
+flashy/session.py,sha256=PeoaLJQ72NgAFAJ6TQ-K38PIN4GsZWUU67GITyqRVtg,6974
+flashy/state_machine.py,sha256=9usEOmlREbh3KTdEEVaUil6KB6y-meyXwTiwlGS4uys,4489
+frontface_flashy-1.0.0.dist-info/licenses/LICENSE,sha256=Zx_XafyZDq7qBexUb7tER9kYlBZ0rCVaAwKuqMCfxLE,1078
+frontface_flashy-1.0.0.dist-info/METADATA,sha256=u4hjfbr1598wz7ZqRhNCFR5kwfR31k_XYEWS_Sz9m8Q,7676
+frontface_flashy-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+frontface_flashy-1.0.0.dist-info/top_level.txt,sha256=XNKwp8CalkM3b9QQhFeWwm6Fo3_E_8OoX0euJi7DAXY,7
+frontface_flashy-1.0.0.dist-info/RECORD,,

frontface_flashy-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

frontface_flashy-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+flashy