yam-flow 2.2.0 → 2.2.1

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to yam-flow are documented here.
 
+## v2.2.1 - 2026-07-09
+
+### Improved
+
+- Strengthened `$scout` into a wider research harness with source mapping, evidence ledger, opposition pass, and blocked-source fallback guidance.
+- Added `references/scout-wide-scan.md` for broad searches across tools, agent systems, protocols, harnesses, markets, and third-party ecosystems.
+- Clarified that `insane-search` should be used as blocked-source acquisition for high-signal sources, not as Scout's default search path.
+- Clarified that real subagent or parallel research lanes are explicit-only and should not turn ordinary scouting into `$mission`.
+
 ## v2.2.0 - 2026-07-07
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yam-flow",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Progressive proof-first agent flow: start fast, deepen deliberately, stay honest by design.",
   "type": "module",
   "author": "0kim0bos",

package/references/scout-wide-scan.md

@@ -0,0 +1,150 @@
+# Scout Wide Scan
+
+Use this reference when `$scout` needs broad search, powerful outside patterns, ecosystem comparison, agent/harness discovery, or source-heavy direction setting.
+
+## Activation
+
+Use wide scan when the user asks for:
+
+- Broad search or "find powerful patterns".
+- Tool, library, agent, harness, protocol, or market landscape comparison.
+- Third-party perspective before committing to a direction.
+- Evidence from multiple source classes.
+- Ideas worth reworking into yam style.
+
+Do not use wide scan for:
+
+- Stable direct answers.
+- Small implementation tasks.
+- Local code questions that a focused file read answers.
+- Heavy verification; use `$deep`.
+- Real subagent/team execution; use `$mission` unless the user explicitly asks for parallel agent work inside the current route and the environment supports it.
+
+## Scan Lanes
+
+1. Decision frame: name the decision, audience, constraints, and what would change the recommendation.
+2. Source map: decide which source classes are needed before reading deeply.
+3. Acquisition: gather enough sources; recover blocked high-signal sources only when needed.
+4. Triage: rank sources by authority, freshness, relevance, bias, and directness.
+5. Comparison: compare by fit, risk, cost, implementation effort, durability, and evidence quality.
+6. Opposition pass: name the strongest argument against the preferred direction.
+7. Synthesis: compress into a practical recommendation and yam-style rework ideas.
+8. Evidence ledger: record the important claims, evidence, confidence, and uncertainty.
+
+## Source Map
+
+Prefer a small balanced map over a large pile:
+
+- Official or primary source: docs, specs, vendor pages, source repos, standards.
+- Implementation evidence: source code, examples, package metadata, changelogs, local files.
+- Third-party analysis: credible writeups, benchmarks, incident reports, adoption notes.
+- Community evidence: issues, forum posts, social reports, user complaints; useful but lower trust.
+- Contrarian source: the best reason the attractive option may be wrong.
+- Local evidence: project constraints, existing route boundaries, installed tools, package scripts.
+
+Default focused scout remains 3-7 high-signal sources. Wide scan may use more, but stop once the decision is supported and marginal sources repeat what is already known.
+
+## Acquisition Ladder
+
+1. Use local project context packs and relevant local files first when the decision is project-specific.
+2. Use official or primary docs for current SDK/API/cloud-service behavior.
+3. Use ordinary web search or documentation search for accessible external sources.
+4. Use platform-specific public APIs or feeds when they are cleaner than rendered pages.
+5. Use blocked-source fallback only for high-signal sources that ordinary access cannot read.
+
+Blocked-source fallback:
+
+- Treat `insane-search` as a source acquisition subroutine.
+- Use it for blocked/WAF/platform-protected sources such as X, Reddit, YouTube, Naver, LinkedIn, Medium, Substack, or similar pages when they matter to the decision.
+- Preserve provenance: original URL, access path, trace or fallback note, and whether the content came from API, cache, feed, rendered HTML, or archive.
+- Do not use it for ordinary searches that normal web search can handle.
+- Do not treat authentication, paywall, private data, or rate-limit boundaries as something to force through.
+
+## Evidence Ledger
+
+Use a compact ledger for broad scans:
+
+```text
+Claim:
+Evidence:
+Source class:
+Confidence: high / medium / low
+Uncertainty:
+Decision impact:
+```
+
+Keep the ledger short. Include only claims that materially shape the recommendation.
+
+## Parallel Research
+
+Scout stays single-agent by default.
+
+Use real subagents or parallel agent lanes only when all are true:
+
+- The user explicitly asked for subagents, delegation, or parallel agent work.
+- The available environment provides real subagent tools.
+- The questions are independent and self-contained.
+- The results can be summarized without flooding the main context.
+
+Good lanes:
+
+- Official/docs lane.
+- Implementation/source lane.
+- Community/contrarian lane.
+- Security/risk lane.
+
+Bad lanes:
+
+- Multiple agents reading the same sources.
+- Delegating the immediate blocking question.
+- Role-playing subagents when no real subagent tool is available.
+- Turning a normal scout into `$mission`.
+
+## Opposition Pass
+
+Before the recommendation, ask:
+
+- What would make the best pick fail in this project?
+- Which source is least trustworthy or most stale?
+- What is the strongest cheaper/simpler alternative?
+- What security or operational risk is easy to miss?
+- What would we need to verify before implementation?
+
+Report the opposition pass briefly. It should sharpen the recommendation, not bury it.
+
+## Output
+
+Use the normal Scout shape, adding only the sections that help:
+
+- Best pick.
+- Objective judgment.
+- Subjective judgment.
+- Macro / realistic / future view.
+- Alternatives.
+- Risks.
+- Security lens.
+- Opposition pass.
+- Evidence ledger.
+- Ideas to rework into yam style.
+- Sources or local evidence.
+- Remaining tasks.
+
+## Source Clarity
+
+When outside systems shape the answer, preserve boundaries:
+
+- Fact: what the source says or what local files show.
+- Inference: what follows from comparing sources.
+- Opinion: taste, product instinct, or likely user perception.
+- Recommendation: the action Scout would take.
+
+Useful outside patterns to rework, not copy wholesale:
+
+- Agent Skills: progressive disclosure through `SKILL.md` plus optional references/scripts/assets.
+- Deep Research: multi-step search, backtracking, citations, and synthesis.
+- Coding-agent subagents: isolated read-only research lanes for context-heavy side tasks.
+- Agents SDK-style guardrails and tracing: lightweight checks and evidence records around runs.
+- Deep Agents-style harnesses: planning, context offloading, subagents, memory, and human checkpoints.
+- MCP/ACP-style protocols: standard tool/resource discovery and agent-client boundaries.
+
+Keep yam's bias: start with momentum, deepen deliberately, stay security-first, and avoid always-on orchestration.

