Repo Bug Finder:package

Repo Bug Finder: Package

Purpose

Convert discovery readiness into a final handoff package. This subskill is packaging-only: it must not read new code facts, hunt for new Bugs, or promote scanner hits that were not triaged during discovery.

Boundary

Input:

• work/discovery-readiness.json
• work/discovery-readiness.md
• work/architecture-signals.json and .md when present
• triage/source-pack references produced during discovery
• user-approved scope and language

Output uses this standard package structure:

submit/
  README.md
  bug-audit-report.html
  findings/P1/
  findings/P2/
  findings/P3/
  findings/P4/
  indexes/
  knowledge/
  quality/
  standards/

Workflow

1. Read references/packaging-workflow.md, references/package-output.md, references/bug-schema.md, references/risk-taxonomy.md, and references/interactive-html-report.md.

2. Export discovery readiness into the package structure:

   python3 scripts/export_readiness_to_package.py <workspace> --project <name> --language zh
   

   --workspace <workspace> is accepted as an agent-friendly alias for the positional workspace.

3. Convert only clean package-ready records into Bug Markdown files. When readiness provides summary.clean_package_ready_record_ids, export only those records; otherwise fall back to eligible confirmed/probable records from older readiness files.

4. Assign continuous IDs starting at BUG-0001 with no gaps. Sort before assigning IDs: confidence high -> medium -> low, then priority P1 -> P2 -> P3 -> P4.

5. Put probable records in the final package only when the sole missing gate is trigger-path; label confidence: medium or low and state the trigger as a hypothesis.

6. Keep candidate, refuted, and merged records in candidate/quality coverage, not as final Bugs.

7. Generate indexes:

   python3 scripts/generate_bug_index.py <workspace>/submit
   python3 scripts/generate_candidate_index.py <workspace>/submit
   

   Package scripts that operate on submit/ also accept --submit-root <workspace>/submit or --workspace <workspace>.

8. Run pre-package validation before HTML generation when final HTML is expected:

   python3 scripts/validate_bug_package.py <workspace>/submit
   

   Do not pass --repo-root by default. In this workflow, work/discovery-readiness.json is the package source of truth. Use --repo-root only when the user explicitly asks for source-path existence validation against local checkouts.

9. Generate the HTML report:

   python3 scripts/generate_bug_report_html.py <workspace>/submit --language zh
   

10. Run final validation:

python3 scripts/validate_bug_package.py <workspace>/submit --require-html-report

Use --language en and English Bug headings only when the final deliverable is English.

⛔ BLOCKING GATES

• No new code reading in packaging.
• No new Bug facts in packaging.
• No architecture findings invented during packaging; architecture review must come from readiness records or work/architecture-signals.json.
• No dependence on untriaged pattern or scanner artifacts during packaging.
• No non-contiguous Bug IDs.
• No candidate-only records in submit/findings/.
• No records blocked by unknown/missing source packs or schema/package-blocking debt in submit/findings/ when readiness exposes clean package-ready IDs.
• No HTML report before indexes and validation receipts required by the generator are satisfied.
• No final handoff claim until validation passes.

Evidence Contract

Final package completion must produce:

• submit/findings/P*/BUG-*.md for promoted confirmed/probable records.
• submit/indexes/findings.generated.json and submit/indexes/candidates.generated.json.
• work/package-validation/prepackage-validation.passed.json before HTML generation.
• submit/bug-audit-report.html when a final report is requested.
• final validate_bug_package.py <workspace>/submit --require-html-report output when HTML is generated.

Output Contract

The package structure, Bug schema, index format, and HTML report style are part of this subskill's own contract. Keep them stable for downstream readers.