feat(recomposer): natural-description build plan generator (second delivery)

Adds a top-level `recomposer/` package that consumes a Decomposer YAML
document (never the raw bundle) and emits an ordered, dependency-aware,
evidence-grounded reconstruction plan as Markdown + YAML:

- model.py: BuildStep/BuildPlan with the canonical 12-phase Part III
  sequence (skeleton -> environment -> domain -> contracts -> core ->
  adapters -> delivery -> persistence -> config -> tests -> validation
  -> docs).
- plan.py: scheduler. Construction units are module parts; mutually
  dependent modules (SCCs of the decomposition's own dependency edges,
  not quality-gate parsing) merge into joint steps with a
  granularity-qualified cycle assumption. Phase relaxation guarantees a
  dependency is never scheduled after its dependent; the
  no-forward-references invariant is asserted at generation time.
- render.py / serialize.py: natural-language Markdown guide (clipped
  lists) + full machine-readable YAML, both carrying the evidence-basis
  disclaimer banner; every step lists goal, rationale, requires,
  creates, contracts, dependencies, validation, evidence, expected
  result, confidence, and assumptions-to-resolve. Evidence-free phases
  are reported as skipped with reasons.
- cli.py: `python -m recomposer <decomposition.yaml> [--plan] [--yaml]`.

Output is byte-deterministic for a given decomposition. 19 tests under
tests/recomposer/ (synthetic scheduler contracts + end-to-end against a
real bundle). Also makes the report's "Semantic domains" assertion in
tests/decomposer conditional on concept evidence, since bundles built
without the concept plugin legitimately have no domain parts.

AI-generated: Claude Fable 5 via Claude Code.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Pedro Anisio Silva

recomposer/README.md

@@ -0,0 +1,81 @@
+# Repository Recomposer
+
+[⬆ back to project root](../README.md)
+
+## Disclaimer
+
+This work is subject to the methodological caveats and commitments described in [@DISCLAIMER.md](../DISCLAIMER.md).
+> No statement or premise not backed by a real logical definition or verifiable reference should be taken for granted.
+
+## What it does
+
+Second delivery of the Decomposer/Recomposer system. Consumes a **Decomposer
+YAML document** — never the raw bundle or repository — and generates a
+**Natural Description Build Plan**: an ordered, dependency-aware,
+evidence-grounded sequence of natural-language construction steps that could
+recreate the system from scratch, executable by a human engineer or an AI
+coding agent.
+
+```bash
+# 1) produce a decomposition (first delivery)
+python -m decomposer _tmp/<bundle> --yaml decomposition.yaml
+
+# 2) recompose it into a build plan
+python -m recomposer decomposition.yaml --plan buildplan.md --yaml buildplan.yaml
+```
+
+With no output flags, `python -m recomposer <yaml>` prints a phase-by-phase
+summary.
+
+## How the plan is scheduled
+
+1. **Units.** Module/package parts are the unit of construction. Modules that
+   are mutually dependent in the decomposition's own dependency edges (SCCs of
+   `dependencies.outgoing`) merge into one **joint step** — the evidence says no
+   linear order exists among them. Cycle detection does *not* parse
+   quality-gate findings, whose names/formats are reporting policy; the
+   scheduler depends only on the data contract.
+2. **Nominal phases.** Each unit gets a canonical Part III phase from its
+   classification (domain→3, ports/shared-kernel→4, core/supporting→5,
+   adapter/infrastructure→6, test→10); fixed steps (skeleton, environment,
+   schemas, ops, validation, docs) take phases 1, 2, 3, 9, 11, 12.
+3. **Phase relaxation.** Dependency evidence overrides canon: a dependency is
+   never scheduled after its dependent (single pass in descending build-order
+   layer, correct because dependencies sit at strictly lower layers in the
+   SCC-condensed DAG).
+4. **Invariant.** Every `requires` reference points to an earlier step; this is
+   asserted at generation time (`ValueError` on violation), not assumed.
+
+Each step carries: goal, rationale, required previous steps, files/components
+to create, contracts to define, dependencies introduced, tests/validation
+required, evidence (part ids + coupling metrics), expected result, a confidence
+label (`certain`/`strong`/`probable`/`weak`/`unknown`), and explicit
+**assumptions to resolve** (Part IV). Phases with no evidence are reported as
+skipped with a reason — never silently.
+
+Output is **byte-deterministic** for a given decomposition document.
+
+## Epistemics (PALS's Law)
+
+File inventories, dependency edges, and build order are mechanically derived
+facts carried over from the Decomposer. Step goals, rationale, and
+responsibilities are interpretive and confidence-tagged. LLM-authored text
+appears only as evidence explicitly marked `LLM (unverified)`. Both emitted
+documents (Markdown and YAML) carry an evidence-basis disclaimer banner.
+
+## Layout
+
+| file | responsibility |
+|---|---|
+| `model.py` | `BuildStep` / `BuildPlan` dataclasses, canonical 12-phase table |
+| `plan.py` | scheduler: units, SCC merging, phase relaxation, ordering, requires |
+| `render.py` | natural-language Markdown build plan |
+| `serialize.py` | machine-readable YAML build plan (full file lists) |
+| `cli.py` / `__main__.py` | `python -m recomposer` |
+
+Tests: `tests/recomposer/` (synthetic scheduler tests + end-to-end contract
+tests against a real bundle decomposition).
+
+---
+*AI-generated (Claude Fable 5 via Claude Code); reviewed under the project's
+verification rules.*

