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

code_factory_1_spec-0.3.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: code-factory-1-spec
+Version: 0.3.0
+Summary: SpecLine — a spec-driven production line for AI-assisted engineering: PRD -> spec -> plan -> atomic task packets -> gated code, with token-lean context hygiene and a compiled-decision handoff to Harness Software Factory (HSF).
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# SpecLine 🏭
+
+**A spec-driven production line for AI coding agents.** PRD → spec → plan →
+atomic task packets → gated code → production, with token-lean context
+hygiene enforced by tooling instead of discipline, and a compiled-decision
+handoff to [Harness Software Factory](../harness-factory) for the logic that
+should never be improvised twice.
+
+Works with **Claude Code, Codex, and any agent harness** — one command wires it in.
+
+## Workflow at a glance
+
+```mermaid
+flowchart LR
+    A["PRD or rough idea"] --> B["Draft spec"]
+    B --> C["Strict contract check"]
+    C -->|"blocks ambiguity"| B
+    C --> D["Gate spec and seal hash"]
+    D --> E["Create atomic plan"]
+    E --> F["Emit one task packet"]
+    F --> G["Agent builds exactly one slice"]
+    G --> H["Audit code against packet"]
+    H -->|"drift found"| F
+    H --> I["Gate code and update receipts"]
+    I --> J{"Decision table?"}
+    J -->|"yes"| K["Handoff to HSF"]
+    J -->|"no"| L["Ready for ForgeLine or PR"]
+```
+
+```
+PRD ──> Spec (EARS+Gherkin) ──> Gate ──> Plan (atomic tasks) ──> Gate
+                                                        │
+              ┌─────────────────────────────────────────┘
+              ▼
+   ┌── Ralph Wiggum Loop ──┐        Decision tables in the spec
+   │ specline loop next    │        ──> specline handoff
+   │  → token-budgeted     │        ──> HSF compiles them ONCE into
+   │    TASK PACKET        │            gated, deterministic code
+   │ agent does ONE task   │            (zero tokens per decision, forever)
+   │ specline loop done    │
+   │  → verify + seal      │
+   └──── context reset ────┘ ──> Gate ──> ship
+```
+
+## Why
+
+Vibe coding hits the wall around four files: context pollution, intent
+drift, API hallucinations. The fixes are known — specs as source of truth,
+constitutions, vertical slices, context resets — but they live in blog
+posts as *discipline*. SpecLine turns them into *tooling*: linted, gated,
+hash-sealed, and receipt-audited, so the discipline holds at 2am too.
+
+## Quickstart (5 minutes, no API keys)
+
+```bash
+pip install -e ".[dev]"
+specline init                      # constitution + six-file context system
+specline new refunds               # spec + plan skeletons
+# ... you + your agent fill the spec ...
+specline validate refunds          # EARS/Gherkin/leak lint — ambiguity dies here
+specline gate spec refunds        # hash-sealed human signoff
+specline tasks refunds             # atomicity lint: ≤4 files, one slice, verify cmd
+specline gate plan refunds        # locks the spec hash (drift guard arms)
+specline loop next refunds         # emits a token-budgeted TASK PACKET
+# ... agent session does exactly one packet ...
+specline loop done refunds T1      # runs verify command, seals receipt, advances
+specline handoff refunds           # decision table -> HSF workflow spec
+specline agent claude              # wires CLAUDE.md + /next-task command
+specline status                    # token-savings receipt
+pytest -q                          # 25 tests
+```
+
+## The mechanisms (what's actually enforced)
+
+| Blog-post advice | SpecLine enforcement |
+|---|---|
+| "Write clear specs" | EARS keyword lint, Gherkin required, implementation-leak detection (`E_IMPL_LEAK`) |
+| "Keep tasks small" | Atomicity linter: ≤4 files, one vertical slice, explicit verify command, no skeleton edits |
+| "Reset agent context" | The loop emits self-contained **task packets** under a hard ~2.2k-token budget; one packet = one session |
+| "Minimize context (C_t=γ·R_f·T_d)" | Packets list the exact R_f file set; excerpt only spec lines relevant to the task; deterministic prune over budget |
+| "Prevent intent drift" | Plan gate seals the spec hash; if the spec changes, the loop **refuses** (`E_INTENT_DRIFT`) until re-gated |
+| "Human review gates" | `specline gate spec|plan|code` writes hash-sealed signoff receipts to the progress tracker |
+| "Don't let agents improvise business rules" | Decision tables compile through HSF: one-time generation, four gates, zero tokens per decision |
+| "Measure the process" | SpecFactor gauge (Goldilocks 0.75–2.5) + a **context ledger**: packet tokens vs naive baseline, % saved |
+
+## Agent integration
+
+- **Claude Code:** `specline agent claude` → writes `CLAUDE.md` (constitution +
+  protocol) and `.claude/commands/next-task.md`. The whole loop is one slash command.
+- **Codex:** `specline agent codex` → appends the protocol to `AGENTS.md`
+  (Codex reads it natively).
+- **Anything else:** `specline agent <name>` → portable constitution file.
+  The protocol is plain text; any harness that can read a file can follow it.
+
+## The factory calibration (the part that saves real money)
+
+Most business logic in AI-built apps is *decision-shaped*: ordered rules over
+extracted facts. Letting agents re-implement those rules inline is how you get
+inconsistent behavior and burned tokens. SpecLine specs carry a
+`## Decision logic` table; `specline handoff` converts it to a Harness
+Software Factory spec, and HSF compiles it once into deterministic, gated,
+signed code — verified end-to-end in this repo's test suite against a real
+HSF install. App code flows through the line; decisions flow through the
+factory; nothing is improvised twice.
+
+## Receipts culture
+
+Every gate signoff, packet emission, and task completion writes a hash-sealed
+line to `context/PROGRESS.md`, and the context ledger accumulates the token
+economics (`specline status` — the walkthrough example shows ~75% saved vs
+naive full-context sessions, and the gap widens as the repo grows). Claims
+trace to receipts, never to vibes. That's the whole point.
+
+MIT licensed.
+
+---
+
+## v0.2 — Strict Input Contract & Drift Audit
+
+The base linter checks that a spec *looks* right (EARS keywords present, valid task
+format). That's necessary but not sufficient: it lets **ambiguity** through, and the
+AI coder then *invents* the missing parameters — which is drift. v0.2 closes that gap
+with two new stages that bracket the coder.
+
+### `specline strict <feature>` — reject ambiguity *before* the coder runs
+
+Treats the spec as a **contract the coder must execute with zero invention**. Every
+finding is a BLOCK with an exact line and fix. It catches the five drift sources:
+
+1. **Incomplete requirements** — an EARS keyword isn't enough. Each requirement must
+   have a concrete outcome verb (`return`/`reject`/`store`/…), not `handle`/`support`/
+   `manage`. `The system shall handle it appropriately` is rejected.
+2. **Surviving placeholders** — `<trigger>`, `<N>`, `TBD` can't reach an approved spec.
+3. **Unquantified bounds** — a requirement that implies a timeout/limit/retry/size must
+   state a number+unit.
+4. **Untraceable acceptance** — every value in a Given/When/Then must be defined in a
+   requirement or the data model. A Gherkin step can't introduce a fact the coder would
+   have to invent.
+5. **Non-deterministic decisions** — each rule's `if` references a declared fact and its
+   `then` is exactly one outcome. No `maybe`/`or`/`etc`; no duplicate conditions.
+   (`else`/`default` catch-all rows are allowed.)
+
+An `approved` spec that still fails strict raises `S_APPROVED_BUT_AMBIGUOUS` — approval
+is a lie until the blocks are resolved.
+
+Strict is **on by default** in `specline gate spec|plan`. Pass `strict=False` to the
+gate API only for legacy specs.
+
+### `specline audit <feature> --files … --slice …` — catch drift *after* the coder runs
+
+Compares what shipped against what the contract authorized:
+
+- **`A_INVENTED_PARAM`** — a config value (`TIMEOUT = 45`) whose number the spec never
+  authorized. The coder guessed; the audit fails the build.
+- **`A_SCOPE_ESCAPE`** — a file outside the task's authorized slice.
+- **`A_UNAUTHORIZED_FILE`** — a file not in the packet's list.
+- **`A_STUB_LEFT`** — a `TODO`/`NotImplementedError` left behind.
+
+### Requirement-scoped packets
+
+The packet excerpt no longer bag-of-words-matches individual lines (which could hand the
+agent half a requirement). It now ships **whole requirement blocks** and the **complete
+acceptance scenario intact** — the agent never receives a partial rule to improvise around.
+
+### Flow
+
+```
+new → write spec → validate → strict → gate spec → write plan → tasks → gate plan
+    → loop (build) → audit → gate code → handoff
+```
+
+Deterministic by design: same spec text → same findings, every run. No LLM, no clock.
+## Failure attribution
+
+SpecLine 0.3 reports strict-lint results per requirement and drift-audit results
+per Python function. Failed units include a stable class such as
+`ambiguous_requirement`, `untyped_input`, `invented_param`, or `scope_escape`,
+plus the offending source phrase or code location. Existing pass/fail rules do
+not change.
+
+For machine-readable output:
+
+```bash
+specline strict my_feature --json
+specline audit my_feature --files slices/my_feature/logic.py --json
+```

