code-factory-1-spec 0.3.0__py3-none-any.whl

specline/gates.py

@@ -0,0 +1,40 @@
+"""Human review gates with receipts. A gate signoff writes a hash-sealed
+line into PROGRESS.md; the loop and drift guard consume those seals."""
+from __future__ import annotations
+import hashlib, datetime
+from pathlib import Path
+from .spec_lint import validate_spec
+from .plan_lint import lint_plan
+from .strict_lint import strict_errors
+
+def _seal(root: Path, line: str):
+    p = Path(root)/"context"/"PROGRESS.md"
+    ts = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%d %H:%M")
+    p.write_text(p.read_text() + f"\n- [{ts}] {line}")
+
+def gate(root: Path, phase: str, feature: str, approver: str = "human", strict: bool = True) -> dict:
+    root = Path(root)
+    spec = root/"specs"/f"{feature}.md"
+    if phase == "spec":
+        errs = validate_spec(spec)
+        if strict:
+            errs = errs + strict_errors(spec)
+        if errs:
+            raise SystemExit("spec gate FAILED:\n" + "\n".join(errs))
+        sha = hashlib.sha256(spec.read_bytes()).hexdigest()[:16]
+        _seal(root, f"GATE spec {feature} approver={approver} strict={strict} sha={sha}")
+        return {"gate": "spec", "sha": sha}
+    if phase == "plan":
+        errsS = validate_spec(spec)
+        if strict:
+            errsS = errsS + strict_errors(spec)
+        tasks, errsP = lint_plan(root/"plans"/f"{feature}.md")
+        if errsS or errsP:
+            raise SystemExit("plan gate FAILED:\n" + "\n".join(errsS + errsP))
+        sha = hashlib.sha256(spec.read_bytes()).hexdigest()[:16]
+        _seal(root, f"GATE plan {feature} approver={approver} tasks={len(tasks)} sha={sha}")
+        return {"gate": "plan", "tasks": len(tasks), "sha": sha}
+    if phase == "code":
+        _seal(root, f"GATE code {feature} approver={approver} reviewer=personas/reviewer.md auditor=personas/security_auditor.md")
+        return {"gate": "code"}
+    raise SystemExit(f"unknown gate {phase}")

specline/handoff.py

@@ -0,0 +1,44 @@
+"""The HSF calibration bridge: decision tables in specs become Harness
+Software Factory workflow specs — compiled once, gated, deterministic —
+instead of agent-improvised if-statements scattered through tissue code."""
+from __future__ import annotations
+import re
+from pathlib import Path
+import yaml
+from .spec_lint import decision_rows
+
+def handoff_to_hsf(root: Path, feature: str, owner: str = "specline") -> Path:
+    root = Path(root)
+    rows = decision_rows(root/"specs"/f"{feature}.md")
+    if not rows:
+        raise SystemExit("no decision table found in spec (## Decision logic section)")
+    fields: set[str] = set()
+    rules = []
+    for r in rows:
+        cond = r["if"].strip()
+        is_else = cond.lower() in {"else", "otherwise", "*"}
+        if not is_else:
+            for name in re.findall(r"[a-z_][a-z0-9_]*", cond):
+                if name not in {"and", "or", "not", "true", "false"}:
+                    fields.add(name)
+        m = re.match(r"(\w+)\s*[:=]\s*(.+)", r["then"])
+        status, reason = (m.group(1).upper(), m.group(2)) if m else ("APPROVED", r["then"])
+        if is_else:
+            rules.append({"else": {"status": status, "reason": reason}})
+        else:
+            rules.append({"if": cond, "then": {"status": status, "reason": reason}})
+    if not any("else" in r for r in rules):
+        rules.append({"else": {"status": "HUMAN_REVIEW", "reason": "No rule matched"}})
+    schema = {f: "boolean" if re.search(rf"{f}\s*==\s*(true|false)", " ".join(r['if'] for r in rows if 'if' in r)) else {"type": "float", "min": 0.0, "max": 1000000.0} for f in sorted(fields)}
+    spec = {"workflow_spec": f"{feature}_decisions", "version": 1,
+            "metadata": {"owner": owner, "compliance": []},
+            "inputs": {"input_data": {"text": "string"}},
+            "steps": [
+                {"id": "extract_facts", "type": "bounded_invocation",
+                 "schema": schema, "on_out_of_bounds": "human_review"},
+                {"id": "decide", "type": "branch", "rules": rules}],
+            "outputs": {"AuthResult": {"status": "enum[APPROVED, DENIED, HUMAN_REVIEW]", "reason": "string"}}}
+    out = root/"handoff"/f"{feature}_decisions.yaml"
+    out.parent.mkdir(exist_ok=True)
+    out.write_text(yaml.safe_dump(spec, sort_keys=False))
+    return out

