Update documentation with 5 changed files (#4803)

[rysweet]

Summary

Concise workflow-generated PR for documentation.

Issue

Closes #4803

Changed files

• docs/concepts/triage-dispatch.md
• mkdocs.yml
• prompt_assets/simard/overseer/problem_to_brief.md
• tests/ecosystem_dispatch_contract.rs
• tests/fixtures/ecosystem_dispatch/canonical.json

Diff stat

 docs/concepts/triage-dispatch.md                  | 239 +++++++++
 mkdocs.yml                                        |   1 +
 prompt_assets/simard/overseer/problem_to_brief.md |  18 +-
 tests/ecosystem_dispatch_contract.rs              | 599 ++++++++++++++++++++++
 tests/fixtures/ecosystem_dispatch/canonical.json  |  34 ++
 5 files changed, 886 insertions(+), 5 deletions(-)

Behavior

Implemented behavior through these branch commits:
0cce06e feat(overseer): add ecosystem triage-dispatch contract, doc, and fixture

Validation

ℹ NODE_OPTIONS=--max-old-space-size=32768 (saved preference). To change: /home/azureuser/.amplihack/config
I'll start by understanding what actually changed in this branch, then determine the right validation approach.

● Get branch, status, diff stat, recent commits (shell)
│ cd /home/azureuser/src/Simard-deploy-4049/worktrees/feat/issue-4803-nodeoptions-max-old-space-si
│ ze32768-saved-preferen && echo "=== BRANCH ===" && git branch --show-current && echo "=== STATUS
│ ===" && git --no-pager status && echo "=== DIFF STAT vs main ===" && git --no-pager diff --stat
│ main...HEAD 2>/dev/null | tail -40 && echo "=== RECENT COMMITS ===" && git --no-pager log
│ --oneline -10
└ 61 lines…

The diff vs main is huge (branch is far ahead). Let me focus on this branch's actual HEAD commit — that's the change to test.

Risk

No high-risk subsystem pattern detected from changed paths.

Checklist

• Branch has 1 commit(s) ahead of main
• Code review completed
• Philosophy check passed

---

This PR was created as a draft for review before merging.

---

Step 16b: Outside-In Testing Results

Tested the PR branch as a downstream consumer would, exercising the boundary the changed files define.

Detected toolchains

• Rust CLI — Cargo.toml at repo root (crate simard v0.38.0), cargo 1.95.0. Primary changed artifact is a Rust integration test (tests/ecosystem_dispatch_contract.rs) plus a checked-in JSON fixture, docs, mkdocs.yml, and a prompt asset.
• Node — package.json present (Playwright e2e only; unrelated to these changes).

Chosen strategy: Per the qa-team skill's repo-type detection, Rust CLI repos use cargo test as the outside-in boundary (no gadugi framework required). Ran the contract test suite plus an independent JSON-consumer check of the shipped fixture and a sibling asset-contract regression guard. Workspace is on /dev/sda (57G free); only root / is full, so the build was unaffected.

#	Scenario	Command	Result	Key output
1 (simple)	Dispatch contract suite (schema/ordering/validation, positive + negative cases)	cargo test --test ecosystem_dispatch_contract	✅ PASS	27 passed; 0 failed
2 (edge/integration)	Independent downstream JSON-consumer validation of tests/fixtures/ecosystem_dispatch/canonical.json (non-empty array; each element brief-or-escalation; well-formed owner/name; non-empty success_criteria; no credential-shaped secrets)	node -e '<inline validator>'	✅ PASS	3 elements (1 escalation, 2 briefs), well-formed, no secret shapes
3 (regression guard)	Sibling asset-contract suite, to confirm the doc/prompt edits didn't break the existing observe/brief contract	cargo test --test ecosystem_observe_assets	✅ PASS	7 passed; 0 failed

Fix count: 0 — all scenarios passed on the first run; no diagnose/fix/commit iterations were required.

[gitguardian]

⚠️ GitGuardian has uncovered 1 secret following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

🔎 Detected hardcoded secret in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
34584769	Triggered	GitHub Personal Access Token	0cce06e	tests/ecosystem_dispatch_contract.rs	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secret safely. Learn here the best practices.
3. Revoke and rotate this secret.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}

[rysweet]

Step 17b — Comprehensive Code Review

Reviewed all 5 changed files (886 insertions): the new triage-dispatch.md concept doc, its mkdocs.yml nav link, the reconciled problem_to_brief.md prompt asset, the 27-test ecosystem_dispatch_contract.rs contract suite, and the machine-checkable canonical.json fixture.