code_factory_1_spec-0.3.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+code_factory_1_spec-0.3.0.dist-info/licenses/LICENSE,sha256=yrgL2BXp2X7HE1O6CSW1Y8loro0WundDyBFj5twonXU,1088
+specline/__init__.py,sha256=n3z3vr1oFsBi0hRr1HA-iVUdVpOtzGzuKrnQiTLs_rU,706
+specline/adapters.py,sha256=BF4Li55BkTB0S4TZ9zM9yfYXm4kUMj-7U4v25AomALo,1617
+specline/attribution.py,sha256=1kexJ7Q8QmfHwrDbAq2NrWySruNSee91-uzsX3umBKM,1888
+specline/cli.py,sha256=7WYTn61vB71H69v7Eg0JQ7RGCAWsWpP_3HTIGcM71ME,6893
+specline/drift_audit.py,sha256=6idWpp1wgJ2Eg_j2_4MJZcKrFB7YitPa5MQaW8YFTEk,6579
+specline/gates.py,sha256=BW5DHK3y_bF0s09mgsnl4mrK4Cs_VxDBlD5obajZCc0,1920
+specline/handoff.py,sha256=XkhY_FEyQyVjPNn5r_IsjrOpoWEZjqfbASuUr-iqCoA,2354
+specline/ledger.py,sha256=zN8yTG_37zxTs6TpZCD-ylK5b36v6KLLoF06Uz5hi5Y,1833
+specline/loop.py,sha256=IfCUUz9AbK-VsD7IY16lFIDuxFW6b0QOv0PicO4m38c,3151
+specline/packets.py,sha256=3KkcUoXVVGH2EZmOa6s-Y-oxW2oCL-Miie8AJinI6P0,4341
+specline/paths.py,sha256=u_VoCXX9gxw2oFu-cWe28EXRqrFmU_0H-YrSd8Oub3w,465
+specline/plan_lint.py,sha256=kLSyJwvkSZb_vzpYX788rAfe2gcp8_K8CY7kWEGsiBk,1821
+specline/scaffold.py,sha256=nQX3AOhD4wShn4-da7mXoSABHZzK4qAeKNhfdD5-2Ns,1800
+specline/spec_lint.py,sha256=-ech9dZjfgTH7wyGmdXLr_WOCJyhggAk1gZJzGp8P0I,2439
+specline/specfactor.py,sha256=pD2l2Sw-Ixn5r_vp1Pv6NL5Gg-qZT7uuTKl4wEqBCGY,1197
+specline/strict_lint.py,sha256=C2KpUAfNj-GdjYS6GqAfhUVGdr4ZAHIfmQzV5kQtJL0,14575
+templates/AGENTS.md,sha256=X4Ygn4SYslNv8HfreMwu9g3Ap2XZ98Eq334KEigb-fw,1120
+templates/PLAN_TEMPLATE.md,sha256=2L9V5UIT6UtXRBqym8TEjtZ-vm153_Wp4JKdzxnVjSM,396
+templates/SPEC_TEMPLATE.md,sha256=yfRv2djQwgD7HY0vkeyxt0AirL0trgoxt3_4G4j8BkU,947
+templates/context/AI_WORKFLOW_RULES.md,sha256=8551l9DA68XjkAy_UOeqRvQ8ZAlDnlpcWae-kMLhAoY,289
+templates/context/ARCHITECTURE.md,sha256=exckCOT_eDEzvrZ00iND_lFYSkovMbhRQYuG3Yrq4kc,467
+templates/context/CODE_STANDARDS.md,sha256=0RD_R0i3Qu9ipvkGdbrUlW1xHrJp7NawpwULwJypSIk,92
+templates/context/PROGRESS.md,sha256=Q04lOJe_1QSp7X6ZE8Vc4mu2d-sQ50nM3lFCgGcCl08,123
+templates/context/PROJECT_OVERVIEW.md,sha256=nlEE3BhMvSeTmYXsc2a8RIopOp__VPmgtNXkm009qGs,122
+templates/context/UI_CONTEXT.md,sha256=RpKsV7k1EMJUDBJpMoOJWPJYWa33UeIHZUXYpkh8uLw,62
+templates/personas/reviewer.md,sha256=fiFvz0C7enGcx9YVKRFDO3wNw-FIGVyK4q_UYPOt3tU,377
+templates/personas/security_auditor.md,sha256=6_1y0caYLMJJDeSmduuH1JzvUuY-ttR1PCh34Drf1Ac,331
+code_factory_1_spec-0.3.0.dist-info/METADATA,sha256=CAbzN8-XRreke3XwPFRrZ3L10sYWX5aI_dmgAbau78Y,9842
+code_factory_1_spec-0.3.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+code_factory_1_spec-0.3.0.dist-info/entry_points.txt,sha256=u7onuG3BPSfKRCnvBzUpiOI16hO2S4fkkY3OTo_cY2g,47
+code_factory_1_spec-0.3.0.dist-info/top_level.txt,sha256=c1gyltWWOPbRVaq6pW3E0oI3p7G_0X_qotHeOENv7X8,9
+code_factory_1_spec-0.3.0.dist-info/RECORD,,