package/references/scout.md

@@ -14,15 +14,20 @@ Use for:
 - Macro, realistic, and future-facing direction checks.
 - Security-centered direction checks.
 - Reference scans that find useful patterns to rework into yam style.
+- Wide scans across tools, agent systems, protocols, harnesses, markets, or third-party ecosystems.
 
 Default behavior:
 
 - Define the decision clearly.
 - Prefer official or primary sources.
 - Gather 3-7 high-signal references for focused scouting, or more when the user asks for a wide scan.
+- For wide scans, build a source map before deep reading: official/primary, implementation evidence, third-party analysis, community evidence, contrarian sources, and local evidence.
 - Use current docs proof only for modern SDK/API/cloud-service behavior where stale knowledge is plausible.
+- Use blocked-source fallback only when a high-signal source is blocked or platform-protected; treat `insane-search` as source acquisition, not as the default search path.
 - Summarize options and recommendation.
 - Separate fact, inference, opinion, and recommendation.
+- Use a compact evidence ledger for broad recommendations.
+- Run an opposition pass when false confidence would make the recommendation brittle.
 - Keep source boundaries clear: cite what was read and do not present reference-derived judgment as direct verification.
 - Put security before convenience: auth, payment, DB, secrets, permissions, deployment, supply chain, and public release get called out early.
 - Do not change code unless the user asks.
@@ -36,9 +41,13 @@ Judgment format:
 - Future view: second-order effects, durability, and what may age well or badly.
 - Security view: sensitive surfaces, safer defaults, failure modes, and what a non-specialist might miss.
 - Rework view: what ideas should be adapted into yam style and what should be rejected.
+- Evidence view: important claim, source class, confidence, uncertainty, and decision impact.
+- Opposition view: the strongest reason the preferred direction could be wrong.
 
 Escalate:
 
 - Use `question` for direct answers that do not need sources.
 - Use `deep` only when the user asks for heavy verification.
 - Use implementation routes only after the user asks to change code.
