code-factory-2-forge 0.6.0__py3-none-any.whl

forgeline/intent_thread.py

@@ -0,0 +1,76 @@
+"""The Intent Thread — end-to-end traceability from PRD to production.
+
+The breakthrough: SpecLine rationalizes intent into a sealed envelope
+(coherence + surfaced assumptions + hash). ForgeLine consumes that same
+envelope so the FINAL shipped code can be verified against the ORIGINAL
+intent — not the plan, not the spec-as-drifted, but the rationalized intent
+that was sealed at the plan gate.
+
+This closes the last translation-loss gap (implementation → validation):
+'does the shipped thing actually satisfy what we rationalized we wanted?'
+Every surfaced assumption becomes a checkable obligation; the sealed hash
+proves the intent hasn't been quietly swapped underneath the build.
+"""
+from __future__ import annotations
+import json, hashlib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+@dataclass
+class IntentTraceResult:
+    envelope_found: bool = False
+    intent_hash: str = ""
+    coherence_at_seal: int = 0
+    assumptions: list = field(default_factory=list)
+    unverified_assumptions: list = field(default_factory=list)
+    obligations_met: int = 0
+    obligations_total: int = 0
+    findings: list = field(default_factory=list)
+
+    @property
+    def traceable(self) -> bool:
+        return self.envelope_found and not self.unverified_assumptions
+
+def load_envelope(root: Path, feature: str) -> dict | None:
+    """Load the SpecLine intent envelope if present (cross-module seam)."""
+    for cand in [root/"envelopes"/f"{feature}.json",
+                 root.parent/"specline"/"envelopes"/f"{feature}.json"]:
+        if cand.exists():
+            return json.loads(cand.read_text())
+    return None
+
+def verify_against_intent(root: Path, feature: str, src_dir: Path) -> IntentTraceResult:
+    """Check shipped code honors the sealed intent's surfaced assumptions.
+    Each assumption becomes an obligation the code must visibly address."""
+    r = IntentTraceResult()
+    env = load_envelope(root, feature)
+    if not env:
+        r.findings.append("IT_NO_ENVELOPE: no sealed intent envelope — build is untraceable to a rationalized PRD.")
+        return r
+    r.envelope_found = True
+    r.intent_hash = env.get("sealed_hash", "")
+    r.coherence_at_seal = env.get("coherence_score", 0)
+    r.assumptions = env.get("assumptions", [])
+    r.obligations_total = len(r.assumptions)
+
+    # each surfaced assumption is an obligation — is it visibly addressed in code?
+    code_text = "\n".join(p.read_text() for p in Path(src_dir).rglob("*.py")).lower()
+    OBLIGATION_EVIDENCE = {
+        "auth":      ["auth", "login", "token", "session", "identity", "authenticate"],
+        "currency":  ["currency", "usd", "locale", "money", "decimal"],
+        "dependency":["retry", "timeout", "fallback", "except", "circuit", "backoff"],
+        "delivery":  ["retry", "bounce", "queue", "deliver", "ack", "confirm"],
+    }
+    for a in r.assumptions:
+        al = a.lower()
+        key = ("auth" if "auth" in al or "identity" in al else
+               "currency" if "currency" in al else
+               "dependency" if "dependency" in al or "availability" in al else
+               "delivery" if "delivery" in al else None)
+        evidence = OBLIGATION_EVIDENCE.get(key, [])
+        if evidence and any(e in code_text for e in evidence):
+            r.obligations_met += 1
+        else:
+            r.unverified_assumptions.append(a)
+            r.findings.append(f"IT_UNMET_ASSUMPTION: intent assumed — '{a[:70]}' — but code shows no handling.")
+    return r

forgeline/learning.py