code_factory_1_spec-0.3.0.dist-info/WHEEL

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

code_factory_1_spec-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+specline = specline.cli:main

code_factory_1_spec-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WizeMe.APP
+
+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.

code_factory_1_spec-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+specline

specline/__init__.py

@@ -0,0 +1,16 @@
+"""SpecLine — the spec-driven production line.
+
+Vibe coding fails at the four-file mark; SpecLine replaces it with a
+standardized, tool-agnostic operating procedure any coding agent
+(Claude Code, Codex, others) can follow:
+
+  PRD -> Spec (EARS) -> Plan -> Atomic Tasks -> Task Packets (token-lean)
+      -> Ralph Wiggum execution loop -> Review Gates -> Production
+
+Decision-shaped logic (ordered rules over extracted facts) doesn't go
+through agents at all: `specline handoff` emits a Harness Software
+Factory workflow spec so it can be compiled ONCE into gated,
+deterministic code. Agents write tissue; humans own the skeleton;
+the factory owns the decisions.
+"""
+__version__ = "0.1.0"

specline/adapters.py

@@ -0,0 +1,32 @@
+"""Agent adapters — one command wires SpecLine into Claude Code, Codex, or
+any agent harness. The constitution IS the agent config; packets are the
+session protocol; slash commands make the loop one keystroke."""
+from __future__ import annotations
+import shutil
+from pathlib import Path
+
+CLAUDE_NEXT_CMD = """Read context/PROGRESS.md, then run `specline loop next <feature>`.
+Open ONLY the packet file it prints and the files the packet lists.
+Complete the packet's single task, run its verify command, then run
+`specline loop done <feature> <task-id>` and STOP. Do not start another task.
+"""
+
+def wire_agent(root: Path, agent: str) -> list[Path]:
+    root = Path(root); created = []
+    constitution = (root/"AGENTS.md").read_text()
+    if agent in {"claude", "claude-code"}:
+        dst = root/"CLAUDE.md"
+        dst.write_text(constitution + "\n\n## SpecLine protocol\n" + CLAUDE_NEXT_CMD)
+        created.append(dst)
+        cmd_dir = root/".claude"/"commands"; cmd_dir.mkdir(parents=True, exist_ok=True)
+        c = cmd_dir/"next-task.md"; c.write_text(CLAUDE_NEXT_CMD); created.append(c)
+    elif agent == "codex":
+        # Codex reads AGENTS.md natively; append the protocol if absent
+        if "SpecLine protocol" not in constitution:
+            (root/"AGENTS.md").write_text(constitution + "\n\n## SpecLine protocol\n" + CLAUDE_NEXT_CMD)
+        created.append(root/"AGENTS.md")
+    else:
+        dst = root/f"{agent.upper()}_AGENT.md"
+        dst.write_text(constitution + "\n\n## SpecLine protocol\n" + CLAUDE_NEXT_CMD)
+        created.append(dst)
+    return created