Verdict: ✅ Approve (non-blocking nits below)

This is an emit-only docs/contract change with no production code paths. The TDD contract suite is well-structured (positive + negative + edge coverage), the fixture is validated by the same in-test spec it documents, and the prompt/doc/schema are correctly reconciled (is_mechanical_sweep / sequence_group now documented as optional producer hints with defaults). Rule 7's secret test uses a genuine ghp_-shaped token literal, so it exercises find_secret correctly.

Checklist

• Code quality and standards — idiomatic Rust, clear helpers, no print!/println!
• Test coverage adequate — 27 tests; schema, discriminator, ordering intent, validation rules 1–4 & 7, fixture shape
• No TODOs, stubs, or swallowed exceptions — none present
• No unimplemented functions — none
• Logic correctness — validator branches (escalation vs brief) and discriminator are sound
• Edge case handling — empty array, blank fields, malformed owner/name, non-array criteria, embedded secret all covered

Non-blocking findings (low/medium)

M1 — Doc leaks a machine-specific absolute path. docs/concepts/triage-dispatch.md Configuration section hardcodes /home/azureuser/.amplihack/config and a personal NODE_OPTIONS value in a shipped concept page. Not portable for other readers. Suggest generalizing to ~/.amplihack/config and framing NODE_OPTIONS as an example rather than an environment fact.

L1 — Rule 5 not verified against the actual fixture. is_blast_radius_ordered is exercised only with hard-coded rank arrays ([0,1,2], etc.); the canonical fixture's real ordering is never rank-checked through it. Position pinning in canonical_fixture_matches_documented_p1_p3_p2_shape covers this indirectly, so the helper is somewhat decorative. Acceptable given rule 5 is source-relative, but worth noting.

L2 — is_well_formed_repo accepts ./.. segments. owner/.. or ./name pass because the char-set check allows all-dot segments, which GitHub disallows as repo names. Consider rejecting segments that are . or ...

L3 — AKIA needle is a bare 4-char substring. Could false-positive on ordinary prose containing "AKIA". Tightening to a shaped match (e.g. AKIA[0-9A-Z]{16}) would reduce false positives. Documented as a heuristic, so low priority.

L4 — Doc rule 1 vs. validator divergence. The validator (and empty_array_is_rejected) reject an empty array, but doc validation rule 1 only says "Top-level value is a JSON array" without stating non-empty. Minor: add "non-empty" to rule 1 for doc/impl parity.

None of these block merge. M1 is the most worth addressing before publishing the doc.

[rysweet]

Step 17c — Security Review (MANDATORY)

Verdict: APPROVE — no exploitable security vulnerabilities found. This is an emit-only docs/contract change with no production runtime code paths.

Checklist

• Security requirements met
• No new vulnerabilities introduced
• Sensitive data handling verified
• Authentication/authorization — N/A (no auth code in scope)
• Injection vectors reviewed

Findings by area

1. Synthetic token literal — NOT a vulnerability. tests/ecosystem_dispatch_contract.rs:520 contains a ghp_-shaped literal (terminal masks it) used to exercise the rule-7 detector. It is an obviously synthetic, low-entropy dummy (sequential body), not a live GitHub PAT, and cannot authenticate. Committing a clearly-fake shape-only literal to test a detector is standard practice. canonical.json contains no secrets.

2. find_secret heuristic (rule 7) — NOT exploitable. Lines 362–372 use plain str::contains over a fixed NEEDLES array (no regex → no ReDoS surface). It has false-negative gaps (case-sensitive, exact-spacing bearer, prefix-only), but it is a test-only assertion helper with no production callers — the live dispatch array is agent-authored and no shipping Rust consumes it. A weak test heuristic is not a runtime secret-scanning vulnerability.

3. Injection / path traversal — NOT present. is_well_formed_repo (line 347) permits ./.. segments, but the validated target_repo is never used as a filesystem path. All asset/repo_path callers pass only hardcoded module constants (DOC, MKDOCS, BRIEF_PROMPT, CANONICAL_FIXTURE); no JSON/user-derived string reaches PathBuf::join, fs::read, or any shell (verified across call sites lines 89–560). No path traversal, no command injection.

4. Prompt asset (problem_to_brief.md) — NOT a vulnerability. The diff only relaxes is_mechanical_sweep/sequence_group from required to optional-with-defaults and reorders an example. No untrusted data interpolated into instructions; no instruction-smuggling / XPIA surface introduced.