@@ -0,0 +1,116 @@
+"""Recursive Learning Kernel — the flywheel that makes the factory improve
+itself. Distinct from skill_memory (which records lessons): this CLOSES THE
+LOOP by promoting recurring lessons into ACTIVE enforcement, tracking whether
+promoted rules actually reduce future failures, and DEMOTING rules that stop
+earning their keep. The factory's own run history becomes its QA policy.
+
+Three tiers, each a ratchet:
+  observe  -> a lesson is recorded (skill_memory)
+  promote  -> a lesson seen >= N times becomes an ACTIVE constraint (enforced)
+  validate -> a promoted constraint that prevents recurrence is KEPT; one that
+              never fires again (dead) or fires with no failures behind it is
+              reviewed. Effectiveness is measured, not assumed.
+"""
+from __future__ import annotations
+import json, datetime
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+POLICY = "skills/active_policy.json"
+HISTORY = "skills/learning_history.jsonl"
+
+def _now(): return datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+@dataclass
+class ActiveConstraint:
+    code: str                 # e.g. "A_EVAL"
+    rule: str                 # human-readable enforced rule
+    promoted_from_count: int  # how many observations triggered promotion
+    promoted_at: str
+    times_enforced: int = 0   # how often it has since blocked something
+    prevented_recurrence: int = 0  # times it caught the same failure again
+    status: str = "active"    # active | probation | retired
+
+class LearningKernel:
+    def __init__(self, root: Path, promote_threshold: int = 3):
+        self.root = Path(root)
+        self.threshold = promote_threshold
+        self.policy_path = self.root/POLICY
+        self.history_path = self.root/HISTORY
+        self.policy_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def _load_policy(self) -> dict:
+        if self.policy_path.exists():
+            return json.loads(self.policy_path.read_text())
+        return {"constraints": {}, "version": 0}
+
+    def _save_policy(self, p: dict):
+        p["version"] = p.get("version", 0) + 1
+        p["updated"] = _now()
+        self.policy_path.write_text(json.dumps(p, indent=2))
+
+    def _log(self, event: str, **f):
+        f.update({"ts": _now(), "event": event})
+        with self.history_path.open("a") as fh:
+            fh.write(json.dumps(f, sort_keys=True) + "\n")
+
+    def promote(self, lessons: list[dict]) -> list[str]:
+        """Tier 2: any lesson seen >= threshold becomes an active constraint.
+        Returns the codes newly promoted this cycle."""
+        policy = self._load_policy(); newly = []
+        for l in lessons:
+            code = l["failure_code"]
+            if l["count"] >= self.threshold and code not in policy["constraints"]:
+                c = ActiveConstraint(code=code, rule=l["fix"],
+                                     promoted_from_count=l["count"], promoted_at=_now())
+                policy["constraints"][code] = asdict(c)
+                newly.append(code)
+                self._log("promote", code=code, from_count=l["count"], rule=l["fix"])
+        if newly:
+            self._save_policy(policy)
+        return newly
+
+    def enforce(self, findings_codes: list[str]) -> dict:
+        """Tier 3 measurement: record which active constraints fired this run.
+        A constraint that catches its target failure again = validated (working).
+        Returns {code: prevented_bool} for constraints that were relevant."""
+        policy = self._load_policy(); result = {}
+        for code in findings_codes:
+            if code in policy["constraints"]:
+                c = policy["constraints"][code]
+                c["times_enforced"] += 1
+                c["prevented_recurrence"] += 1
+                result[code] = True
+                self._log("enforce", code=code, prevented=True)
+        if result:
+            self._save_policy(policy)
+        return result
+
+    def audit_effectiveness(self, recent_run_count: int = 20) -> dict:
+        """Recursive review: constraints that keep catching real failures are
+        VALIDATED; ones promoted long ago that never fire go to PROBATION
+        (candidate for retirement — the policy self-prunes)."""
+        policy = self._load_policy()
+        validated, probation = [], []
+        for code, c in policy["constraints"].items():
+            if c["status"] == "retired":
+                continue
+            if c["prevented_recurrence"] >= 1:
+                c["status"] = "active"; validated.append(code)
+            elif c["times_enforced"] == 0 and c["status"] == "active":
+                c["status"] = "probation"; probation.append(code)
+                self._log("probation", code=code, reason="never fired since promotion")
+        self._save_policy(policy)
+        return {"validated": validated, "probation": probation,
+                "total_active": sum(1 for c in policy["constraints"].values() if c["status"]=="active")}
+
+    def active_codes(self) -> list[str]:
+        policy = self._load_policy()
+        return [k for k,v in policy["constraints"].items() if v["status"] in ("active","probation")]
+
+    def policy_summary(self) -> dict:
+        policy = self._load_policy()
+        return {"version": policy.get("version",0),
+                "constraints": {k: {"status": v["status"], "enforced": v["times_enforced"],
+                                    "prevented": v["prevented_recurrence"]}
+                                for k,v in policy["constraints"].items()}}

