trueline 0.1.0.dev0__py3-none-any.whl

trueline/__init__.py

@@ -0,0 +1 @@
+"""trueline — Spec-Driven Development framework for Claude Code users."""

trueline/__main__.py

@@ -0,0 +1,9 @@
+"""Enable ``python -m trueline`` — the entry the adopt-run orchestrator spawns
+(``[sys.executable, "-m", "trueline", …]``; see ``cli/adopt_run.py``'s ``_spawn``,
+designed PATH-robust/venv-correct in ``M4-IMPL-PLAN.md``). It delegates to the same
+``run()`` console-script entry as ``[project.scripts]`` so the ``-m`` invocation and the
+installed ``trueline`` binary share one framework-error boundary and one exit-code contract."""
+
+from trueline.cli import run
+
+run()

trueline/adoption/__init__.py

@@ -0,0 +1,72 @@
+"""Adoption (brownfield RE) home: records I/O, facts, parsers, derived state (M4 §2)."""
+
+from trueline.adoption.facts import AdoptionFacts, build_adoption_facts
+from trueline.adoption.records import (
+    ADOPTION_DIR,
+    AdoptionRecordError,
+    adoption_home,
+    approval_path,
+    assembly_dir,
+    audits_dir,
+    base_branch_path,
+    capability_plan_path,
+    constraints_dir,
+    describe_marker_path,
+    description_path,
+    dispositions_dir,
+    flip_path,
+    map_path,
+    module_dir,
+    provenance_path,
+    read_approval,
+    read_audits,
+    read_base_branch,
+    read_capability_plan,
+    read_constraints,
+    read_describe_marker,
+    read_dispositions,
+    read_flip,
+    read_map,
+    read_provenance,
+    read_suite_run,
+    read_validation,
+    suite_log_path,
+    suite_run_path,
+    validation_path,
+)
+
+__all__ = [
+    "ADOPTION_DIR",
+    "AdoptionFacts",
+    "AdoptionRecordError",
+    "adoption_home",
+    "approval_path",
+    "assembly_dir",
+    "audits_dir",
+    "base_branch_path",
+    "build_adoption_facts",
+    "capability_plan_path",
+    "constraints_dir",
+    "describe_marker_path",
+    "description_path",
+    "dispositions_dir",
+    "flip_path",
+    "map_path",
+    "module_dir",
+    "provenance_path",
+    "read_approval",
+    "read_audits",
+    "read_base_branch",
+    "read_capability_plan",
+    "read_constraints",
+    "read_describe_marker",
+    "read_dispositions",
+    "read_flip",
+    "read_map",
+    "read_provenance",
+    "read_suite_run",
+    "read_validation",
+    "suite_log_path",
+    "suite_run_path",
+    "validation_path",
+]

trueline/adoption/assemble.py