specline/ledger.py

@@ -0,0 +1,40 @@
+"""Context Ledger — receipts for token economics. Every packet logs its
+estimated context cost vs the naive baseline (re-reading the whole feature
+surface each session). `specline status` shows cumulative savings —
+the SDD equivalent of HSF's break-even bench."""
+from __future__ import annotations
+import json, datetime
+from pathlib import Path
+
+LEDGER = "receipts/context-ledger.jsonl"
+
+def _naive_baseline_tokens(root: Path, feature: str) -> int:
+    total = 0
+    for p in [root/"specs"/f"{feature}.md", root/"plans"/f"{feature}.md", root/"AGENTS.md"]:
+        if p.exists(): total += len(p.read_text())
+    for d in ["context", "slices"]:
+        for p in (root/d).rglob("*.*"):
+            try: total += len(p.read_text())
+            except Exception: pass
+    return total // 4
+
+def log_packet(root: Path, feature: str, task_id: str, tokens_est: int, sha: str) -> dict:
+    root = Path(root)
+    entry = {"ts": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+             "feature": feature, "task": task_id, "packet_tokens": tokens_est,
+             "naive_baseline_tokens": _naive_baseline_tokens(root, feature), "sha": sha}
+    lp = root/LEDGER
+    lp.parent.mkdir(exist_ok=True)
+    with lp.open("a") as f:
+        f.write(json.dumps(entry) + "\n")
+    return entry
+
+def summarize(root: Path) -> dict:
+    lp = Path(root)/LEDGER
+    if not lp.exists():
+        return {"sessions": 0, "packet_tokens": 0, "naive_tokens": 0, "saved_pct": 0.0}
+    rows = [json.loads(l) for l in lp.read_text().splitlines() if l.strip()]
+    pt = sum(r["packet_tokens"] for r in rows)
+    nt = sum(r["naive_baseline_tokens"] for r in rows)
+    return {"sessions": len(rows), "packet_tokens": pt, "naive_tokens": nt,
+            "saved_pct": round(100 * (1 - pt / nt), 1) if nt else 0.0}

specline/loop.py