+
+For broad scan mechanics, use `references/scout-wide-scan.md`.

package/skills/scout/SKILL.md

@@ -16,6 +16,7 @@ Use for:
 - Objective and subjective evaluation together.
 - Macro, realistic, and future-facing judgment.
 - Broad reference scans when the user needs wider perspective.
+- Wide search across source classes, markets, tools, harnesses, agent patterns, or third-party ecosystems.
 - Security-centered direction checks before implementation.
 - Finding patterns worth reworking into yam style.
 
@@ -31,6 +32,11 @@ Use for:
 - Do not change code unless the user asks.
 - Return a practical recommendation.
 - Separate fact, inference, opinion, and recommendation.
+- Use an evidence ledger for wide scans: claim, source or local evidence, confidence, and uncertainty.
+- Run an opposition pass for broad recommendations: name the strongest reason the preferred direction may be wrong.
+- Use blocked-source acquisition only when a high-signal source is blocked, protected by WAF, or hosted on a platform that ordinary fetch cannot read.
+- Treat `insane-search` as a source acquisition subroutine, not as Scout's default search path.
+- Use real subagents or parallel agent lanes only when the user explicitly asks for delegation, subagents, or parallel agent work and the environment supports it.
 - Treat "objective" as evidence plus constraints, not certainty theater.
 - Treat "subjective" as named taste, product instinct, and likely user perception.
 - Security is the first lens: call out auth, payment, DB, secrets, permission, deployment, supply-chain, and public-release risks early.
@@ -46,13 +52,17 @@ Use for:
    - design/reference scan
    - product/technical direction memo
    - risk discovery
+   - wide scan
 3. Read `yam.project.md` first when project direction matters.
 4. Gather enough high-signal sources to support the decision; keep source quality higher than source volume.
-5. Compare options by fit, risk, cost, implementation effort, and durability.
-6. Identify security and trust implications before convenience or aesthetics.
-7. Give both objective and subjective judgment when useful.
-8. Recommend a direction and which ideas are worth reworking into yam style.
-9. State uncertainty and what would change the recommendation.
+5. For wide scans, build a source map before deep reading: official/primary, implementation evidence, third-party analysis, community reports, contrarian sources, and local evidence.
+6. Recover blocked high-signal sources through the blocked-source fallback only when ordinary access fails or is predictably blocked.
+7. Compare options by fit, risk, cost, implementation effort, durability, and evidence quality.
+8. Identify security and trust implications before convenience or aesthetics.
+9. Give both objective and subjective judgment when useful.
+10. Run an opposition pass when making a broad recommendation.
+11. Recommend a direction and which ideas are worth reworking into yam style.
+12. State uncertainty and what would change the recommendation.
 
 ## Output
 
@@ -65,6 +75,8 @@ Use concise sections:
 - Alternatives.
 - Risks.
 - Security lens.
+- Evidence ledger.
+- Opposition pass.
 - Ideas to rework into yam style.
 - Sources or local evidence.
 - Remaining tasks or useful next improvements.
@@ -72,6 +84,7 @@ Use concise sections:
 Use `references/token-economy.md`; default to 3-7 high-signal sources unless the user asks for a broad research scan.
 Use `references/current-docs.md` for current SDK/API/cloud-service questions.
 Use `references/context-reuse.md`; do not rescout known decisions unless they may be stale.
+Use `references/scout-wide-scan.md` when the user asks for broad search, powerful outside patterns, harness/agent comparisons, or ecosystem scans.
 Use `references/markdown-management.md` before creating or updating project packs.
 Use `references/final-report.md` to close with remaining tasks and fix-first items when useful.
 Use `references/token-budget-reporter.md` when a run needs measured budget feedback.

package/yam.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "yam",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "principles": [
     "Direction before execution.",
     "Start fast.",
@@ -36,8 +36,8 @@
     },
     {
       "id": "scout",
-      "stage": "v0.1",
-      "purpose": "Lightweight investigation and recommendation without code changes by default."
+      "stage": "v0.2",
+      "purpose": "Investigation, wide search, evidence-led source mapping, blocked-source fallback, opposition pass, and recommendation without code changes by default."
     },
     {
       "id": "deep",