specline/attribution.py

@@ -0,0 +1,60 @@
+"""Standalone copy of the factory attribution contract."""
+from dataclasses import asdict, dataclass
+from enum import Enum
+
+
+class FailureClass(str, Enum):
+    AMBIGUOUS_REQUIREMENT = "ambiguous_requirement"
+    UNTYPED_INPUT = "untyped_input"
+    SCOPE_ESCAPE = "scope_escape"
+    INVENTED_PARAM = "invented_param"
+    SIGNATURE_DRIFT = "signature_drift"
+    STUB_UNFILLED = "stub_unfilled"
+    COMPLEXITY_EXCEEDED = "complexity_exceeded"
+    INCONSISTENT_LOGIC = "inconsistent_logic"
+    RUNTIME_CRASH = "runtime_crash"
+    RUNTIME_TIMEOUT = "runtime_timeout"
+    WRONG_OUTPUT = "wrong_output"
+    ACCURACY_REGRESSION = "accuracy_regression"
+    NONDETERMINISM = "nondeterminism"
+    SECURITY_FINDING = "security_finding"
+
+
+@dataclass(frozen=True)
+class UnitResult:
+    unit: str
+    stage: str
+    passed: bool
+    evidence: str
+    failure_class: FailureClass | None = None
+
+    def __post_init__(self):
+        if not self.passed and (self.failure_class is None or not self.evidence.strip()):
+            raise ValueError("failed units require a class and concrete evidence")
+
+
+@dataclass
+class Attribution:
+    stage: str
+    n_checked: int
+    n_passed: int
+    units: list[UnitResult]
+
+    @property
+    def rate(self):
+        return self.n_passed / self.n_checked if self.n_checked else 0.0
+
+    def dominant_failure_class(self):
+        counts = {kind: 0 for kind in FailureClass}
+        for unit in self.units:
+            if not unit.passed:
+                counts[unit.failure_class] += 1
+        maximum = max(counts.values(), default=0)
+        return next((kind for kind in FailureClass if maximum and counts[kind] == maximum), None)
+
+    def to_dict(self):
+        value = asdict(self)
+        value["rate"] = self.rate
+        dominant = self.dominant_failure_class()
+        value["dominant_failure_class"] = dominant.value if dominant else None
+        return value