@@ -0,0 +1,66 @@
+"""The Ralph Wiggum Loop runner. `next` emits one packet; `done` verifies
+and seals it with a receipt in PROGRESS.md. Drift guard: if the spec hash
+changed since plan approval, the loop refuses until the plan is re-gated."""
+from __future__ import annotations
+import hashlib, subprocess, datetime
+from pathlib import Path
+from .plan_lint import parse_tasks, lint_plan
+from .packets import build_packet
+from .ledger import log_packet
+
+def _sha(p: Path) -> str:
+    return hashlib.sha256(p.read_bytes()).hexdigest()[:16]
+
+def _progress(root: Path) -> Path:
+    return Path(root)/"context"/"PROGRESS.md"
+
+def _append_progress(root: Path, line: str):
+    p = _progress(root)
+    ts = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%d %H:%M")
+    p.write_text(p.read_text() + f"\n- [{ts}] {line}")
+
+def _approved_spec_sha(root: Path, feature: str) -> str | None:
+    for line in _progress(root).read_text().splitlines():
+        if f"GATE plan {feature}" in line and "sha=" in line:
+            return line.split("sha=")[-1].strip()
+    return None
+
+def next_task(root: Path, feature: str) -> dict:
+    root = Path(root)
+    plan = root/"plans"/f"{feature}.md"
+    tasks, errors = lint_plan(plan)
+    if errors:
+        raise SystemExit("plan not clean:\n" + "\n".join(errors))
+    locked = _approved_spec_sha(root, feature)
+    current = _sha(root/"specs"/f"{feature}.md")
+    if locked is None:
+        raise SystemExit("plan gate missing: run `specline gate plan " + feature + "` first")
+    if locked != current:
+        raise SystemExit(f"E_INTENT_DRIFT: spec changed since plan gate (locked {locked}, now {current}). Re-gate the plan.")
+    todo = [t for t in tasks if not t["done"]]
+    if not todo:
+        return {"status": "all_done"}
+    task = todo[0]
+    packet, meta = build_packet(root, feature, task)
+    entry = log_packet(root, feature, task["id"], meta["tokens_est"], meta["sha"])
+    _append_progress(root, f"PACKET {feature} {task['id']} tokens={meta['tokens_est']} sha={meta['sha']}")
+    return {"status": "ready", "task": task["id"], "packet": str(packet),
+            "tokens_est": meta["tokens_est"], "saved_vs_naive": entry["naive_baseline_tokens"] - meta["tokens_est"]}
+
+def mark_done(root: Path, feature: str, task_id: str, run_verify: bool = True) -> dict:
+    root = Path(root)
+    plan = root/"plans"/f"{feature}.md"
+    tasks = parse_tasks(plan)
+    task = next((t for t in tasks if t["id"] == task_id), None)
+    if task is None:
+        raise SystemExit(f"unknown task {task_id}")
+    verified = True
+    if run_verify:
+        proc = subprocess.run(task["verify"], shell=True, cwd=root, capture_output=True, text=True)
+        verified = proc.returncode == 0
+        if not verified:
+            raise SystemExit(f"VERIFY FAILED for {task_id}: {task['verify']}\n{proc.stderr[-500:]}")
+    text = plan.read_text().replace(f"- [ ] {task_id} |", f"- [x] {task_id} |", 1)
+    plan.write_text(text)
+    _append_progress(root, f"DONE {feature} {task_id} verify_pass=true  # context resets now")
+    return {"task": task_id, "verified": verified}

specline/packets.py