forgeline/orchestrator.py

@@ -0,0 +1,263 @@
+"""The outer loop. Advances the state machine, calling SpecLine for spec/plan
+governance and HSF for decision compilation when a spec carries a decision
+table. Everything is a receipt; every gate failure records a skill lesson and
+routes to the refine loop."""
+from __future__ import annotations
+import shutil, subprocess, sys
+from pathlib import Path
+from .states import State, can_transition, IllegalTransition, HUMAN_GATES
+from .run_store import RunStore
+from .ssat import load_ssat, scaffold_from_ssat, check_erosion
+from .gates import judge_consistency, grumpy_review, skill_check
+from .gates.qa_audit import qa_audit
+from .skill_memory import record_lesson, inject_lessons_block, lessons_for
+from .learning import LearningKernel
+from .attribution import Attribution, FailureClass, UnitResult
+
+MAX_REFINE = 3
+
+
+def _gate_attribution(stage: str, checks: list[tuple[str, bool, str, FailureClass]]) -> dict:
+    units = [
+        UnitResult(
+            unit=f"{stage}:{name}",
+            stage=stage,
+            passed=passed,
+            evidence=evidence,
+            failure_class=None if passed else failure_class,
+        )
+        for name, passed, evidence, failure_class in checks
+    ]
+    return Attribution(stage, len(units), sum(unit.passed for unit in units), units).to_dict()
+
+class Orchestrator:
+    def __init__(self, root: Path, feature: str):
+        self.root = Path(root); self.feature = feature
+        self.store = RunStore(self.root, feature)
+
+    def _advance(self, to: State, note: str = "", **receipt):
+        frm = self.store.state
+        if not can_transition(frm, to):
+            raise IllegalTransition(f"{frm.value} -> {to.value}")
+        self.store.set_state(to, note)
+        self.store.receipt(transition=f"{frm.value}->{to.value}", **receipt)
+
+    def architect(self, ssat_path: Path) -> dict:
+        ssat = load_ssat(ssat_path)
+        created = scaffold_from_ssat(ssat, self.root)
+        self._advance(State.SCAFFOLDED, "scaffold from SSAT",
+                      modules=len(ssat.get("modules", [])), files=[str(c) for c in created])
+        return {"scaffolded": [str(c) for c in created]}
+
+    def review(self, ssat_path: Path) -> dict:
+        """Judge + grumpy adversary + arch erosion + deep QA audit, with a
+        recursive learning kernel and escalating refine loop."""
+        ssat = load_ssat(ssat_path)
+        attempt = self.store.bump_attempt("review")
+        kernel = LearningKernel(self.root)
+        j_ok, j = judge_consistency(ssat, self.root)
+        g_ok, g = grumpy_review(self.root)
+        erosion = check_erosion(ssat, self.root)
+        qa = qa_audit(self.root)                       # STRICTER: quantitative QA grade
+        all_findings = j + g + [f"{v.code} {v.message}" for v in erosion] + qa.findings
+        all_ok = j_ok and g_ok and not erosion and qa.passed
+        review_attr = _gate_attribution("review", [
+            ("judge", j_ok, "consistent" if j_ok else " | ".join(j),
+             FailureClass.INCONSISTENT_LOGIC),
+            ("adversary", g_ok, "all probes resisted" if g_ok else " | ".join(g),
+             FailureClass.SECURITY_FINDING),
+            ("architecture", not erosion, "no erosion" if not erosion else
+             " | ".join(f"{v.code} {v.message}" for v in erosion),
+             FailureClass.SIGNATURE_DRIFT),
+            ("qa_audit", qa.passed, f"grade={qa.grade}; metrics={qa.metrics}",
+             FailureClass.COMPLEXITY_EXCEEDED),
+        ])
+
+        # recursive learning: measure whether active constraints caught failures
+        codes = [f.split()[0].split("[")[0] for f in all_findings]
+        prevented = kernel.enforce(codes)
+
+        self.store.receipt(phase="review", attempt=attempt, judge_ok=j_ok,
+                           grumpy_ok=g_ok, erosion=len(erosion),
+                           qa_grade=qa.grade, qa_metrics=qa.metrics,
+                           active_constraints_fired=list(prevented.keys()),
+                           findings=all_findings, attribution=review_attr)
+        if all_ok:
+            self._advance(State.REVIEWED, f"review pass (attempt {attempt}, QA={qa.grade})")
+            return {"reviewed": True, "attempt": attempt, "qa_grade": qa.grade,
+                    "qa_metrics": qa.metrics, "attribution": review_attr}
+
+        # record lessons, then PROMOTE recurring ones into active policy (recursion)
+        for f in all_findings:
+            code = f.split()[0].split("[")[0]
+            record_lesson(self.root, phase="fill", failure_code=code, fix=f, feature=self.feature)
+        promoted = kernel.promote(lessons_for(self.root, "fill"))
+        kernel.audit_effectiveness()
+
+        if self.store.state != State.BLOCKED:
+            self._advance(State.BLOCKED, f"review failed (attempt {attempt}, QA={qa.grade})")
+
+        # ESCALATION: refine loop gets stricter each attempt
+        escalation = ("normal" if attempt == 1 else
+                      "elevated: fix ALL findings, not just blockers" if attempt == 2 else
+                      "final: exhausted — human review required" )
+        result = {"reviewed": False, "attempt": attempt, "qa_grade": qa.grade,
+                  "qa_metrics": qa.metrics, "findings": all_findings,
+                  "newly_promoted_constraints": promoted, "escalation": escalation,
+                  "lessons_for_next": inject_lessons_block(self.root, "fill"),
+                  "attribution": review_attr}
+        if attempt >= MAX_REFINE:
+            result["exhausted"] = True
+        return result
+
+    def arch_gate(self, ssat_path: Path) -> dict:
+        ssat = load_ssat(ssat_path)
+        erosion = check_erosion(ssat, self.root)
+        s_ok, s = skill_check(self.root, self.feature)
+        arch_attr = _gate_attribution("arch_gate", [
+            ("erosion", not erosion, "no architecture erosion" if not erosion else
+             " | ".join(f"{v.code} {v.message}" for v in erosion),
+             FailureClass.SIGNATURE_DRIFT),
+            ("skill_contract", s_ok, "skill contract valid" if s_ok else " | ".join(s),
+             FailureClass.INCONSISTENT_LOGIC),
+        ])
+        if erosion or not s_ok:
+            self.store.receipt(phase="arch_gate", passed=False,
+                               erosion=[f"{v.code} {v.message}" for v in erosion], skill=s,
+                               attribution=arch_attr)
+            if self.store.state != State.BLOCKED:
+                self._advance(State.BLOCKED, "arch gate failed")
+            return {"passed": False, "erosion": [f"{v.code} {v.message}" for v in erosion] + s,
+                    "attribution": arch_attr}
+        # must currently be REVIEWED to legally gate
+        if self.store.state == State.BLOCKED:
+            self.store.set_state(State.REVIEWED, "recovered for arch gate")
+        kernel = LearningKernel(self.root)
+        eff = kernel.audit_effectiveness()
+        self._advance(State.ARCH_GATED, "architecture CI gate passed")
+        self.store.receipt(phase="arch_gate", passed=True, learning=eff,
+                           active_policy=kernel.policy_summary(), attribution=arch_attr)
+        return {"passed": True, "learning": eff, "attribution": arch_attr}
+
+    def handoff_decisions(self, spec_path: Path) -> dict | None:
+        """If SpecLine + HSF are importable and the spec has a decision table,
+        compile decisions through the factory. Best-effort seam."""
+        try:
+            sys.path.insert(0, str(Path(__file__).resolve().parents[2]/"specline"))
+            from specline.spec_lint import decision_rows  # type: ignore
+        except Exception:
+            return None
+        rows = decision_rows(spec_path)
+        if not rows:
+            return None
+        self.store.receipt(phase="handoff", decision_rules=len(rows),
+                           note="decision table present — route to HSF compile")
+        return {"decision_rules": len(rows), "next": "hsf compile"}
+
+    def smoke_gate(self) -> dict:
+        """Runtime behavior verification — the behavior-by-inspection gate.
+        Runs the built artifact against declared behavioral checks (smoke/<feature>.json)
+        in isolated subprocesses. Blocks ship on any runtime failure. This is the
+        right-sized version of a per-PR preview deployment: verify the thing RUNS
+        and behaves, not just that it type-checks and honors the spec."""
+        from .gates.runtime_smoke import runtime_smoke, smoke_report_lines
+        if self.store.state == State.SHIPPED:
+            return {"smoked": True, "note": "already shipped"}
+        if self.store.state == State.SMOKED:
+            return {"smoked": True, "note": "already smoked"}
+        if self.store.state != State.TESTS_VERIFIED:
+            return {"smoked": False,
+                    "reason": "tests not verified - run `forge verify-tests` first"}
+        rep = runtime_smoke(self.root, self.feature)
+        gate = rep.gate_result
+        attr = gate.attribution.to_dict()
+        lines = smoke_report_lines(rep)
+        if not gate.passed:
+            self.store.receipt(phase="smoke_gate", smoked=False,
+                               manifest_found=rep.manifest_found,
+                               failures=[r.name for r in rep.failures],
+                               report=lines, attribution=attr)
+            # a runtime failure is a real defect -> block; refine loop owns recovery
+            self._advance(State.BLOCKED, "runtime smoke gate failed")
+            return {"smoked": False,
+                    "reason": ("no runtime behavior verified" if not rep.manifest_found
+                               else "runtime behavioral check(s) failed"),
+                    "failures": [f"{r.name}: {r.reason}" for r in rep.failures],
+                    "attribution": attr}
+        self._advance(State.SMOKED, "runtime behavior verified")
+        self.store.receipt(phase="smoke_gate", smoked=True,
+                           checks=len(rep.results), report=lines, attribution=attr)
+        return {"smoked": True, "checks": len(rep.results), "attribution": attr}
+
+    def verify_tests(self, ssat_path: Path) -> dict:
+        """Verify smoke checks can fail before trusting smoke results."""
+        from .gates.reverse_classical import verify_tests
+        if self.store.state == State.SHIPPED:
+            return {"verified": True, "note": "already shipped"}
+        if self.store.state in {State.TESTS_VERIFIED, State.SMOKED}:
+            return {"verified": True, "note": "already verified"}
+        if self.store.state not in {State.ARCH_GATED, State.BLOCKED}:
+            return {"verified": False,
+                    "reason": "architecture gate not passed - run `forge arch-gate` first"}
+        gate = verify_tests(self.root, self.feature, Path(ssat_path))
+        attr = gate.attribution.to_dict()
+        if not gate.passed:
+            self.store.receipt(phase="verify_tests", verified=False, attribution=attr)
+            if self.store.state != State.BLOCKED:
+                self._advance(State.BLOCKED, "reverse-classical test verification failed")
+            return {"verified": False,
+                    "reason": "hollow smoke check(s) found",
+                    "attribution": attr}
+        self._advance(State.TESTS_VERIFIED, "smoke checks proven non-hollow",
+                      attribution=attr)
+        self.store.receipt(phase="verify_tests", verified=True, attribution=attr)
+        return {"verified": True, "checks": gate.attribution.n_checked, "attribution": attr}
+
+    def refine(self, evaluate, propose, apply, revert, max_iters: int = 6) -> dict:
+        """Run deterministic localized refinement.
+
+        Callers may propose an edit, but exact Pareto acceptance and rollback are
+        controlled here. Learning state remains build-time only under `.forge/`.
+        """
+        from .refinement import refine
+        return refine(evaluate, propose, apply, revert, self.root, max_iters=max_iters)
+
+    def ship(self, verify_intent: bool = True) -> dict:
+        # ship now requires runtime behavior to have been verified
+        if self.store.state in {State.ARCH_GATED, State.TESTS_VERIFIED}:
+            return {"shipped": False, "reason": "runtime smoke gate not run - "
+                    "call smoke_gate() before ship (behavior must be verified)."}
+        trace = None
+        intent_attr = None
+        if verify_intent:
+            from .intent_thread import verify_against_intent
+            trace = verify_against_intent(self.root, self.feature, self.root)
+            intent_checks = [
+                (f"obligation_{index}", met, evidence, FailureClass.INCONSISTENT_LOGIC)
+                for index, (met, evidence) in enumerate(
+                    [(not trace.unverified_assumptions, finding)
+                     for finding in (trace.findings or ["intent obligations satisfied"])],
+                    1,
+                )
+            ]
+            intent_attr = _gate_attribution("intent_thread", intent_checks)
+            if trace.envelope_found and not trace.traceable:
+                # PRD->production gap: shipped code doesn't honor sealed intent
+                self.store.receipt(phase="ship", shipped=False,
+                                   intent_hash=trace.intent_hash,
+                                   unverified_assumptions=trace.unverified_assumptions,
+                                   findings=trace.findings, attribution=intent_attr)
+                if self.store.state != State.BLOCKED:
+                    self._advance(State.BLOCKED, "intent-traceability gap")
+                return {"shipped": False, "reason": "intent not honored by code",
+                        "unverified_assumptions": trace.unverified_assumptions,
+                        "findings": trace.findings}
+        self._advance(State.SHIPPED, "all gates green")
+        self.store.receipt(phase="ship", shipped=True,
+                           intent_hash=(trace.intent_hash if trace else None),
+                           obligations=f"{trace.obligations_met}/{trace.obligations_total}" if trace else None,
+                           attribution=intent_attr)
+        return {"shipped": True,
+                "intent_traceable": (trace.traceable if trace else None),
+                "obligations_met": (f"{trace.obligations_met}/{trace.obligations_total}" if trace else None),
+                "attribution": intent_attr}

