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

forgeline/demo.py

@@ -0,0 +1,83 @@
+"""forge demo - a headless walk through refine loop + skill flywheel."""
+from __future__ import annotations
+
+import shutil
+import tempfile
+import time
+from pathlib import Path
+
+C = {"g": "\033[92m", "c": "\033[96m", "y": "\033[93m", "d": "\033[2m", "b": "\033[1m", "x": "\033[0m"}
+
+
+def p(message: str, sleep: float = 0.02) -> None:
+    print(message.encode("ascii", "replace").decode("ascii"))
+    time.sleep(sleep)
+
+
+def run() -> None:
+    from forgeline.orchestrator import Orchestrator
+    from forgeline.skill_memory import lessons_for
+    from forgeline.states import State
+
+    root = Path(tempfile.mkdtemp())
+    (root / "skills").mkdir()
+    ssat_src = Path(__file__).resolve().parents[1] / "examples" / "notifier.ssat.yaml"
+    ssat = root / "notifier.ssat.yaml"
+    shutil.copy(ssat_src, ssat)
+
+    p(f"\n{C['b']}* ForgeLine - autonomous factory outer loop{C['x']}")
+    p(f"{C['d']}  intent -> SSAT -> scaffold -> fill -> adversarial review -> ship{C['x']}\n")
+
+    orchestrator = Orchestrator(root, "notifier")
+    orchestrator.store.set_state(State.ARCHITECTED)
+    p(f"{C['c']}[1] architect{C['x']} - scaffolding signatures from architecture-as-code")
+    orchestrator.architect(ssat)
+    p(f"      {C['g']}OK{C['x']} 2 modules scaffolded with valid imports\n")
+
+    slices = root / "slices" / "notifier"
+    (slices / "formatter.py").write_text(
+        'def format_message(event: dict) -> str:\n    return str(eval(event.get("expr","1")))\n',
+        encoding="utf-8",
+    )
+    (slices / "sender.py").write_text(
+        "from slices.notifier.formatter import format_message\n"
+        "def send(event: dict, channel: str) -> bool:\n"
+        "    return bool(format_message(event) and channel)\n",
+        encoding="utf-8",
+    )
+    orchestrator.store.set_state(State.FILLED)
+    p(f"{C['c']}[2] fill (attempt 1){C['x']} - agent used eval(), shipped no tests")
+    review = orchestrator.review(ssat)
+    p(f"      {C['y']}BLOCKED: grumpy adversary findings:{C['x']}")
+    for finding in review["findings"]:
+        p(f"        - {finding}")
+    p(f"      {C['d']}lesson recorded to skill memory{C['x']}\n")
+
+    p(f"{C['c']}[3] lessons injected into next context:{C['x']}")
+    for lesson in lessons_for(root, "fill"):
+        p(f"        [{lesson['failure_code']} x{lesson['count']}] {lesson['fix'][:60]}")
+
+    (slices / "formatter.py").write_text(
+        "def format_message(event: dict) -> str:\n"
+        "    return f\"{event.get('kind','x')}: {event.get('text','')}\"\n",
+        encoding="utf-8",
+    )
+    (root / "tests").mkdir(exist_ok=True)
+    (root / "tests" / "test_notifier.py").write_text(
+        "def test_ok():\n    assert True\n",
+        encoding="utf-8",
+    )
+    p(f"\n{C['c']}[4] fill (attempt 2){C['x']} - eval removed, tests supplied")
+    review2 = orchestrator.review(ssat)
+    if review2["reviewed"]:
+        p(f"      {C['g']}OK judge + grumpy + arch erosion all pass{C['x']}")
+        orchestrator.arch_gate(ssat)
+        orchestrator.ship()
+        p(f"      {C['g']}OK architecture CI gate pass -> SHIPPED{C['x']}\n")
+
+    p(f"{C['d']}The factory caught its own bad output, learned, and shipped clean.")
+    p(f"  Wire it in: forge agent claude   |   forge agent codex{C['x']}\n")
+
+
+if __name__ == "__main__":
+    run()

forgeline/demo_learning.py