@@ -0,0 +1,107 @@
+"""Task Packets — the token-lean session brief. This is C_t = γ·R_f·T_d
+made executable: each packet contains ONLY the task, the spec excerpt that
+governs it, the exact file list, a constitution digest, and the verify
+command — under a hard token budget. One packet == one agent session."""
+from __future__ import annotations
+import hashlib, re
+from pathlib import Path
+
+TOKEN_BUDGET = 2200   # ~ chars/4; hard cap for a packet
+CHARS_PER_TOKEN = 4
+
+def _est_tokens(s: str) -> int:
+    return len(s) // CHARS_PER_TOKEN
+
+def _relevant_spec_excerpt(spec_text: str, task_text: str, max_chars: int = 2600) -> str:
+    """Requirement-scoped excerpt (anti-drift).
+
+    The old version matched individual LINES by shared vocabulary, which could
+    hand the agent a half-requirement (condition stripped off), forcing it to
+    improvise the rest. This version selects WHOLE requirement blocks and always
+    ships the complete acceptance scenario intact. The agent never receives a
+    partial rule.
+    """
+    words = {w.lower() for w in re.findall(r"[A-Za-z]{4,}", task_text)}
+    lines = spec_text.splitlines()
+
+    gherkin_block, in_g = [], False
+    for line in lines:
+        if line.strip().startswith("```gherkin"):
+            in_g = True
+        if in_g:
+            gherkin_block.append(line)
+        if in_g and line.strip() == "```" and not line.strip().startswith("```g"):
+            in_g = False
+
+    req_block, i = [], 0
+    while i < len(lines):
+        line = lines[i]
+        if line.lstrip().startswith("- "):
+            block = [line]; j = i + 1
+            while j < len(lines) and lines[j].startswith(("  ", "\t")) and not lines[j].lstrip().startswith("- "):
+                block.append(lines[j]); j += 1
+            bw = {w.lower() for w in re.findall(r"[A-Za-z]{4,}", " ".join(block))}
+            if words & bw:
+                req_block.extend(block)
+            i = j
+        else:
+            i += 1
+
+    parts = []
+    if req_block:
+        parts.append("### Governing requirements (complete blocks)\n" + "\n".join(req_block))
+    if gherkin_block:
+        parts.append("### Acceptance (verbatim — do not reinterpret)\n" + "\n".join(gherkin_block))
+    out = "\n\n".join(parts) if parts else "\n".join(l for l in lines if l.lstrip().startswith("- "))
+    if len(out) > max_chars:
+        kept, total = [], 0
+        for para in out.split("\n\n"):
+            if total + len(para) > max_chars:
+                break
+            kept.append(para); total += len(para) + 2
+        out = "\n\n".join(kept) if kept else out[:max_chars]
+    return out
+
+CONSTITUTION_DIGEST = (
+    "CONSTITUTION DIGEST: one task only; read ONLY listed files; tests ship with code; "
+    "never touch skeleton/; never add deps without ADR; never leave stubs; "
+    "decision logic goes to the factory, not inline; stop and ask on ambiguity."
+)
+
+def build_packet(root: Path, feature: str, task: dict) -> tuple[Path, dict]:
+    root = Path(root)
+    spec_text = (root/"specs"/f"{feature}.md").read_text()
+    excerpt = _relevant_spec_excerpt(spec_text, task["text"])
+    files_block = "\n".join(f"- {f}" for f in task["files"]) or "- (new files in slice)"
+    body = f"""# TASK PACKET {task['id']} — {feature}
+<!-- One session. Finish, verify, stop. Context resets after this. -->
+
+## Your single task
+{task['text']}
+
+## Slice (you may only create/modify files here + tests)
+{task['slice']}
+
+## Files in scope (R_f — read nothing else except context/PROGRESS.md)
+{files_block}
+
+## Governing spec excerpt
+{excerpt}
+
+## {CONSTITUTION_DIGEST}
+
+## Definition of done
+Run: `{task['verify']}` — must pass. Then STOP and report the diff summary.
+"""
+    est = _est_tokens(body)
+    if est > TOKEN_BUDGET:
+        # deterministic prune: shrink excerpt first (same discipline as HSF context assembler)
+        overflow = (est - TOKEN_BUDGET) * CHARS_PER_TOKEN
+        body = body.replace(excerpt, excerpt[: max(len(excerpt) - overflow, 400)])
+        est = _est_tokens(body)
+    out = root/"packets"/f"{feature}-{task['id']}.md"
+    out.parent.mkdir(exist_ok=True)
+    out.write_text(body)
+    meta = {"packet": str(out), "tokens_est": est,
+            "sha": hashlib.sha256(body.encode()).hexdigest()[:16]}
+    return out, meta

specline/paths.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+from pathlib import Path
+
+def templates_dir() -> Path:
+    return Path(__file__).resolve().parents[1] / "templates"
+
+def project_dirs(root: Path) -> dict:
+    return {"specs": root/"specs", "plans": root/"plans", "context": root/"context",
+            "adr": root/"adr", "packets": root/"packets", "slices": root/"slices",
+            "skeleton": root/"skeleton", "handoff": root/"handoff", "receipts": root/"receipts"}

specline/plan_lint.py

