Tier 1 + Tier 2 improvements: docs, CI, tests, output flexibility

[JTCneo]

Tier 1 + Tier 2 improvements: docs, CI, tests, output flexibility, failure handling

Motivation

deep-recon v1.0.0 is a strong skill but ships as a black box for forkers and a
black box for users when things go wrong. The README markets the workflow well
but doesn't help when an agent times out, a Synthesizer write fails, or a fork
produces generic-feeling output (the latter caused by a hardcoded reference to a
personal style guide in agents/synthesizer.md). This PR addresses those gaps
and adds the smallest amount of structure (CI, structural tests, CHANGELOG) the
repo can carry without losing its minimal character.

Changes

Tier 1 — Quick wins (docs, examples, CI hygiene)

• CHANGELOG.md — Keep-a-Changelog format, retroactive entry for v1.0.0
  derived from release notes, Unreleased section captures everything since the
  v1.0.0 tag.
• README — new Troubleshooting section (missing-document recovery,
  determinism expectations, partial-round failure, generic-voice fixes,
  metrics-after-compaction, cost guidance), new Documentation section
  pointing to CHANGELOG / TUNING / examples, and a Claude-Code-version-agnostic
  rewrite of the Architecture section (the prior "experimental in 4.6" framing
  is replaced with a forward-compatible explanation). New subsection clarifying
  that agents/*.md are prompt templates, not Claude Code agent definitions.
• docs/TUNING.md — guidance for forkers on customizing the Synthesizer's
  voice. Surfaces the hardcoded _resources/Kazys Varnelis – Personal Writing Style Guide.md reference at agents/synthesizer.md:16 and gives three
  remediation paths (replace path / remove reference / parameterize).
• examples/ — two illustrative recon outputs (Explore mode, Focus mode)
  plus a README explicitly marking them as illustrative, not best-of.
• SKILL.md — added argument-hint frontmatter field (verified against
  current Claude Code 4.7 spec — all other frontmatter fields current and
  correct).
• CI — .github/workflows/lint.yml runs markdownlint-cli2 plus a
  SKILL.md frontmatter check (must have name, description,
  allowed-tools) plus a negative check (agents/*.md must NOT have YAML
  frontmatter, since they are prompt templates).
• .markdownlint.json — config tuned to match the repo's existing style
  (MD040 disabled because the repo convention is plain ``` blocks).

Tier 2 — Meaningful upgrades

• CONTRIBUTING.md — PR norms: triage path by change type, prompt-edit
  conventions (atomic / justify / before-after), local testing, style
  expectations matching the repo's existing register. Voice changes are
  routed to forks rather than upstream PRs.

• Structural validator (tests/check_recon_structure.py,
  tests/run_smoke_tests.sh, tests/README.md) — Python validator (no deps)
  that asserts the output contract: required frontmatter fields, mode-specific
  section names, Territory cardinality (3–5 framings in Explore mode), Process
  Log + Central Question callouts, Obsidian flavoring (or the corresponding
  plain-mode invariants when --plain is set). Self-tests against examples/.
  Caught one real structural regression in focus-example.md (which has been
  fixed) on the first run.

• --plain flag — Synthesizer produces CommonMark-only output (no
  [[wikilinks]], no > [!callouts]) for non-Obsidian environments (Logseq,
  Foam, plain GitHub markdown). Default Obsidian flavor is unchanged.

• Per-agent model overrides — --explorer-model, --associator-model,
  --critic-model, --synthesizer-model flags. SKILL.md's "Agent Model
  Selection" section is now operational rather than purely descriptive: the
  Task dispatch passes model: and resolution order is documented.
  Cost-conscious guidance: --explorer-model haiku is the safe single
  substitution; never substitute the Synthesizer.

• --budget <tokens> flag — hard cap on total token spend. Orchestrator
  reads _metrics.md between rounds and aborts gracefully (writing the
  best-available draft) before exceeding the cap. Default behavior (no cap)
  is unchanged.

• Failure handling in the orchestrator — six failure modes are explicitly
  handled:

  • One agent fails or times out → proceed with N–1 reports, log in Process Log
  • All agents fail in a round → skip to final Synthesizer with prior rounds'
    material
  • Synthesizer's final write fails → retry once, then orchestrator writes
    captured text directly, or writes a stub pointing at per-agent reports
  • _metrics.md write fails → log to stderr, continue
  • Web search empty → Explorer handles in its own prompt; orchestrator does
    not auto-fallback to --vault-only
  • User kills mid-round → do not auto-resume on next invocation

  Principle: substance survives. Agent reports on disk are the ground truth.
  The README's troubleshooting section is updated to match this new behavior.

Migration notes

This PR is fully backwards-compatible. Default behavior is unchanged:

• No new required flags.
• No changes to the four agent prompt files except agents/synthesizer.md,
  which gets a new "Plain Mode" subsection that only fires when --plain is
  passed.
• The output template (templates/brainstorm-output.md) is unmodified.
• Existing recon/ directories are untouched.
• Existing _metrics.md files continue to be read and written in the same
  format.

For forkers: see docs/TUNING.md for the Synthesizer voice-tuning
guidance — this is the most important read after merge.

Risks

• Orchestrator prompt is now ~50% larger (especially Tier 2's failure
  handling at +37 lines). Token-spend per recon goes up slightly. This is
  recovered by the new --budget cap if needed.
• Untested behaviorally. Structural validator and lint config were verified;
  the skill itself has not been invoked end-to-end against these changes.
  Smoke-test recommended before merge: a default-mode recon, a --plain
  recon, a --budget test, and a model-override test.
• Per-agent model override depends on the Task tool's model: parameter
  being supported in Claude Code 4.7. Verified against the current skills doc
  during T1.4.
• The hardcoded _resources/Kazys Varnelis… reference is documented but not
  removed. This is intentional. Upstream should preserve the original
  author's voice tuning; forkers retune via docs/TUNING.md.

Rollback

Each commit is atomic and self-contained. To revert any single change:

git revert <sha>

To return the branch fully to upstream main:

git reset --hard origin/main

No external state is touched (no shared infrastructure, no published packages,
no production data).

Verification

End-to-end runs against a live vault would burn $5–$15 of Opus tokens per
pass. Instead, this PR ships a free verification harness that proves the
plumbing without the spend:

1. Validator-contract tests (tests/test_validator_contract.py) — feeds
   the structural validator 10 stubs (3 valid, 7 intentionally malformed:
   missing section, framings under/over cardinality, missing frontmatter
   field, plain-mode wikilinks, plain-mode callouts, Obsidian-mode without
   wikilinks). Catches regressions that would silently weaken the validator.
   Wired into tests/run_smoke_tests.sh. 10/10 assertions pass.
2. Static analysis — every smoke-test claim is traced to specific
   SKILL.md and agent-file lines (see table below).
3. Mock walk — the --budget abort condition is exercised against a
   synthetic _metrics.md: cumulative=73k, projected_next=78k, cap=80k →
   abort fires correctly per SKILL.md:162-175.

Static traces — what wires what

Claim	Wired at
Default Explore parse → dispatch → write-to-disk	SKILL.md:21,76-86,222; example output passes validator
--plain propagates to Synthesizer; plain-mode rules enforced	SKILL.md:41,258-264; agents/synthesizer.md:85-95; validator catches both wikilinks-in-plain and callouts-in-plain
--budget aborts gracefully	SKILL.md:49,162-175; mock walk above; Process Log message format at SKILL.md:172
--explorer-model haiku dispatches Haiku	SKILL.md:43-47,266-294; resolution order documented; Task call format specified as Task(model: <resolved>, ...)

Pre-merge checklist

• Markdownlint CI workflow passes. (local: markdownlint-cli2 "**/*.md" → 0 errors across all .md files. See commit 69386d2.)
• Structural validator self-tests pass. (local: bash tests/run_smoke_tests.sh — both example files OK.)
• Validator-contract tests pass. (local: python3 tests/test_validator_contract.py — 10/10. New in this PR.)
• SKILL.md frontmatter has all CI-required fields (name,
  description, allowed-tools).