@@ -0,0 +1,44 @@
+"""forge demo-learning — shows the recursive loop: a failure recurs, gets
+promoted into active policy, then that policy catches it on the next run and
+is marked validated. The factory improving its own QA."""
+from __future__ import annotations
+import tempfile, time
+from pathlib import Path
+from .learning import LearningKernel
+from .skill_memory import record_lesson, lessons_for
+
+C = {"g":"\033[92m","c":"\033[96m","y":"\033[93m","d":"\033[2m","b":"\033[1m","x":"\033[0m"}
+def p(m): print(m); time.sleep(0.02)
+
+def run():
+    root = Path(tempfile.mkdtemp()); (root/"skills").mkdir()
+    k = LearningKernel(root, promote_threshold=3)
+    p(f"\n{C['b']}✦ ForgeLine — recursive learning loop{C['x']}")
+    p(f"{C['d']}  observe → promote → validate → self-prune{C['x']}\n")
+
+    p(f"{C['c']}[1] observe{C['x']} — the same flaw (eval) appears in 3 runs")
+    for i in range(3):
+        record_lesson(root, phase="fill", failure_code="A_EVAL", fix="never use eval()", feature=f"run{i}")
+        p(f"      {C['y']}▲{C['x']} run {i+1}: A_EVAL recorded")
+
+    p(f"\n{C['c']}[2] promote{C['x']} — seen ≥3× → becomes an ENFORCED constraint")
+    promoted = k.promote(lessons_for(root, "fill"))
+    p(f"      {C['g']}✓{C['x']} promoted to active policy: {promoted}")
+
+    p(f"\n{C['c']}[3] validate{C['x']} — next run, the policy CATCHES the same flaw")
+    prevented = k.enforce(["A_EVAL"])
+    p(f"      {C['g']}✓{C['x']} A_EVAL caught by learned policy → validated")
+
+    p(f"\n{C['c']}[4] self-prune{C['x']} — a stale rule that never fires goes to probation")
+    for i in range(3):
+        record_lesson(root, phase="fill", failure_code="A_OLD", fix="obsolete rule", feature="x")
+    k.promote(lessons_for(root, "fill"))
+    eff = k.audit_effectiveness()
+    p(f"      {C['d']}validated: {eff['validated']}  ·  probation: {eff['probation']}{C['x']}")
+
+    s = k.policy_summary()
+    p(f"\n{C['d']}Active policy v{s['version']} — the factory now enforces what it learned.")
+    p(f"  Every future build is checked against its own accumulated experience.{C['x']}\n")
+
+if __name__ == "__main__":
+    run()

forgeline/gates/__init__.py

@@ -0,0 +1,4 @@
+from .judge import judge_consistency
+from .adversary import grumpy_review
+from .skill_check import skill_check
+__all__ = ["judge_consistency", "grumpy_review", "skill_check"]

forgeline/gates/adversary.py

@@ -0,0 +1,45 @@
+"""The grumpy adversary — assumes the code is broken/insecure and makes the
+generator prove otherwise. Executable heuristics (no LLM needed to be
+useful); an optional LLM adversary can be layered behind the same interface.
+It does NOT need to be right — it needs to force proof (tests + arch completeness)."""
+from __future__ import annotations
+import ast, re
+from pathlib import Path
+
+DANGER = {
+    "eval(": "A_EVAL arbitrary eval",
+    "exec(": "A_EXEC arbitrary exec",
+    "os.system": "A_SHELL shell execution",
+    "subprocess": "A_SUBPROC subprocess use",
+    "pickle.load": "A_PICKLE unsafe deserialization",
+    "verify=False": "A_TLS TLS verification disabled",
+    "shell=True": "A_SHELL_TRUE shell=True injection surface",
+}
+SECRET = re.compile(r"(?i)(api[_-]?key|secret|password|token)\s*=\s*['\"][A-Za-z0-9/\+_-]{12,}['\"]")
+
+def grumpy_review(src_dir: Path, require_tests: bool = True) -> tuple[bool, list[str]]:
+    """Returns (satisfied, complaints). Grumpy is satisfied only when it can
+    find NO obvious sin AND the generator supplied tests to prove correctness."""
+    src_dir = Path(src_dir); complaints = []
+    py = list(src_dir.rglob("*.py"))
+    for p in py:
+        if p.name.startswith("test_") or p.parent.name == "tests":
+            continue
+        text = p.read_text()
+        for needle, msg in DANGER.items():
+            if needle in text:
+                complaints.append(f"{msg} in {p.name}")
+        if SECRET.search(text):
+            complaints.append(f"A_SECRET hard-coded credential in {p.name}")
+        # bare except = hiding failure, which grumpy hates
+        try:
+            for node in ast.walk(ast.parse(text)):
+                if isinstance(node, ast.ExceptHandler) and node.type is None:
+                    complaints.append(f"A_BARE_EXCEPT swallowed error in {p.name}")
+        except SyntaxError:
+            complaints.append(f"A_SYNTAX {p.name} does not parse")
+    if require_tests:
+        test_files = [p for p in py if p.name.startswith("test_") or p.parent.name == "tests"]
+        if not test_files:
+            complaints.append("A_NO_PROOF no tests supplied — prove it works")
+    return (len(complaints) == 0, complaints)