specline/cli.py

@@ -0,0 +1,136 @@
+"""specline CLI — the production line, end to end:
+init -> new -> (write spec) -> validate -> gate spec -> (write plan) ->
+tasks -> gate plan -> loop next/done ... -> gate code -> handoff -> status
+"""
+from __future__ import annotations
+import argparse, json
+from pathlib import Path
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="specline", description="Spec-driven production line for AI coding agents")
+    sub = p.add_subparsers(required=True, dest="cmd")
+
+    s = sub.add_parser("init", help="scaffold constitution + six-file context system")
+    s.add_argument("--root", default=".")
+
+    s = sub.add_parser("new", help="create spec+plan skeleton for a feature")
+    s.add_argument("feature"); s.add_argument("--root", default=".")
+
+    s = sub.add_parser("validate", help="lint a spec (EARS/Gherkin/leaks)")
+    s.add_argument("feature"); s.add_argument("--root", default=".")
+
+    s = sub.add_parser("strict", help="STRICT semantic input contract — reject ambiguity before the coder")
+    s.add_argument("feature"); s.add_argument("--root", default=".")
+    s.add_argument("--warn", action="store_true", help="also show WARN-level smells")
+    s.add_argument("--json", action="store_true", help="emit machine-readable attribution")
+
+    s = sub.add_parser("audit", help="post-code drift audit (invented params / scope escape / stubs)")
+    s.add_argument("feature"); s.add_argument("--root", default=".")
+    s.add_argument("--files", nargs="+", required=True, help="changed files to audit")
+    s.add_argument("--slice", default=None, help="authorized slice prefix")
+    s.add_argument("--json", action="store_true", help="emit machine-readable attribution")
+
+    s = sub.add_parser("tasks", help="lint plan task atomicity")
+    s.add_argument("feature"); s.add_argument("--root", default=".")
+
+    s = sub.add_parser("gate", help="record a human gate signoff (spec|plan|code)")
+    s.add_argument("phase", choices=["spec", "plan", "code"]); s.add_argument("feature")
+    s.add_argument("--approver", default="human"); s.add_argument("--root", default=".")
+
+    s = sub.add_parser("loop", help="Ralph Wiggum loop: next | done")
+    s.add_argument("action", choices=["next", "done"]); s.add_argument("feature")
+    s.add_argument("task_id", nargs="?"); s.add_argument("--no-verify", action="store_true")
+    s.add_argument("--root", default=".")
+
+    s = sub.add_parser("handoff", help="emit HSF workflow spec from decision table")
+    s.add_argument("feature"); s.add_argument("--root", default=".")
+
+    s = sub.add_parser("agent", help="wire into an agent harness (claude|codex|<name>)")
+    s.add_argument("name"); s.add_argument("--root", default=".")
+
+    s = sub.add_parser("specfactor", help="spec/code ratio gauge")
+    s.add_argument("--root", default=".")
+
+    s = sub.add_parser("status", help="progress + token-savings receipt")
+    s.add_argument("--root", default=".")
+
+    a = p.parse_args(argv)
+    root = Path(a.root)
+
+    if a.cmd == "init":
+        from .scaffold import init_project
+        created = init_project(root)
+        print("created:\n  " + "\n  ".join(str(c) for c in created))
+        print("next: specline new <feature>")
+    elif a.cmd == "new":
+        from .scaffold import new_feature
+        spec, plan = new_feature(root, a.feature)
+        print(f"spec: {spec}\nplan: {plan}\nnext: fill the spec, then `specline validate {a.feature}`")
+    elif a.cmd == "validate":
+        from .spec_lint import validate_spec
+        errs = validate_spec(root/"specs"/f"{a.feature}.md")
+        if errs: raise SystemExit("INVALID:\n" + "\n".join(errs))
+        print("spec OK — next: specline strict " + a.feature)
+    elif a.cmd == "strict":
+        from .strict_lint import strict_validate
+        spec_path = root/"specs"/f"{a.feature}.md"
+        rep = strict_validate(spec_path)
+        if a.json:
+            print(json.dumps({"passed": rep.ok,
+                              "attribution": rep.attribution(spec_path.read_text()).to_dict()},
+                             indent=2))
+        for f in (rep.findings if a.warn else rep.blocks):
+            print(str(f))
+        if rep.blocks:
+            raise SystemExit(f"\nSTRICT FAILED: {len(rep.blocks)} blocking ambiguity(ies) — "
+                             f"the coder would guess these. Fix before gating.")
+        print(f"STRICT OK — spec is unambiguous ({len(rep.warns)} warns). "
+              f"next: specline gate spec {a.feature}")
+    elif a.cmd == "audit":
+        from .drift_audit import audit_code_against_spec, audit_report_lines
+        rep = audit_code_against_spec(root/"specs"/f"{a.feature}.md",
+                                      [Path(f) for f in a.files], slice_prefix=a.slice)
+        if a.json:
+            print(json.dumps({"passed": rep.ok,
+                              "attribution": rep.attribution([Path(f) for f in a.files]).to_dict()},
+                             indent=2))
+        for line in audit_report_lines(rep):
+            print(line)
+        if rep.blocks:
+            raise SystemExit(f"\nAUDIT FAILED: {len(rep.blocks)} drift(s) detected.")
+        print(f"AUDIT OK — no drift ({len(rep.warns)} warns).")
+    elif a.cmd == "tasks":
+        from .plan_lint import lint_plan
+        tasks, errs = lint_plan(root/"plans"/f"{a.feature}.md")
+        if errs: raise SystemExit("PLAN INVALID:\n" + "\n".join(errs))
+        print(f"{len(tasks)} atomic tasks OK — next: specline gate plan " + a.feature)
+    elif a.cmd == "gate":
+        from .gates import gate
+        print(json.dumps(gate(root, a.phase, a.feature, a.approver)))
+    elif a.cmd == "loop":
+        from .loop import next_task, mark_done
+        if a.action == "next":
+            print(json.dumps(next_task(root, a.feature), indent=2))
+        else:
+            if not a.task_id: raise SystemExit("task_id required for done")
+            print(json.dumps(mark_done(root, a.feature, a.task_id, run_verify=not a.no_verify)))
+    elif a.cmd == "handoff":
+        from .handoff import handoff_to_hsf
+        out = handoff_to_hsf(root, a.feature)
+        print(f"HSF spec: {out}\ncompile with: hsf compile {out}")
+    elif a.cmd == "agent":
+        from .adapters import wire_agent
+        created = wire_agent(root, a.name)
+        print("wired:\n  " + "\n  ".join(str(c) for c in created))
+    elif a.cmd == "specfactor":
+        from .specfactor import specfactor
+        print(json.dumps(specfactor(root), indent=2))
+    elif a.cmd == "status":
+        from .ledger import summarize
+        s = summarize(root)
+        print(json.dumps(s, indent=2))
+        if s["sessions"]:
+            print(f"→ packets used {s['packet_tokens']:,} est. tokens vs {s['naive_tokens']:,} naive: {s['saved_pct']}% saved")
+
+if __name__ == "__main__":
+    main()