forgeline/refinement.py

@@ -0,0 +1,76 @@
+"""Deterministic refinement policy: one edit, ordered, Pareto-gated, bounded."""
+from __future__ import annotations
+from dataclasses import asdict, dataclass
+from pathlib import Path
+import json
+
+from .attribution import FailureClass
+
+
+@dataclass(frozen=True)
+class Edit:
+    edit_class: str
+    target: str
+    description: str
+
+
+STRUCTURAL_FAILURES = {
+    FailureClass.SIGNATURE_DRIFT,
+    FailureClass.STUB_UNFILLED,
+    FailureClass.INCONSISTENT_LOGIC,
+    FailureClass.SCOPE_ESCAPE,
+    FailureClass.HOLLOW_TEST,
+    FailureClass.HOLLOW_MANIFEST,
+}
+
+
+def select_edit(failure_class: FailureClass) -> Edit:
+    edit_class = "structural" if failure_class in STRUCTURAL_FAILURES else (
+        "configuration" if failure_class in {
+            FailureClass.RUNTIME_CRASH, FailureClass.RUNTIME_TIMEOUT,
+            FailureClass.SECURITY_FINDING,
+        } else "parametric"
+    )
+    return Edit(edit_class, failure_class.value, f"localized {edit_class} correction")
+
+
+def pareto_win(current: dict[str, float], previous: dict[str, float], target: str) -> bool:
+    return (
+        current.get(target, 0.0) > previous.get(target, 0.0)
+        and all(current.get(stage, 0.0) >= rate for stage, rate in previous.items())
+    )
+
+
+class RejectionLedger:
+    def __init__(self, root: Path):
+        self.path = Path(root) / ".forge" / "rejection_ledger.jsonl"
+
+    def log(self, edit: Edit, before: dict, after: dict) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as stream:
+            stream.write(json.dumps({
+                "edit": asdict(edit), "before_rates": before, "after_rates": after,
+            }, sort_keys=True) + "\n")
+
+
+def refine(evaluate, propose, apply, revert, root: Path, max_iters: int = 6) -> dict:
+    previous = evaluate()
+    no_win_streak = 0
+    ledger = RejectionLedger(root)
+    for iteration in range(max_iters):
+        if all(rate == 1.0 for rate in previous.values()):
+            return {"converged": True, "iters": iteration}
+        target, failure_class = propose(previous)
+        edit = select_edit(failure_class)
+        snapshot = apply(edit)
+        current = evaluate()
+        if pareto_win(current, previous, target):
+            previous = current
+            no_win_streak = 0
+            continue
+        revert(snapshot)
+        ledger.log(edit, previous, current)
+        no_win_streak += 1
+        if no_win_streak >= 2:
+            return {"converged": False, "reason": "plateau", "iters": iteration + 1}
+    return {"converged": False, "reason": "budget", "iters": max_iters}