forgeline/gates/judge.py

@@ -0,0 +1,26 @@
+"""Judge Agent — directory & interface consistency (executable, LLM-free).
+Checks the filled code matches the SSAT scaffold: no stubs left, every
+declared function implemented, imports resolve within the tree."""
+from __future__ import annotations
+import ast
+from pathlib import Path
+from ..ssat import check_erosion
+
+def judge_consistency(ssat: dict, src_dir: Path) -> tuple[bool, list[str]]:
+    findings = []
+    src_dir = Path(src_dir)
+    for mod in ssat.get("modules", []):
+        p = src_dir/mod["path"]
+        if not p.exists():
+            findings.append(f"J_MISSING {mod['path']}"); continue
+        text = p.read_text()
+        if "raise NotImplementedError" in text or "# FILL" in text or "TODO" in text:
+            findings.append(f"J_STUB unfilled body in {mod['path']}")
+        try:
+            ast.parse(text)
+        except SyntaxError as e:
+            findings.append(f"J_SYNTAX {mod['path']}: {e}")
+    # structural erosion is a judge concern too
+    for v in check_erosion(ssat, src_dir):
+        findings.append(f"J_ARCH {v.code} {v.message}")
+    return (len(findings) == 0, findings)

forgeline/gates/qa_audit.py