@@ -0,0 +1,38 @@
+"""specline tasks — atomicity linter. Enforces the double-decomposition
+contract so every task is a clean Ralph-Wiggum session."""
+from __future__ import annotations
+import re
+from pathlib import Path
+
+TASK = re.compile(r"^- \[( |x)\] (T\d+) \| slice=(\S+) \| files=([^|]+) \| verify=`([^`]+)` \| (.+)$")
+
+def parse_tasks(path: Path) -> list[dict]:
+    tasks = []
+    for line in Path(path).read_text().splitlines():
+        m = TASK.match(line.strip())
+        if m:
+            files = [f.strip() for f in m.group(4).split(",") if f.strip() and "<=" not in f]
+            tasks.append({"done": m.group(1) == "x", "id": m.group(2), "slice": m.group(3),
+                          "files": files, "verify": m.group(5), "text": m.group(6)})
+    return tasks
+
+def lint_plan(path: Path) -> tuple[list[dict], list[str]]:
+    text = Path(path).read_text()
+    tasks = parse_tasks(path)
+    errors = []
+    if not tasks:
+        errors.append("E_NO_TASKS: no parseable task lines (format: - [ ] T1 | slice=x | files=a,b | verify=`cmd` | text)")
+    if "Architect verdict: PASS" not in text:
+        errors.append("E_NO_VERDICT: plan lacks 'Architect verdict: PASS'")
+    ids = [t["id"] for t in tasks]
+    if len(ids) != len(set(ids)):
+        errors.append("E_DUP_TASK_ID")
+    for t in tasks:
+        if len(t["files"]) > 4:
+            errors.append(f"E_TASK_TOO_WIDE: {t['id']} touches {len(t['files'])} files (max 4)")
+        if t["slice"].startswith("skeleton"):
+            errors.append(f"E_SKELETON_TASK: {t['id']} targets human-owned skeleton")
+        for f in t["files"]:
+            if f and not (f.startswith(t["slice"]) or f.startswith("tests")):
+                errors.append(f"E_SLICE_ESCAPE: {t['id']} file {f!r} outside slice {t['slice']!r}")
+    return tasks, errors

specline/scaffold.py

@@ -0,0 +1,40 @@
+"""specline init — stand up the six-file context system + constitution."""
+from __future__ import annotations
+import shutil
+from pathlib import Path
+from .paths import templates_dir, project_dirs
+
+def init_project(root: Path) -> list[Path]:
+    root = Path(root); created = []
+    for d in project_dirs(root).values():
+        d.mkdir(parents=True, exist_ok=True)
+    t = templates_dir()
+    for name in ["PROJECT_OVERVIEW.md","ARCHITECTURE.md","CODE_STANDARDS.md",
+                 "AI_WORKFLOW_RULES.md","UI_CONTEXT.md","PROGRESS.md"]:
+        dst = root/"context"/name
+        if not dst.exists():
+            shutil.copy(t/"context"/name, dst); created.append(dst)
+    for src, dst in [(t/"AGENTS.md", root/"AGENTS.md")]:
+        if not dst.exists():
+            shutil.copy(src, dst); created.append(dst)
+    pd = root/"templates"
+    pd.mkdir(exist_ok=True)
+    for name in ["SPEC_TEMPLATE.md","PLAN_TEMPLATE.md"]:
+        if not (pd/name).exists():
+            shutil.copy(t/name, pd/name); created.append(pd/name)
+    per = root/"personas"; per.mkdir(exist_ok=True)
+    for p in (t/"personas").glob("*.md"):
+        if not (per/p.name).exists():
+            shutil.copy(p, per/p.name); created.append(per/p.name)
+    return created
+
+def new_feature(root: Path, name: str) -> tuple[Path, Path]:
+    root = Path(root)
+    spec = root/"specs"/f"{name}.md"; plan = root/"plans"/f"{name}.md"
+    if spec.exists():
+        raise FileExistsError(spec)
+    spec.parent.mkdir(parents=True, exist_ok=True); plan.parent.mkdir(parents=True, exist_ok=True)
+    t = templates_dir()
+    spec.write_text((t/"SPEC_TEMPLATE.md").read_text().replace("{name}", name))
+    plan.write_text((t/"PLAN_TEMPLATE.md").read_text().replace("{name}", name))
+    return spec, plan

specline/spec_lint.py

