Initial commit: pygenium as git submodule

tasks/02-recon.md

@@ -0,0 +1,46 @@
+# 02. Deterministic code reconnaissance module
+
+meta:
+  id: pygienium-02
+  feature: pygienium
+  priority: P1
+  depends_on: [pygienium-01]
+  tags: [infrastructure, no-model]
+
+objective:
+
+- Build `src/recon.ts`: a deterministic, no-model pass that walks the target repo and writes a compact markdown report (languages, manifests, file counts, dead-file candidates) so every check has stable ground truth.
+
+deliverables:
+
+- `src/recon.ts` exporting `runRecon(cwd)`, `runReconAsync(cwd, opts)`, `reconReportPath(cwd)`, `ReconResult`
+- Writes `pygienium/recon/report.md` under cwd
+- Detects: languages by extension, build manifests, total files/bytes, git head/branch, and a "candidate files" list (source files not under skip dirs) written to `pygienium/recon/candidates.jsonl` + summary
+- Soft caps (MAX_FILES, MAX_BYTES) and SIGINT-safe async walk mirroring piolium's recon
+
+steps:
+
+- Port piolium's `recon.ts` structure: MANIFEST_FILES, LANGUAGE_BY_EXT, SKIP_DIRS, safe git exec, walkAndTally + async variant with yieldToEventLoop
+- Adapt skip dirs to include `pygienium` (own output dir)
+- Add a `candidates.jsonl` emitter listing source files (by language) for the check runners to consume; cap entries to keep it bounded
+- Export `buildReconReport` for unit testing
+
+tests:
+
+- Unit: `buildReconReport` on a fake ReconResult produces expected markdown sections (Arrange a result, Act build, Assert headers present)
+- Integration: run recon against this repo; assert report.md + candidates.jsonl exist and counts > 0
+
+acceptance_criteria:
+
+- `runRecon(cwd)` returns a ReconResult and writes report.md + candidates.jsonl
+- A repo without `.git` does not throw (graceful degradation)
+- Very large trees are capped without wedging
+
+validation:
+
+- Inspect `pygienium/recon/report.md` and `pygienium/recon/candidates.jsonl` after a run
+
+notes:
+
+- Recon is Q0-equivalent: deterministic, runs in-process, no model calls
+- This is the foundation every check consumes for targeting