@@ -0,0 +1,134 @@
+"""Deep QA audit — stricter than the grumpy adversary's heuristics. Scores
+generated code on coverage-intent, cyclomatic complexity, security surface,
+and documentation, producing a QA grade that gates shipping. This is the
+'stricter QA audit' layer: quantitative, thresholded, receipted."""
+from __future__ import annotations
+import ast, re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+@dataclass
+class QAReport:
+    coverage_intent: float = 0.0     # ratio of public funcs with a matching test
+    max_complexity: int = 0          # highest cyclomatic complexity found
+    security_score: int = 100        # 100 = clean; deductions per finding
+    doc_ratio: float = 0.0           # public funcs with docstrings
+    grade: str = "F"
+    findings: list = field(default_factory=list)
+    metrics: dict = field(default_factory=dict)
+    function_metrics: list = field(default_factory=list)
+
+    @property
+    def passed(self) -> bool:
+        return self.grade in ("A", "B") and self.security_score >= 80
+
+    @property
+    def attribution(self):
+        from ..attribution import Attribution, FailureClass, UnitResult
+        units = []
+        for metric in self.function_metrics:
+            failures = []
+            failure_class = None
+            if metric["complexity"] > 10:
+                failures.append(f"complexity={metric['complexity']}; threshold=10")
+                failure_class = FailureClass.COMPLEXITY_EXCEEDED
+            if not metric["tested"]:
+                failures.append("coverage_intent=0; required=1")
+                failure_class = failure_class or FailureClass.INCONSISTENT_LOGIC
+            units.append(UnitResult(
+                unit=f"qa_audit:{metric['function']}",
+                stage="qa_audit",
+                passed=not failures,
+                evidence="metrics within thresholds" if not failures else "; ".join(failures),
+                failure_class=failure_class,
+            ))
+        if not units:
+            units.append(UnitResult(
+                "qa_audit:<no-public-functions>", "qa_audit", False,
+                "no public functions were available to grade",
+                FailureClass.STUB_UNFILLED,
+            ))
+        return Attribution("qa_audit", len(units), sum(unit.passed for unit in units), units)
+
+def _complexity(node: ast.FunctionDef) -> int:
+    """Cyclomatic complexity: 1 + branch points."""
+    c = 1
+    for n in ast.walk(node):
+        if isinstance(n, (ast.If, ast.For, ast.While, ast.ExceptHandler, ast.With, ast.Assert)):
+            c += 1
+        elif isinstance(n, ast.BoolOp):
+            c += len(n.values) - 1
+        elif isinstance(n, ast.IfExp):
+            c += 1
+    return c
+
+SEC_PATTERNS = {
+    r"\beval\(": ("CRITICAL", 40, "eval() — arbitrary code execution"),
+    r"\bexec\(": ("CRITICAL", 40, "exec() — arbitrary code execution"),
+    r"shell\s*=\s*True": ("HIGH", 25, "shell=True — command injection surface"),
+    r"pickle\.loads?\(": ("HIGH", 20, "pickle — unsafe deserialization"),
+    r"verify\s*=\s*False": ("HIGH", 20, "TLS verification disabled"),
+    r"(?i)(password|secret|api_key|token)\s*=\s*['\"][^'\"]{8,}": ("CRITICAL", 40, "hard-coded credential"),
+    r"md5\(": ("MEDIUM", 10, "MD5 — weak hash"),
+    r"random\.random\(\)": ("LOW", 5, "non-cryptographic randomness"),
+}
+
+def qa_audit(src_dir: Path) -> QAReport:
+    src_dir = Path(src_dir)
+    r = QAReport()
+    code_files = [p for p in src_dir.rglob("*.py")
+                  if not p.name.startswith("test_") and p.parent.name != "tests"]
+    test_files = [p for p in src_dir.rglob("*.py")
+                  if p.name.startswith("test_") or p.parent.name == "tests"]
+    all_test_text = "\n".join(p.read_text() for p in test_files)
+
+    public_funcs, tested, documented, complexities = [], 0, 0, []
+    for p in code_files:
+        try:
+            tree = ast.parse(p.read_text())
+        except SyntaxError as e:
+            r.findings.append(f"QA_SYNTAX {p.name}: {e}"); continue
+        for node in ast.walk(tree):
+            if isinstance(node, ast.FunctionDef) and not node.name.startswith("_"):
+                public_funcs.append(node.name)
+                # coverage-intent: is the function name referenced in tests?
+                if re.search(rf"\b{re.escape(node.name)}\b", all_test_text):
+                    tested += 1
+                if ast.get_docstring(node):
+                    documented += 1
+                cx = _complexity(node)
+                complexities.append((node.name, cx))
+                r.function_metrics.append({
+                    "function": f"{p.name}:{node.name}",
+                    "complexity": cx,
+                    "tested": bool(re.search(rf"\b{re.escape(node.name)}\b", all_test_text)),
+                    "documented": bool(ast.get_docstring(node)),
+                })
+        # security scan
+        text = p.read_text()
+        for pat, (sev, deduct, msg) in SEC_PATTERNS.items():
+            if re.search(pat, text):
+                r.security_score -= deduct
+                r.findings.append(f"QA_SEC[{sev}] {msg} in {p.name}")
+
+    n = len(public_funcs) or 1
+    r.coverage_intent = round(tested / n, 2)
+    r.doc_ratio = round(documented / n, 2)
+    r.max_complexity = max((c for _, c in complexities), default=0)
+    r.security_score = max(r.security_score, 0)
+    for name, cx in complexities:
+        if cx > 10:
+            r.findings.append(f"QA_COMPLEXITY {name}() complexity {cx} > 10 — refactor")
+
+    # composite grade
+    score = 0
+    score += 35 * r.coverage_intent
+    score += 25 * (1 if r.max_complexity <= 10 else max(0, 1 - (r.max_complexity-10)/10))
+    score += 25 * (r.security_score / 100)
+    score += 15 * r.doc_ratio
+    r.metrics = {"coverage_intent": r.coverage_intent, "max_complexity": r.max_complexity,
+                 "security_score": r.security_score, "doc_ratio": r.doc_ratio,
+                 "composite": round(score, 1)}
+    r.grade = ("A" if score >= 85 else "B" if score >= 70 else
+               "C" if score >= 55 else "D" if score >= 40 else "F")
+    return r

