synthesize-complete-scaffold

name	synthesize_complete_scaffold
description	Complete missing scaffold artifacts with minimal changes while preserving target/build consistency.
compatibility	opencode
metadata	{"stage":"synthesize-complete-scaffold","owner":"tianheng"}

What this skill does

Repairs only missing or semantically invalid scaffold items without rewriting unrelated files.

When to use this skill

Use this skill when coordinator reports missing scaffold files after synthesize.

Required inputs

• current fuzz/ scaffold
• missing items list from coordinator
• fuzz/execution_plan.json (if present)
• fuzz/harness_index.json (if present)

Required outputs

• missing required files completed under fuzz/
• if harness source is missing, create at least one harness source file before doc/json-only fixes
• refreshed fuzz/harness_index.json mapping execution targets to real harness files

Workflow

1. Repair missing harness source first if absent.
2. Repair/complete required scaffold files only.
3. Repair semantic invalid states in repo_understanding.json.
4. Reconcile execution plan and harness index mappings.

Constraints

• Preserve existing harness/build assets unless minimal change is required.
• fuzz/repo_understanding.json must contain non-empty:
  • build_system, chosen_target_api, chosen_target_reason, fuzzer_entry_strategy, evidence
• chosen_target_api must not be harness file path-like.
• build_system.lower() != "unknown".
• evidence must be non-empty string array.
• If fuzz/build.py uses invalid parallel style ($(nproc)), repair to ["-j", str(os.cpu_count() or 1)].
• If native fuzzers are built under fuzz/out/, fuzz/build.py must also build real coverage replay siblings under fuzz/out/replay/ with -fprofile-instr-generate -fcoverage-mapping; do not use symlinks/copies of primary fuzzers as replay binaries.
• Coverage replay must link coverage-instrumented repository/library objects, not only an instrumented harness object; do not link replay binaries against non-instrumented static libraries when function/path coverage is expected.
• Coverage/replay CMake builds that use LLVM coverage flags must configure with clang/clang++, not /usr/bin/cc/GCC.
• Generated subprocess compile commands must start with the compiler executable (clang or clang++); sanitizer/coverage flags must not become cmd[0].
• Keep multi-target buildability when fuzz/execution_plan.json contains multiple targets.
• Use explicit path actions: Read and fix <path>[:line].

Command policy

• Allowed: read-only commands only.
• Forbidden: build/execute commands.

Acceptance checklist

• All required scaffold files exist after this step.
• If harness was missing before this step, harness exists after this step.
• fuzz/harness_index.json contains no missing execution-target mappings.
• repo_understanding.json is semantically valid.
• fuzz/out/replay/<fuzzer> exists for native fuzzers and is profile-instrumented for per-input replay.

Done contract

• Write the path string fuzz/out/ as the sole text of ./done (run echo 'fuzz/out/' > ./done; do not copy the file's contents).