• agents/*.md have no YAML frontmatter (CI negative check).
• Static analysis traces every flag to its handling code path
  (table above).
• --budget abort condition mock-walked and verified.

Deferred to maintainer review (live-run-only)

These three claims are statically wired but cannot be verified without
running the skill end-to-end against a real vault. They are deferred for
maintainer review:

• A real Explorer/Associator/Critic/Synthesizer dispatch returns
  per-agent reports on disk that the orchestrator then composes. Static
  trace says yes; runtime is the only proof.
• Claude Code's Task tool accepts model: <id> as documented in
  SKILL.md:286-294. The skill is built to this contract; a smoke
  recon with --explorer-model haiku is the one-shot way to confirm.
• Output prose actually matches the Synthesizer's voice rules — beyond
  the validator's structural pass.

Maintainer is welcome to run any subset of these against their own vault.
Suggested cheapest verification: one autonomous, vault-only, Haiku-on-all-
agents recon (~$0.50 in tokens) covers all three deferred items.

Commits (15)

• Add CHANGELOG.md (T1.3)
• Add Troubleshooting section, update Architecture for 4.7 (T1.1/T1.7/T1.8)
• Add docs/TUNING.md for forker voice customization (T1.6)
• Add examples/ directory with illustrative recon outputs (T1.2)
• Add argument-hint to SKILL.md frontmatter (T1.4)
• Add markdownlint CI workflow + config (T1.5)
• Add CONTRIBUTING.md (T2.6)
• Add structural validator for recon outputs (T2.4)
• Add --plain output flag for non-Obsidian forks (T2.3)
• Add per-agent model override (T2.5)
• Add token budget guard --budget (T2.2)
• Add failure handling to orchestrator (T2.1)
• Update CHANGELOG with Tier 1 + Tier 2 additions
• Tune markdownlint config to match repo voice; backtick placeholders
• Add validator contract tests (T2.4 follow-up)

🤖 Generated with Claude Code