forgeline/gates/reverse_classical.py

@@ -0,0 +1,118 @@
+"""Reverse-classical test verification.
+
+Before ForgeLine trusts a smoke check against the real implementation, it runs
+the same behavioral check against the generated SSAT scaffold. A behavioral
+test must fail on that empty stub. If it passes, the test is hollow: it asserts
+nothing the implementation provides.
+"""
+from __future__ import annotations
+
+import shutil
+import tempfile
+from pathlib import Path
+
+from forgeline.attribution import Attribution, FailureClass, GateResult, UnitResult
+from forgeline.gates.runtime_smoke import _load_manifest, _run_check
+from forgeline.ssat import load_ssat, scaffold_from_ssat
+
+
+def materialize_stub_root(ssat_path: Path) -> Path:
+    """Regenerate the SSAT scaffold into an isolated temp root.
+
+    The production tree is never touched. Reusing `scaffold_from_ssat` is the
+    guarantee: the mutant is byte-identical to what the normal SCAFFOLDED state
+    would produce for the same SSAT.
+    """
+    tmp = Path(tempfile.mkdtemp(prefix="forge-stub-"))
+    scaffold_from_ssat(load_ssat(ssat_path), tmp)
+    return tmp
+
+
+def verify_tests(root: Path, feature: str, ssat_path: Path) -> GateResult:
+    root = Path(root)
+    try:
+        checks = _load_manifest(root, feature)
+    except ValueError as exc:
+        attr = Attribution("verify_tests", 1, 0, [
+            UnitResult(
+                unit="verify_tests:manifest",
+                stage="verify_tests",
+                passed=False,
+                evidence=str(exc),
+                failure_class=FailureClass.HOLLOW_MANIFEST,
+            )
+        ])
+        return GateResult(False, attr)
+
+    if checks is None:
+        attr = Attribution("verify_tests", 1, 0, [
+            UnitResult(
+                unit="verify_tests:manifest",
+                stage="verify_tests",
+                passed=False,
+                evidence=f"no smoke manifest at smoke/{feature}.json; nothing to verify",
+                failure_class=FailureClass.HOLLOW_MANIFEST,
+            )
+        ])
+        return GateResult(False, attr)
+
+    if not checks:
+        attr = Attribution("verify_tests", 1, 0, [
+            UnitResult(
+                unit="verify_tests:manifest",
+                stage="verify_tests",
+                passed=False,
+                evidence="smoke manifest declares no checks",
+                failure_class=FailureClass.HOLLOW_MANIFEST,
+            )
+        ])
+        return GateResult(False, attr)
+
+    if all(not check.must_fail_on_stub for check in checks):
+        units = [
+            UnitResult(
+                unit=f"verify_tests:{check.name}",
+                stage="verify_tests",
+                passed=False,
+                evidence="every check is exempt; manifest verifies no behavior",
+                failure_class=FailureClass.HOLLOW_MANIFEST,
+            )
+            for check in checks
+        ]
+        return GateResult(False, Attribution("verify_tests", len(units), 0, units))
+
+    stub_root = materialize_stub_root(ssat_path)
+    try:
+        units: list[UnitResult] = []
+        for check in checks:
+            unit = f"verify_tests:{check.name}"
+            if not check.must_fail_on_stub:
+                units.append(UnitResult(
+                    unit=unit,
+                    stage="verify_tests",
+                    passed=True,
+                    evidence="exempt: declared structural check",
+                    failure_class=None,
+                ))
+                continue
+
+            result = _run_check(check, stub_root)
+            hollow = result.passed
+            units.append(UnitResult(
+                unit=unit,
+                stage="verify_tests",
+                passed=not hollow,
+                evidence=(
+                    "check PASSED against an empty stub; it asserts nothing the "
+                    "implementation provides"
+                    if hollow
+                    else f"correctly failed on stub: {result.reason}"
+                ),
+                failure_class=FailureClass.HOLLOW_TEST if hollow else None,
+            ))
+    finally:
+        shutil.rmtree(stub_root, ignore_errors=True)
+
+    attr = Attribution("verify_tests", len(units), sum(unit.passed for unit in units), units)
+    return GateResult(attr.rate == 1.0, attr)
+