forgeline/run_store.py

@@ -0,0 +1,43 @@
+"""Per-feature run state + receipts. The state machine's durable memory —
+survives context resets (Ralph Wiggum) because the disk is the truth."""
+from __future__ import annotations
+import json, datetime, hashlib
+from pathlib import Path
+from .states import State
+
+def _now():
+    return datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+class RunStore:
+    def __init__(self, root: Path, feature: str):
+        self.root = Path(root); self.feature = feature
+        self.dir = self.root/".forge"/feature
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.state_path = self.dir/"state.json"
+        self.receipts = self.dir/"receipts.jsonl"
+        if not self.state_path.exists():
+            self._write({"feature": feature, "state": State.INTENT.value,
+                         "created": _now(), "attempts": {}, "history": []})
+
+    def _write(self, data): self.state_path.write_text(json.dumps(data, indent=2))
+    def load(self) -> dict: return json.loads(self.state_path.read_text())
+
+    @property
+    def state(self) -> State:
+        return State(self.load()["state"])
+
+    def set_state(self, s: State, note: str = ""):
+        d = self.load(); d["state"] = s.value
+        d["history"].append({"ts": _now(), "state": s.value, "note": note})
+        self._write(d)
+
+    def bump_attempt(self, phase: str) -> int:
+        d = self.load(); d["attempts"][phase] = d["attempts"].get(phase, 0) + 1
+        self._write(d); return d["attempts"][phase]
+
+    def receipt(self, **fields):
+        fields["ts"] = _now()
+        line = json.dumps(fields, sort_keys=True)
+        fields = {"h": hashlib.sha256(line.encode()).hexdigest()[:12], **fields}
+        with self.receipts.open("a") as f:
+            f.write(json.dumps(fields, sort_keys=True) + "\n")

