blind-rebuild-verification

name	blind-rebuild-verification
description	Verify a reverse-engineered spec is self-sufficient by rebuilding the target from spec ONLY (never read the original). Use when the user hands you a spec directory + out directory and says "rebuild from spec only, do not read the original repo."

Blind-Rebuild Verification

You are given a spec dir (natural-language spec generated by a reverse-engineering tool like REgent regent-reverse) and an out dir. Your job is to rebuild the target package from spec only and prove the spec was sufficient.

This is a meta-test of the spec, not just an implementation task. The original repo is OFF-LIMITS — never ls, cat, grep, git log, or otherwise read it.

When this skill fires

• User says "blind-rebuild verification", "rebuild from spec only", or names the regent-build skill test.
• You're handed a <spec_dir>/AGENTS.md plus <spec_dir>/{README,architecture}.md, layout/, specs/, conventions/, inventory/.

Required reading order (literal)

1. <spec_dir>/AGENTS.md — its rebuild order is authoritative.
2. <spec_dir>/README.md + architecture.md — goals, constraints, building blocks.
3. <spec_dir>/layout/tree.txt + layout/src.map.md — file map + public APIs.
4. <spec_dir>/specs/*.spec.md — R-/S- requirements (MUST > SHOULD).
5. <spec_dir>/conventions/*.md — style, tooling, error conventions.
6. <spec_dir>/inventory/functional-checklist.md — grading key.

Rebuild loop

For each file in src.map.md:

1. Read its purpose, public API, side effects, imports from src.map.md.
2. Read the matching specs/*.spec.md R-num requirements that govern it.
3. Honor any constraints from conventions/ (import style, version, error format).
4. Write the minimum code that satisfies R-requirements and passes the checklist.

Do not copy verbatim. Reconstruct from natural-language spec.

Verification protocol

1. Per conventions/dev-env.md: build install command + test command.
2. Run the full test suite. Expect exit 0.
3. Run every - [ ] line of inventory/functional-checklist.md as an actual command/call. Capture output, exit codes.
4. For non-obvious cases, write a 5-line ad-hoc Python probe rather than guessing.

Final report (under 4 KB)

Structure:

• Clear spec sections — path:line cites where requirements were unambiguous.
• Vague/missing/invented sections — path:line for spec gaps. Be honest; this is the point.
• Checklist table — every - [ ] with PASS/FAIL + one-line reason + evidence.
• Inventions bullet-list — every decision not specified by the spec (e.g. "chose dict over if/elif in formats.py", "invented LICENSE body text because spec said only 'MIT stub'").
• Final verdict — PASS (spec sufficient) or FAIL (spec has gap), with the exact missing R- or S- number.

Pitfalls

• Do not read the original repo. Even verifying a "small detail" by reading original defeats the test. If spec is ambiguous, mark it vague in the report — don't peek.
• Empty/clean out-dir. Spec says "starts cleaned" — assume mkdir -p is yours.
• Use uv venv + uv pip install when venv needed. Never sudo. PEP 668 + python3 without pip → uv path.
• pip install -e .[test] will warn "no extra named test" if pyproject lacks a test extra. Not a real error; add pytest separately via uv pip install pytest or just pip install -e . for greeter-style packages without extras.
• Literal punctuation matters. For non-English locales (zh, ja), full-width ， 。 ！ etc. are usually required by spec — copy them byte-for-byte, do not auto-translate.
• error: prefix on stderr is literal in many CLI specs. argparse + print(f"error: {exc}", file=sys.stderr) is the canonical pattern.
• SHOULD vs MUST. SHOULD requirements are graded as PASS when honored; MUST failures → FAIL.
• __all__ matters. If spec says __init__.py declares __all__, declare it. from __future__ import annotations is required in Python ≥3.10 modules when the spec mentions it.
• Console script verification. After pip install -e ., run the binary directly (e.g. greeter Ada); don't trust that install succeeded without an actual invocation.
• Exit code discipline. Spec-defined codes (0 success, 2 domain error) must be tested explicitly with $?.
• Whitelist reuses, don't reinvent. If conventions/architecture-rules.md says formats.py is "function defs and a dict literal" — use a dict, even if an if/elif chain feels Pythonic. Match evidence.

Subagent Fallback (parent-agent rebuild)

When delegate_task fails — MiniMax 429 quota exhaustion, pool timeout at max_concurrent_children=1, or model unavailability — the parent agent MUST do the rebuild directly rather than retrying the subagent.

Triggers for fallback:

• Subagent returns 429 (Token Plan 用量上限) from MiniMax
• dispatch timeout after 600s with no output
• model resolves to a provider with exhausted quota

Parent-agent rebuild pattern:

• Python: write minimal stub modules + implementation via write_file using clean string literals (never read_file → write_file)
• Rust: cargo init --lib workspace (trait crate + impl crate), then write src/lib.rs
• Debug: fix one bug at a time, verify with python3 -c or #[test] probes
• Grade: comprehensive test walking every checklist item

Cross-Language Pitfalls

Rust + regex-automata

• NonMaxUsize has .get() not usize::from()
• HalfMatch has .offset() returning usize (no Dead/Quit variants in 0.4)
• search_captures returns () not Option in 0.4
• group_info().group_len() requires PatternID argument
• RegexBuilder is a temporary — bind to let binding before chaining

Common Implementation Bugs

• _exit_buffer calls _write_buffer directly, bypassing _check_buffer → quiet flag ignored
• Buffer saved AFTER flush in end_capture → returns empty string
• Sentinel NO_CHANGE values crash int() in update(width=...)
• Style.parse() doesn't raise on malformed input → get_style never falls back to default
• read_file output fed to write_file → line number prefixes injected into source files

What NOT to capture

• Specific license text you invented for one project — it's a per-spec invention, belongs in the report not as a durable rule.
• Per-implementation choices (dict vs if-elif) — report those in the inventions list, don't generalize.

Reference

See references/greeter-report.md for a worked example (small Python CLI package, 20/20 PASS, 4 minor inventions).