forgeline/gates/runtime_smoke.py

@@ -0,0 +1,194 @@
+"""forgeline runtime smoke gate — behavior-by-inspection before ship.
+
+The rest of ForgeLine verifies code against *specifications*: the judge checks
+consistency, the QA audit grades static quality, the intent thread proves the
+code honors the sealed envelope. All of that is correctness-*by-construction*.
+
+None of it answers the question a per-PR preview deployment answers: **does the
+built thing actually RUN and behave correctly when executed?** A change can pass
+every static gate and still crash on import, throw at runtime, or produce the
+wrong output. This gate closes that gap at the right scale for a solo builder:
+it runs the artifact against declared behavioral checks and blocks ship on any
+runtime failure — without the cost of ephemeral per-PR environments.
+
+Design contract:
+  - Deterministic pass/fail: a check either ran green or it didn't.
+  - Isolated: checks run in a subprocess with a timeout, so a hang or crash in
+    the built code cannot take down the orchestrator.
+  - Declarative: behavioral checks live in a `smoke/` manifest beside the spec,
+    so what "correct runtime behavior" means is itself a reviewed artifact.
+  - Fail-closed: no manifest, or a manifest that references nothing runnable,
+    is a BLOCK — you cannot ship unverified runtime behavior by omission.
+"""
+from __future__ import annotations
+import json
+import subprocess
+import sys
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from forgeline.attribution import Attribution, FailureClass, GateResult, UnitResult
+
+
+@dataclass
+class SmokeCheck:
+    name: str
+    kind: str           # "command" | "python"
+    run: str            # shell command, or python snippet/file
+    expect_exit: int = 0
+    expect_stdout: str | None = None   # substring that must appear
+    timeout_s: int = 30
+    must_fail_on_stub: bool = True
+
+
+@dataclass
+class SmokeResult:
+    name: str
+    passed: bool
+    reason: str
+    duration_ms: int = 0
+
+
+@dataclass
+class SmokeReport:
+    results: list[SmokeResult] = field(default_factory=list)
+    manifest_found: bool = True
+
+    @property
+    def ok(self) -> bool:
+        return self.manifest_found and bool(self.results) and all(r.passed for r in self.results)
+
+    @property
+    def failures(self):
+        return [r for r in self.results if not r.passed]
+
+    def add(self, name, passed, reason, duration_ms=0):
+        self.results.append(SmokeResult(name, passed, reason, duration_ms))
+
+    @property
+    def attribution(self) -> Attribution:
+        units = []
+        for result in self.results:
+            failure_class = None
+            reason = result.reason.lower()
+            if not result.passed:
+                if "timed out" in reason:
+                    failure_class = FailureClass.RUNTIME_TIMEOUT
+                elif "expected stdout" in reason:
+                    failure_class = FailureClass.WRONG_OUTPUT
+                else:
+                    failure_class = FailureClass.RUNTIME_CRASH
+            units.append(UnitResult(
+                unit=f"smoke:{result.name}",
+                stage="smoke",
+                passed=result.passed,
+                evidence=result.reason,
+                failure_class=failure_class,
+            ))
+        return Attribution("smoke", len(units), sum(unit.passed for unit in units), units)
+
+    @property
+    def gate_result(self) -> GateResult:
+        attr = self.attribution
+        return GateResult(attr.n_checked > 0 and attr.rate == 1.0, attr)
+
+
+def _load_manifest(root: Path, feature: str) -> list[SmokeCheck] | None:
+    """A smoke manifest is JSON at smoke/<feature>.json (or smoke/smoke.json).
+    Each entry declares one behavioral check. Missing manifest -> None (fail-closed
+    upstream)."""
+    candidates = [
+        Path(root) / "smoke" / f"{feature}.json",
+        Path(root) / "smoke" / "smoke.json",
+    ]
+    for p in candidates:
+        if p.exists():
+            try:
+                data = json.loads(p.read_text())
+            except json.JSONDecodeError as e:
+                raise ValueError(f"smoke manifest {p} is not valid JSON: {e}")
+            checks = []
+            for entry in data.get("checks", []):
+                checks.append(SmokeCheck(
+                    name=entry["name"],
+                    kind=entry.get("kind", "command"),
+                    run=entry["run"],
+                    expect_exit=entry.get("expect_exit", 0),
+                    expect_stdout=entry.get("expect_stdout"),
+                    timeout_s=entry.get("timeout_s", 30),
+                    must_fail_on_stub=entry.get("must_fail_on_stub", True),
+                ))
+            return checks
+    return None
+
+
+def _run_check(check: SmokeCheck, cwd: Path) -> SmokeResult:
+    """Execute one check in an isolated subprocess with a hard timeout."""
+    t0 = time.monotonic()
+    if check.kind == "python":
+        cmd = [sys.executable, "-c", check.run]
+    else:
+        cmd = check.run  # shell command string
+    try:
+        proc = subprocess.run(
+            cmd,
+            cwd=str(cwd),
+            shell=(check.kind != "python"),
+            capture_output=True,
+            text=True,
+            timeout=check.timeout_s,
+        )
+    except subprocess.TimeoutExpired:
+        ms = int((time.monotonic() - t0) * 1000)
+        return SmokeResult(check.name, False,
+                           f"timed out after {check.timeout_s}s — runtime hang", ms)
+    except (OSError, ValueError) as e:
+        ms = int((time.monotonic() - t0) * 1000)
+        return SmokeResult(check.name, False, f"could not execute: {e}", ms)
+
+    ms = int((time.monotonic() - t0) * 1000)
+    # exit-code check
+    if proc.returncode != check.expect_exit:
+        tail = (proc.stderr or proc.stdout or "").strip().splitlines()[-3:]
+        return SmokeResult(check.name, False,
+                           f"exit {proc.returncode} != expected {check.expect_exit}; "
+                           f"last: {' | '.join(tail)[:200]}", ms)
+    # stdout-substring check
+    if check.expect_stdout is not None and check.expect_stdout not in (proc.stdout or ""):
+        return SmokeResult(check.name, False,
+                           f"expected stdout to contain {check.expect_stdout!r}, not found", ms)
+    return SmokeResult(check.name, True, "ran green", ms)
+
+
+def runtime_smoke(root: Path, feature: str) -> SmokeReport:
+    """Run all declared behavioral checks for a feature. Fail-closed: no manifest,
+    empty manifest, or any failing check blocks ship."""
+    rep = SmokeReport()
+    root = Path(root)
+    try:
+        checks = _load_manifest(root, feature)
+    except ValueError as e:
+        rep.manifest_found = True
+        rep.add("manifest", False, str(e))
+        return rep
+    if checks is None:
+        rep.manifest_found = False
+        rep.add("manifest", False,
+                f"no smoke manifest at smoke/{feature}.json — cannot verify runtime "
+                f"behavior. Declare at least one behavioral check before ship.")
+        return rep
+    if not checks:
+        rep.add("manifest", False, "smoke manifest present but declares no checks — "
+                                   "runtime behavior would ship unverified.")
+        return rep
+    for c in checks:
+        rep.results.append(_run_check(c, root))
+    return rep
+
+
+def smoke_report_lines(rep: SmokeReport) -> list[str]:
+    out = []
+    for r in rep.results:
+        mark = "PASS" if r.passed else "FAIL"
+        out.append(f"[{mark}] {r.name} ({r.duration_ms}ms): {r.reason}")
+    return out

forgeline/gates/skill_check.py

@@ -0,0 +1,14 @@
+"""Skill-check gate — ensures the AGENT EXPERIENCE stays high: the run
+produced the receipts, the state machine advanced legally, and the skill
+memory recorded a lesson. Keeps the factory itself from eroding."""
+from __future__ import annotations
+from pathlib import Path
+
+def skill_check(root: Path, feature: str) -> tuple[bool, list[str]]:
+    findings = []
+    fd = Path(root)/".forge"/feature
+    if not (fd/"receipts.jsonl").exists() or not (fd/"receipts.jsonl").read_text().strip():
+        findings.append("S_NO_RECEIPTS run produced no receipts")
+    if not (fd/"state.json").exists():
+        findings.append("S_NO_STATE run has no state record")
+    return (len(findings) == 0, findings)