@@ -0,0 +1,270 @@
+"""Assembly substrate (M4 §2.5): the digest, the plan/provenance recomputations
+and the invalidation rule — pure over preloaded facts (the command is the shell).
+"""
+
+from pathlib import Path
+
+from pydantic import Field, ValidationError
+
+from trueline.adoption.parse import DescriptionFacts, parse_description
+from trueline.adoption.records import description_path
+from trueline.fold import parse_delta
+from trueline.schemas import StrictModel
+from trueline.schemas.adoption import (
+    AdoptionMap,
+    CapabilityPlan,
+    PlanAssignment,
+    ProvenanceEntry,
+    ProvenanceMap,
+    ProvenanceSource,
+)
+
+
+class DigestEntry(StrictModel):
+    part: str
+    module: str
+    requirement: str
+    summary: str
+
+
+class PlanParseError(RuntimeError):
+    """The planner output failed the schema — the corrective payload carries the why."""
+
+
+def read_descriptions(home: Path, map_: AdoptionMap) -> dict[str, DescriptionFacts]:
+    """part-qualified module id → parsed description facts (the I/O read, done once)."""
+    facts: dict[str, DescriptionFacts] = {}
+    for part_id, part_map in map_.parts.items():
+        for module_id in part_map.modules:
+            path = description_path(home, part_id, module_id)
+            text = path.read_text(encoding="utf-8") if path.is_file() else ""
+            facts[f"{part_id}/{module_id}"] = parse_description(text)
+    return facts
+
+
+def requirement_digest(descriptions: dict[str, DescriptionFacts]) -> list[DigestEntry]:
+    """One entry per requirement — part, module, header, SUMMARY (bodies out BY
+    CONSTRUCTION: the digest is a mechanical extraction, never an instruction)."""
+    entries: list[DigestEntry] = []
+    for qualified in sorted(descriptions):
+        part, module = qualified.split("/", 1)
+        for requirement in descriptions[qualified].requirements:
+            entries.append(
+                DigestEntry(
+                    part=part,
+                    module=module,
+                    requirement=requirement.name,
+                    summary=requirement.summary or "",
+                )
+            )
+    return entries
+
+
+def render_digest(entries: list[DigestEntry]) -> str:
+    if not entries:
+        return "(no requirements — every described module is empty)"
+    return "\n".join(
+        f"- {e.part} / {e.module} / {e.requirement} — SUMMARY: {e.summary}" for e in entries
+    )
+
+
+class PlannerOutput(StrictModel):
+    assignments: list[PlanAssignment] = Field(default_factory=lambda: list[PlanAssignment]())
+
+
+def convert_planner_output(raw: object) -> CapabilityPlan:
+    try:
+        output = PlannerOutput.model_validate(raw)
+    except ValidationError as exc:
+        raise PlanParseError(f"the plan does not parse: {exc.errors()[0]['msg']}") from exc
+    return CapabilityPlan(assignments=output.assignments)
+
+
+def _key(part: str, module: str, requirement: str) -> tuple[str, str, str]:
+    return (part, module, requirement)
+
+
+def plan_completeness_defects(plan: CapabilityPlan, digest: list[DigestEntry]) -> list[str]:
+    """Every digest entry assigned EXACTLY once; nothing outside the digest."""
+    defects: list[str] = []
+    digest_keys = {_key(e.part, e.module, e.requirement) for e in digest}
+    counts: dict[tuple[str, str, str], int] = {}
+    for assignment in plan.assignments:
+        key = _key(assignment.part, assignment.module, assignment.requirement)
+        counts[key] = counts.get(key, 0) + 1
+        if key not in digest_keys:
+            defects.append(
+                f"unknown entry: {assignment.part}/{assignment.module} "
+                f"{assignment.requirement!r} is not in the digest"
+            )
+    for key, count in sorted(counts.items()):
+        if count > 1 and key in digest_keys:
+            defects.append(f"duplicated entry: {key[0]}/{key[1]} {key[2]!r} assigned {count} times")
+    for key in sorted(digest_keys - set(counts)):
+        defects.append(f"unassigned entry: {key[0]}/{key[1]} {key[2]!r}")
+    return defects
+
+
+def stale_plan_entries(plan: CapabilityPlan, digest: list[DigestEntry]) -> list[str]:
+    """Plan entries resolving to NO current requirement (§2.5: a stale entry is a
+    pointed refusal, never a silent drop or a phantom in the provenance)."""
+    digest_keys = {_key(e.part, e.module, e.requirement) for e in digest}
+    return [
+        f"{a.part}/{a.module} {a.requirement!r} → {a.capability}"
+        for a in plan.assignments
+        if _key(a.part, a.module, a.requirement) not in digest_keys
+    ]
+
+
+class AssemblerProvenanceSource(StrictModel):
+    part: str
+    module: str
+    requirement: str
+
+
+class AssemblerProvenanceEntry(StrictModel):
+    requirement: str  # the emitted (capability) header, verbatim
+    sources: list[AssemblerProvenanceSource]
+
+
+class AssemblerOutput(StrictModel):
+    provenance: list[AssemblerProvenanceEntry]
+
+
+class AssemblerParseError(RuntimeError):
+    """The assembler response failed the schema."""
+
+
+def convert_assembler_output(raw: object) -> list[AssemblerProvenanceEntry]:
+    try:
+        return AssemblerOutput.model_validate(raw).provenance
+    except ValidationError as exc:
+        raise AssemblerParseError(
+            f"the provenance does not parse: {exc.errors()[0]['msg']}"
+        ) from exc
+
+
+def assembly_coverage_defects(
+    assigned: list[PlanAssignment],
+    entries: list[AssemblerProvenanceEntry],
+    delta_text: str,
+) -> list[str]:
+    """The per-capability postcondition: every assigned requirement accounted for in
+    the provenance AND every emitted header exists in the delta (all-ADDED); no
+    source outside the assigned set."""
+    defects: list[str] = []
+    assigned_keys = {_key(a.part, a.module, a.requirement) for a in assigned}
+    covered: set[tuple[str, str, str]] = set()
+    delta_names = {block.name for block in parse_delta(delta_text).added}
+    for entry in entries:
+        if entry.requirement not in delta_names:
+            defects.append(
+                f"provenance names {entry.requirement!r}, which is not an ADDED "
+                "requirement of the delta"
+            )
+        for source in entry.sources:
+            key = _key(source.part, source.module, source.requirement)
+            if key not in assigned_keys:
+                defects.append(
+                    f"unassigned source: {source.part}/{source.module} {source.requirement!r}"
+                )
+            covered.add(key)
+    for key in sorted(assigned_keys - covered):
+        defects.append(f"assigned requirement unaccounted for: {key[0]}/{key[1]} {key[2]!r}")
+    for name in sorted(delta_names - {entry.requirement for entry in entries}):
+        defects.append(f"delta requirement {name!r} has no provenance entry")
+    return defects
+
+
+def join_evidence(
+    capability: str,
+    entries: list[AssemblerProvenanceEntry],
+    descriptions: dict[str, DescriptionFacts],
+    blobs: dict[str, str | None],
+) -> list[ProvenanceEntry]:
+    """The evidence lines are joined MECHANICALLY by the framework (from the parsed
+    descriptions) — the model reports keys only. Each source is stamped with its
+    module's committed description blob (`blobs`) so the next `assemble` can rebuild
+    on a same-header content correction (M4 §2.5)."""
+    joined: list[ProvenanceEntry] = []
+    for entry in entries:
+        sources: list[ProvenanceSource] = []
+        for source in entry.sources:
+            facts = descriptions.get(f"{source.part}/{source.module}")
+            evidence: list[str] = []
+            if facts is not None:
+                for requirement in facts.requirements:
+                    if requirement.name == source.requirement:
+                        evidence = [
+                            *(f"EVIDENCE: {value}" for value in requirement.evidence),
+                            *(f"EVIDENCE-TEST: {value}" for value in requirement.evidence_tests),
+                        ]
+                        break
+            sources.append(
+                ProvenanceSource(
+                    part=source.part,
+                    module=source.module,
+                    requirement=source.requirement,
+                    evidence=evidence,
+                    blob=blobs.get(f"{source.part}/{source.module}"),
+                )
+            )
+        joined.append(
+            ProvenanceEntry(capability=capability, requirement=entry.requirement, sources=sources)
+        )
+    return joined
+
+
+def capabilities_to_build(
+    plan: CapabilityPlan,
+    previous: ProvenanceMap | None,
+    digest: list[DigestEntry],
+    specs_dir: Path,
+    current_blobs: dict[str, str | None],
+) -> list[str]:
+    """Per-capability resume + wholesale invalidation (§2.5): rebuild a capability
+    iff its baseline is missing, it was never assembled (no provenance entry), a
+    provenance source no longer resolves against the CURRENT descriptions (a header
+    removed/renamed), **the plan re-partitioned its assigned source set**, or **a
+    source module's committed description blob moved** (a same-header body/evidence
+    correction). The last two close the canonical reopen → re-describe → re-assemble
+    loop: name-resolution alone missed a corrected description that kept its headers
+    and a requirement re-assigned between two existing capabilities."""
+    digest_keys = {_key(e.part, e.module, e.requirement) for e in digest}
+    previous_by_capability: dict[str, list[ProvenanceEntry]] = {}
+    if previous is not None:
+        for entry in previous.entries:
+            previous_by_capability.setdefault(entry.capability, []).append(entry)
+    to_build: list[str] = []
+    for capability in sorted({a.capability for a in plan.assignments}):
+        if not (specs_dir / capability / "spec.md").is_file():
+            to_build.append(capability)
+            continue
+        entries = previous_by_capability.get(capability)
+        if not entries:
+            to_build.append(capability)
+            continue
+        sources = [source for entry in entries for source in entry.sources]
+        sources_resolve = all(
+            _key(source.part, source.module, source.requirement) in digest_keys
+            for source in sources
+        )
+        if not sources_resolve:
+            to_build.append(capability)
+            continue
+        # re-partition: the plan's current assigned set differs from what was built
+        current_assigned = {
+            _key(a.part, a.module, a.requirement)
+            for a in plan.assignments
+            if a.capability == capability
+        }
+        built_from = {_key(s.part, s.module, s.requirement) for s in sources}
+        if current_assigned != built_from:
+            to_build.append(capability)
+            continue
+        # content correction: a source module's committed description blob moved
+        if any(
+            source.blob != current_blobs.get(f"{source.part}/{source.module}") for source in sources
+        ):
+            to_build.append(capability)
+    return to_build