5. Machine-specific path — informational, below reporting bar. docs/concepts/triage-dispatch.md:97 hardcodes /home/azureuser/.amplihack/config, leaking the build machine's username. Portability/hygiene nit (overlaps prior review M1), not exploitable — exposes no credential and grants no access. Suggest ~/.amplihack/config.

Conclusion: No security-blocking issues. The token literal is synthetic, the secret heuristic and repo validator are test-only with no production data flow, no user-controlled input reaches a filesystem/shell/injection sink, and the prompt changes add no injection surface.

[rysweet]

Step 17d — Philosophy Guardian Review

Scope: 5 files, +886 emit-only lines — new concept doc triage-dispatch.md, mkdocs.yml nav link, reconciled problem_to_brief.md prompt asset, 27-test ecosystem_dispatch_contract.rs, and canonical.json fixture. No production Rust/runtime code paths are added or changed.

Verdict: COMPLIANT — no blocking philosophy violations.

Philosophy compliance

• Ruthless simplicity achieved — Contract is a set of small, single-purpose predicate helpers (is_well_formed_repo, is_blast_radius_ordered, find_secret) validating a plain JSON dispatch array. No speculative abstraction, no future-proofing layers. The doc describes exactly the rules the test enforces.
• Bricks & studs pattern followed — Self-contained brick: doc + contract + fixture co-located by concern. The "stud" is the dispatch-array shape (rules 1–7) shared between the doc (spec) and the test (enforcement); the fixture is the canonical example connecting them. Regeneratable from the doc spec.
• Zero-BS implementation — No stubs, TODOs, dead code, or unimplemented functions. Every helper is exercised by positive, negative, and edge tests (27 passing). No faked APIs or mock services outside the test's own fixtures. No swallowed exceptions — failures assert loudly.
• No over-engineering — Heuristic secret check is deliberately scoped to credential-shaped needles (ghp_, AKIA, PEM, bearer); rule 7 wording was corrected in Step 11b to stop over-claiming PII enforcement, aligning the promise with the mechanism rather than adding machinery to back an over-claim. This is the correct simplicity trade-off.
• Clean module boundaries — Doc (spec) ↔ test (contract) ↔ fixture (example) have a clear, stable contract surface. The doc's self-contained/source-relative summary matches the validator's actual scope after the Step 11b reconciliation.

Non-blocking observations (consistent with prior code review, no philosophy conflict)

• M1 — Doc embeds a machine-specific path (/home/azureuser/.amplihack/config) and personal NODE_OPTIONS. Minor "present-moment vs portability" nit; generalize when convenient. Not a philosophy violation but reduces regeneratability cleanliness.
• L3 — AKIA bare-substring needle could false-positive; acceptable given the heuristic's explicitly-scoped intent (no over-engineering to eliminate a low-risk edge).

Conclusion: The change embodies ruthless simplicity and zero-BS: a spec, its enforcing contract, and a canonical fixture — nothing more. Approved on philosophy grounds.

[rysweet]

Step 18b — Review Feedback Implemented

Commit d07a63405 applies the actionable Step 16 review findings. No blocking issues existed; these are portability/contract-fidelity improvements.

ID	Severity	Action	Change
M1	Medium	✅ Fixed	triage-dispatch.md — replaced machine-specific /home/azureuser/.amplihack/config with portable ~/.amplihack/config; generalized personal NODE_OPTIONS value to a <MB> placeholder. Removes username leak + non-portability.
L4	Low	✅ Fixed	Doc rule 1 + module-comment now state non-empty JSON array, matching the validator that already rejects empty arrays.
L2	Low	✅ Fixed	is_well_formed_repo now rejects bare ./.. segments (GitHub disallows them); added negative test cases (., .., ./name, owner/., owner/.., ../name).
L3	Low	⏸ Deferred (documented)	AKIA needle intentionally broad — inline comment explains a false positive is fail-safe (rejects array) whereas tightening risks missing a real key. No behavior change.
L1	Low	⏸ Deferred (backlog)	Rule 5 ordering already covered indirectly via position-pinning tests; fixture-driven assertion is nice-to-have.

Verification: ecosystem_dispatch_contract 27/27, docs_integrity 4/4; cargo fmt, clippy -D warnings (release), and pre-push gates all passed. PR remains MERGEABLE.

[rysweet]

Auto-closing this superseded auto-generated documentation PR: it is an older duplicate superseded by the canonical open auto-doc PR #4826. Enforcing the single-open auto-doc PR invariant (goal_hygiene).