specline/drift_audit.py

@@ -0,0 +1,150 @@
+"""specline audit — the post-coding drift detector.
+
+strict_lint stops ambiguity BEFORE the coder runs. This catches drift AFTER:
+it compares what shipped against what the contract authorized, and fails when
+the coder invented parameters, referenced undefined entities, or widened scope.
+
+Deterministic: it parses, it does not judge intent.
+"""
+from __future__ import annotations
+import re
+import ast
+from dataclasses import dataclass, field
+from pathlib import Path
+from .strict_lint import _declared_terms, _requirement_lines, Finding
+
+_MAGIC_NUMBER = re.compile(r"(?<![\w.])(\d+)(?![\w.])")
+_PARAM_ASSIGN = re.compile(
+    r"\b([A-Z][A-Z0-9_]{2,})\s*=\s*([^\n#]+)"
+    r"|\b(timeout|retries|max_\w+|min_\w+|limit|threshold|ttl|batch_size|"
+    r"page_size|expiry|expires_in)\s*[:=]\s*([^\n#,)]+)", re.I)
+
+
+@dataclass
+class AuditReport:
+    findings: list[Finding] = field(default_factory=list)
+    @property
+    def blocks(self): return [f for f in self.findings if f.severity == "BLOCK"]
+    @property
+    def warns(self): return [f for f in self.findings if f.severity == "WARN"]
+    @property
+    def ok(self) -> bool: return not self.blocks
+    def add(self, code, severity, message, line=0):
+        self.findings.append(Finding(code, severity, message, line))
+
+    def attribution(self, changed_files):
+        from .attribution import Attribution, FailureClass, UnitResult
+        units = []
+        for file_path in changed_files:
+            path = Path(file_path)
+            path_text = str(path)
+            file_findings = [f for f in self.blocks if path_text in f.message]
+            spans = []
+            if path.exists() and path.suffix == ".py":
+                try:
+                    tree = ast.parse(path.read_text())
+                    spans = [
+                        (node.name, node.lineno, getattr(node, "end_lineno", node.lineno))
+                        for node in ast.walk(tree)
+                        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+                    ]
+                except (SyntaxError, OSError, UnicodeDecodeError):
+                    spans = []
+            if not spans:
+                spans = [("<module>", 1, 10**9)]
+            for function_name, start, end in sorted(spans, key=lambda item: (item[1], item[0])):
+                related = [
+                    finding for finding in file_findings
+                    if finding.line == 0 or start <= finding.line <= end
+                ]
+                failure_class = None
+                if related:
+                    code = related[0].code
+                    failure_class = (
+                        FailureClass.INVENTED_PARAM if code == "A_INVENTED_PARAM"
+                        else FailureClass.STUB_UNFILLED if code == "A_STUB_LEFT"
+                        else FailureClass.SCOPE_ESCAPE
+                    )
+                units.append(UnitResult(
+                    unit=f"function:{path_text}:{function_name}",
+                    stage="drift_audit",
+                    passed=not related,
+                    evidence="no drift found" if not related else related[0].message,
+                    failure_class=failure_class,
+                ))
+        return Attribution("drift_audit", len(units), sum(u.passed for u in units), units)
+
+
+def _spec_authorized_numbers(spec_text: str) -> set[str]:
+    return {m.group(1) for m in re.finditer(r"\b(\d+(?:\.\d+)?)\b", spec_text)}
+
+
+def _in_slice(fp: Path, slice_prefix: str | None) -> bool:
+    """Segment-aware slice membership: an absolute path .../refund/logic.py is
+    inside slice 'refund'. This is what made the naive str.startswith unreliable."""
+    if slice_prefix is None:
+        return True
+    sp = slice_prefix.rstrip("/")
+    parts = fp.parts
+    if sp in parts:
+        return True
+    for i in range(len(parts)):
+        tail = "/".join(parts[i:])
+        if tail == sp or tail.startswith(sp + "/"):
+            return True
+    return False
+
+
+def audit_code_against_spec(spec_path, changed_files, slice_prefix=None, packet_files=None):
+    rep = AuditReport()
+    spec_text = Path(spec_path).read_text()
+    ok_numbers = _spec_authorized_numbers(spec_text)
+    authorized = {str(f) for f in (packet_files or [])}
+
+    for fp in changed_files:
+        fp = Path(fp)
+        rel = str(fp)
+        # Only the FILENAME determines test-ness. The full path can contain
+        # 'test' incidentally (e.g. pytest temp dirs), which would wrongly
+        # suppress scope/param findings.
+        is_test = fp.name.lower().startswith("test") or fp.name.lower().endswith("_test.py") \
+            or "tests" in fp.parts
+
+        if slice_prefix and not _in_slice(fp, slice_prefix) and not is_test:
+            rep.add("A_SCOPE_ESCAPE", "BLOCK",
+                    f"{rel} is outside the authorized slice {slice_prefix!r}. The coder widened "
+                    f"scope beyond its task.")
+        if authorized and rel not in authorized and not is_test:
+            rep.add("A_UNAUTHORIZED_FILE", "BLOCK",
+                    f"{rel} was not in the packet's file list — packet was wrong or coder invented "
+                    f"a file.")
+
+        if not fp.exists() or fp.is_dir():
+            continue
+        try:
+            code = fp.read_text()
+        except (UnicodeDecodeError, OSError):
+            continue
+
+        for i, ln in enumerate(code.splitlines(), 1):
+            stripped = ln.strip()
+            if stripped.startswith(("#", "//", "*", "/*")):
+                continue
+            for m in _PARAM_ASSIGN.finditer(ln):
+                val = (m.group(2) or m.group(4) or "").strip()
+                for num in _MAGIC_NUMBER.findall(val):
+                    if num not in ok_numbers:
+                        name = (m.group(1) or m.group(3) or "param").strip()
+                        rep.add("A_INVENTED_PARAM", "BLOCK",
+                                f"{rel}:{i} sets {name}={val} but the spec never authorizes the "
+                                f"value {num}. Invented parameter — add to spec or remove.", i)
+                        break
+            if re.search(r"\b(TODO|FIXME|XXX|NotImplemented|raise NotImplementedError)\b", ln):
+                rep.add("A_STUB_LEFT", "BLOCK",
+                        f"{rel}:{i} leaves a stub/TODO — constitution forbids shipping incomplete "
+                        f"work.", i)
+    return rep
+
+
+def audit_report_lines(rep: AuditReport) -> list[str]:
+    return [str(f) for f in rep.findings]