trueline/adoption/derive.py

@@ -0,0 +1,143 @@
+"""Derived adoption state (M4 §2.2/§3/§6.3) — pure over preloaded facts, with the
+paired `*_at` I/O shells (the `derive_state`/`derive_state_at` idiom).
+
+Nothing is stored: a describe marker COUNTS only while the map's current file set
+matches the recorded one (surgery), no mapped file changed since the read-SHA
+(staleness) and no constraint was recorded after it (reopen — at SHA equality the
+constraint counts as recorded-after, erring conservative). A validation record
+counts only while the description it validated is current. Late writers are inert
+by comparison — the M1 orphan-approval idiom at module grain.
+"""
+
+from pathlib import Path
+
+from trueline.adoption.records import (
+    read_describe_marker,
+    read_suite_run,
+    read_validation,
+)
+from trueline.adoption.scan import path_excluded
+from trueline.gitio import diff_names, is_ancestor
+from trueline.schemas import StrictModel
+from trueline.schemas.adoption import (
+    Constraint,
+    DescribeMarker,
+    ModuleEntry,
+    PartMap,
+    SuiteRun,
+    ValidationRecord,
+)
+
+
+class ModuleFacts(StrictModel):
+    """One module's preloaded derivation facts (the shell computes the git reads)."""
+
+    mapped_files: list[str]  # the CURRENT map's sorted file set (files + tests)
+    marker: DescribeMarker | None
+    validation: ValidationRecord | None
+    changed_since_read: list[str]  # diff(read_sha..HEAD) names ([] without a marker)
+    constraint_recorded_after: bool  # any module constraint not a PROPER ancestor of read-SHA
+
+
+def module_described(facts: ModuleFacts) -> bool:
+    """Describe-green (§2.2/§6.3): marker present, file set matches the current map
+    (surgery), no mapped file changed since the read (staleness), no constraint
+    recorded after the read (reopen)."""
+    marker = facts.marker
+    if marker is None:
+        return False
+    if sorted(marker.files) != sorted(facts.mapped_files):
+        return False  # map surgery invalidates by derivation — no file is touched
+    recorded = set(marker.files)
+    if any(changed in recorded for changed in facts.changed_since_read):
+        return False  # stale: the corpus always describes HEAD
+    return not facts.constraint_recorded_after
+
+
+def module_validated(facts: ModuleFacts) -> bool:
+    """Validated = described AND the validation record binds the CURRENT description
+    (same recorded describe-SHA)."""
+    if not module_described(facts):
+        return False
+    marker = facts.marker
+    validation = facts.validation
+    if marker is None or validation is None:
+        return False
+    return validation.describe_sha == marker.read_sha
+
+
+def suite_run_valid(
+    record: SuiteRun | None,
+    changed_since_run: list[str],
+    part_map: PartMap,
+    any_module_invalidated: bool,
+) -> bool:
+    """The §3 round predicate: the record is valid iff the SHA-diff touches nothing
+    of the part's mapped file set (assigned AND excluded — conservative; framework
+    paths are outside by construction) AND no module of the part is currently
+    stale/reopened/surgery-invalidated."""
+    if record is None or any_module_invalidated:
+        return False
+    assigned = {file for entry in part_map.modules.values() for file in entry.all_files()}
+    for changed in changed_since_run:
+        if changed in assigned or path_excluded(changed, part_map.exclusions):
+            return False
+    return True
+
+
+# ---- the I/O shells ----------------------------------------------------------------
+
+
+def module_constraints(constraints: list[Constraint], part: str, module: str) -> list[Constraint]:
+    return [c for c in constraints if c.part == part and c.module == module]
+
+
+def build_module_facts(
+    repo_root: Path,
+    home: Path,
+    part: str,
+    module: str,
+    entry: ModuleEntry,
+    constraints: list[Constraint],
+) -> ModuleFacts:
+    marker = read_describe_marker(home, part, module)
+    changed = diff_names(repo_root, marker.read_sha) if marker is not None else []
+    recorded_after = False
+    if marker is not None:
+        for constraint in module_constraints(constraints, part, module):
+            proper_ancestor = constraint.recorded_sha != marker.read_sha and is_ancestor(
+                repo_root, constraint.recorded_sha, marker.read_sha
+            )
+            if not proper_ancestor:
+                recorded_after = True  # SHA equality counts as recorded-after (conservative)
+                break
+    return ModuleFacts(
+        mapped_files=sorted(entry.all_files()),
+        marker=marker,
+        validation=read_validation(home, part, module),
+        changed_since_read=changed,
+        constraint_recorded_after=recorded_after,
+    )
+
+
+def part_has_invalidated_module(
+    repo_root: Path, home: Path, part: str, part_map: PartMap, constraints: list[Constraint]
+) -> bool:
+    """A module WITH a marker that is no longer describe-current (stale, reopened
+    or surgery-invalidated) — an un-described module never invalidates the suite."""
+    for module, entry in part_map.modules.items():
+        facts = build_module_facts(repo_root, home, part, module, entry, constraints)
+        if facts.marker is not None and not module_described(facts):
+            return True
+    return False
+
+
+def suite_run_valid_at(
+    repo_root: Path, home: Path, part: str, part_map: PartMap, constraints: list[Constraint]
+) -> bool:
+    record = read_suite_run(home, part)
+    if record is None:
+        return False
+    changed = diff_names(repo_root, record.sha)
+    invalidated = part_has_invalidated_module(repo_root, home, part, part_map, constraints)
+    return suite_run_valid(record, changed, part_map, invalidated)