@@ -0,0 +1,49 @@
+"""specline validate — EARS/Gherkin/leak lint. A spec that fails here never
+reaches an agent, so ambiguity dies before it costs tokens."""
+from __future__ import annotations
+import re
+from pathlib import Path
+
+EARS = re.compile(r"^\s*-\s+(The system shall|When\b|While\b|If\b|Where\b)", re.M)
+REQ_LINE = re.compile(r"^\s*-\s+\S", re.M)
+
+
+def validate_spec(path: Path) -> list[str]:
+    text = Path(path).read_text()
+    errors = []
+    if "## MUST" not in text:
+        errors.append("E_NO_MUST: missing '## MUST — Functional core' section")
+    must = text.split("## SHOULD")[0]
+    reqs_section = must.split("### Requirements")[-1] if "### Requirements" in must else ""
+    req_lines = [l for l in REQ_LINE.findall(reqs_section)]
+    ears_hits = EARS.findall(reqs_section)
+    if not ears_hits:
+        errors.append("E_NO_EARS: no requirement uses an EARS keyword (shall/When/While/If/Where)")
+    non_ears = max(len(req_lines) - len(ears_hits), 0)
+    if req_lines and non_ears > len(req_lines) // 2:
+        errors.append(f"E_EARS_RATIO: {non_ears}/{len(req_lines)} requirement lines lack EARS keywords")
+    if "```gherkin" not in text:
+        errors.append("E_NO_GHERKIN: no acceptance criteria scenario found")
+    elif not re.search(r"Given .+", text) or not re.search(r"Then .+", text):
+        errors.append("E_GHERKIN_INCOMPLETE: scenario missing Given/Then")
+    fence_langs = re.findall(r"```(\w+)", must)
+    if any(lang != "gherkin" for lang in fence_langs):
+        errors.append("E_IMPL_LEAK: implementation code fence inside MUST section (belongs in plan)")
+    if re.search(r"## MUST.*?\b(def |class |function\(|=>)", must, re.S):
+        errors.append("E_IMPL_LEAK: code-level detail in MUST section")
+    if "Status: approved" in text and errors:
+        errors.append("E_APPROVED_BUT_INVALID: spec marked approved while failing lint")
+    return errors
+
+def decision_rows(path: Path) -> list[dict]:
+    """Parse the 'Decision logic (factory candidates)' table -> rules."""
+    text = Path(path).read_text()
+    if "## Decision logic" not in text:
+        return []
+    section = text.split("## Decision logic")[1]
+    rows = []
+    for line in section.splitlines():
+        m = re.match(r"\s*\|\s*(\d+)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*$", line)
+        if m:
+            rows.append({"n": int(m.group(1)), "if": m.group(2), "then": m.group(3)})
+    return rows

specline/specfactor.py

@@ -0,0 +1,21 @@
+"""SpecFactor gauge = spec lines / code lines, with the Goldilocks bands."""
+from __future__ import annotations
+from pathlib import Path
+
+def specfactor(root: Path) -> dict:
+    root = Path(root)
+    spec_lines = sum(len(p.read_text().splitlines()) for p in (root/"specs").glob("*.md")) if (root/"specs").exists() else 0
+    plan_lines = sum(len(p.read_text().splitlines()) for p in (root/"plans").glob("*.md")) if (root/"plans").exists() else 0
+    code_lines = 0
+    for d in ["slices", "skeleton"]:
+        if (root/d).exists():
+            for p in (root/d).rglob("*.*"):
+                try: code_lines += len(p.read_text().splitlines())
+                except Exception: pass
+    ratio = round((spec_lines + plan_lines) / code_lines, 2) if code_lines else float("inf")
+    if code_lines == 0: verdict = "no code yet"
+    elif ratio < 0.5: verdict = "UNDER-SPECIFIED: sliding toward vibe coding — expect hallucinations"
+    elif ratio <= 2.5: verdict = "Goldilocks zone"
+    else: verdict = "OVER-SPECIFIED: review bottleneck risk (>2.5)"
+    return {"spec_lines": spec_lines + plan_lines, "code_lines": code_lines,
+            "specfactor": ratio, "verdict": verdict}