recomposer/__init__.py

@@ -0,0 +1,31 @@
+"""Repository Recomposer — second delivery.
+
+Consumes a Decomposer YAML document (never the raw bundle or repository) and
+generates a **Natural Description Build Plan**: an ordered, dependency-aware,
+evidence-grounded sequence of natural-language construction steps that could
+recreate the system from scratch, executable by a human engineer or an AI
+coding agent.
+
+Public API:
+    recompose(doc: dict) -> BuildPlan
+    to_markdown(plan) -> str
+    to_yaml(plan) -> str
+"""
+from __future__ import annotations
+
+from .model import PHASES, BuildPlan, BuildStep
+from .plan import recompose
+from .render import to_markdown
+from .serialize import to_document, to_yaml
+
+__all__ = [
+    "recompose",
+    "to_markdown",
+    "to_yaml",
+    "to_document",
+    "BuildPlan",
+    "BuildStep",
+    "PHASES",
+]
+
+__version__ = "0.1.0"

recomposer/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m recomposer`` entry point."""
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

recomposer/cli.py

@@ -0,0 +1,75 @@
+"""Command-line interface for the Repository Recomposer.
+
+    python -m recomposer <decomposition.yaml> [--plan OUT.md] [--yaml OUT.yaml] [--stdout]
+
+Consumes a Decomposer YAML document — never the raw bundle — and emits the
+Natural Description Build Plan as Markdown and/or YAML. With no output flags it
+prints a short summary.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import yaml
+
+from .model import PHASE_TITLE
+from .plan import recompose
+from .render import to_markdown
+from .serialize import to_yaml
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m recomposer",
+        description="Generate an ordered natural-language reconstruction plan "
+                    "from a Decomposer YAML document.",
+    )
+    parser.add_argument("decomposition", type=Path,
+                        help="Path to a decomposition YAML produced by "
+                             "`python -m decomposer ... --yaml`.")
+    parser.add_argument("--plan", type=Path, default=None,
+                        help="Write the Markdown build plan to this path.")
+    parser.add_argument("--yaml", type=Path, default=None,
+                        help="Write the YAML build plan to this path.")
+    parser.add_argument("--stdout", action="store_true",
+                        help="Print the Markdown plan to stdout.")
+    args = parser.parse_args(argv)
+
+    if not args.decomposition.exists():
+        parser.error(f"decomposition file not found: {args.decomposition}")
+    doc = yaml.safe_load(args.decomposition.read_text())
+    if not isinstance(doc, dict) or "parts" not in doc:
+        parser.error(f"not a decomposition document (no `parts`): {args.decomposition}")
+
+    plan = recompose(doc)
+
+    wrote = False
+    if args.plan:
+        args.plan.write_text(to_markdown(plan))
+        print(f"wrote Markdown build plan -> {args.plan}", file=sys.stderr)
+        wrote = True
+    if args.yaml:
+        args.yaml.write_text(to_yaml(plan))
+        print(f"wrote YAML build plan     -> {args.yaml}", file=sys.stderr)
+        wrote = True
+    if args.stdout:
+        print(to_markdown(plan))
+        wrote = True
+
+    if not wrote:
+        phases = sorted({s.phase for s in plan.steps})
+        print(f"repository: {plan.repository.get('name')}")
+        print(f"steps:      {len(plan.steps)} across {len(phases)} phases")
+        for n in phases:
+            k = sum(1 for s in plan.steps if s.phase == n)
+            print(f"  phase {n:>2} ({PHASE_TITLE[n]}): {k} step(s)")
+        print(f"skipped phases: {len(plan.skipped_phases)}")
+        print(f"open assumptions: {len(plan.open_assumptions)}")
+        print("(pass --plan/--yaml/--stdout to emit full output)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

recomposer/model.py

@@ -0,0 +1,94 @@
+"""Recomposition data model — the Natural Description Build Plan.
+
+A :class:`BuildPlan` is an ordered sequence of :class:`BuildStep` records that,
+followed in order, reconstruct the system described by a Decomposer output.
+Every step is evidence-grounded (it cites the decomposition part ids and files
+it derives from) and confidence-tagged; steps resting on unresolved assumptions
+carry them explicitly (Part IV: "reconstruction steps that depend on unresolved
+assumptions" must be reported, never silently embedded).
+
+The Recomposer consumes ONLY the decomposition document — never the raw bundle
+or repository — so this model mirrors what that document can prove.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# Canonical construction phases (Part III). The scheduler may pull a step to an
+# earlier phase than its nominal one when dependency evidence forces it (e.g. a
+# cycle group spanning core and infrastructure must be built together); it never
+# pushes a step later than its dependents.
+PHASES: list[tuple[int, str, str]] = [
+    (1, "skeleton", "Establish project skeleton"),
+    (2, "environment", "Configure package/build/runtime environment"),
+    (3, "domain_data", "Define core domain/data model"),
+    (4, "contracts", "Define internal contracts/interfaces"),
+    (5, "core_logic", "Implement core logic"),
+    (6, "adapters_infrastructure", "Implement adapters/infrastructure"),
+    (7, "delivery_surfaces", "Implement APIs/CLIs/jobs/events"),
+    (8, "persistence", "Implement persistence and migrations"),
+    (9, "configuration_deployment", "Implement configuration and deployment"),
+    (10, "tests_fixtures", "Implement tests and fixtures"),
+    (11, "validation", "Validate full-system behavior"),
+    (12, "documentation", "Document usage and extension points"),
+]
+PHASE_TITLE: dict[int, str] = {n: title for n, _, title in PHASES}
+PHASE_KEY: dict[int, str] = {n: key for n, key, _ in PHASES}
+
+
+@dataclass
+class BuildStep:
+    number: int
+    phase: int                              # 1..12, index into PHASES
+    goal: str
+    rationale: str                          # construction intent: why now, why this shape
+    requires: list[int] = field(default_factory=list)       # earlier step numbers
+    creates: list[str] = field(default_factory=list)        # files/components to create
+    contracts: list[str] = field(default_factory=list)      # interfaces/symbols to define
+    dependencies_introduced: list[str] = field(default_factory=list)
+    tests_required: list[str] = field(default_factory=list)
+    evidence: list[str] = field(default_factory=list)       # part ids + signals
+    expected_result: str = ""
+    confidence: str = "probable"
+    assumptions: list[str] = field(default_factory=list)    # unresolved assumptions
+    parts: list[str] = field(default_factory=list)          # decomposition part ids realized
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "step": self.number,
+            "phase": self.phase,
+            "phase_title": PHASE_TITLE.get(self.phase, "?"),
+            "goal": self.goal,
+            "rationale": self.rationale,
+            "requires_steps": list(self.requires),
+            "creates": list(self.creates),
+            "contracts": list(self.contracts),
+            "dependencies_introduced": list(self.dependencies_introduced),
+            "tests_required": list(self.tests_required),
+            "evidence": list(self.evidence),
+            "expected_result": self.expected_result,
+            "confidence": self.confidence,
+            "assumptions": list(self.assumptions),
+            "parts": list(self.parts),
+        }
+
+
+@dataclass
+class BuildPlan:
+    repository: dict[str, Any]              # copied from the decomposition header
+    architecture_intent: dict[str, Any]     # style + hypotheses the rebuild should honor
+    steps: list[BuildStep] = field(default_factory=list)
+    skipped_phases: list[dict[str, str]] = field(default_factory=list)
+    open_assumptions: list[str] = field(default_factory=list)
+    provenance: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "repository": self.repository,
+            "architecture_intent": self.architecture_intent,
+            "steps": [s.to_dict() for s in self.steps],
+            "skipped_phases": list(self.skipped_phases),
+            "open_assumptions": list(self.open_assumptions),
+            "provenance": self.provenance,
+        }