forgeline/skill_memory.py

@@ -0,0 +1,52 @@
+"""Skill memory — the self-accelerating flywheel. Records what failed in each
+run and the fix, so future runs inject accumulated lessons into agent context.
+This is the 'skill learns from past refinements' mechanism, made concrete and
+LLM-free: lessons are structured, deduped, and promotable to constraints."""
+from __future__ import annotations
+import json, datetime
+from pathlib import Path
+
+LESSONS = "skills/lessons.jsonl"
+
+def record_lesson(root: Path, *, phase: str, failure_code: str, fix: str, feature: str):
+    root = Path(root); lp = root/LESSONS
+    lp.parent.mkdir(parents=True, exist_ok=True)
+    # dedupe by (phase, failure_code, fix)
+    existing = []
+    if lp.exists():
+        existing = [json.loads(l) for l in lp.read_text().splitlines() if l.strip()]
+    key = (phase, failure_code, fix)
+    for e in existing:
+        if (e["phase"], e["failure_code"], e["fix"]) == key:
+            e["count"] += 1; e["last_seen"] = datetime.datetime.now(datetime.timezone.utc).isoformat()
+            lp.write_text("\n".join(json.dumps(x) for x in existing) + "\n")
+            return e
+    entry = {"phase": phase, "failure_code": failure_code, "fix": fix, "feature": feature,
+             "count": 1, "last_seen": datetime.datetime.now(datetime.timezone.utc).isoformat()}
+    existing.append(entry)
+    lp.write_text("\n".join(json.dumps(x) for x in existing) + "\n")
+    return entry
+
+def lessons_for(root: Path, phase: str, min_count: int = 1) -> list[dict]:
+    lp = Path(root)/LESSONS
+    if not lp.exists(): return []
+    rows = [json.loads(l) for l in lp.read_text().splitlines() if l.strip()]
+    return sorted([r for r in rows if r["phase"] == phase and r["count"] >= min_count],
+                  key=lambda r: -r["count"])
+
+def promotable_constraints(root: Path, threshold: int = 3) -> list[dict]:
+    """Lessons seen >= threshold times graduate into hard constraints
+    (conventions-into-constraints). These get injected as SSAT invariants."""
+    lp = Path(root)/LESSONS
+    if not lp.exists(): return []
+    rows = [json.loads(l) for l in lp.read_text().splitlines() if l.strip()]
+    return [r for r in rows if r["count"] >= threshold]
+
+def inject_lessons_block(root: Path, phase: str) -> str:
+    """Text block injected into an agent's task context for this phase."""
+    ls = lessons_for(root, phase)
+    if not ls: return ""
+    lines = [f"## Lessons from past runs (phase: {phase})"]
+    for l in ls[:8]:
+        lines.append(f"- [{l['failure_code']} ×{l['count']}] {l['fix']}")
+    return "\n".join(lines)