Spec: Colleague Trust Gate Bundle

User Input

IP-107 outcome: colleague trust gate bundle covering internal wiki onboarding, golden repo adoption walkthrough, harness criteria checklist, validation story, failure model, operator runbooks, and support/feedback loop.

Trust gate wording must focus on explicit boundaries, proof, validation, failure handling, and support loops. Do not imply AI output is inherently reliable.

Initial Situation

The harness wiki contains foundations, prompt surfaces, skill packs, execution modes, validation/tools, and lifecycle flows. Trust and adoption requirements exist in the grill, but routed colleague-facing trust material is still compact. There is no explicit onboarding path, trust boundary page, validation story, failure model, criteria checklist, support loop page, or golden repo walkthrough artifact.

Issue

Colleagues cannot yet evaluate when to trust the harness, where human judgment remains mandatory, or how to inspect a concrete adoption example. That blocks internal adoption and also blocks later public landing narrative work from a reliable private source.

Solution

Create a private trust gate bundle in the harness wiki and docs/runbooks. The bundle must help a colleague inspect the harness before adopting it:

• what it does and does not do
• what automatic checks prove
• what human review still owns
• common failure modes
• acceptance criteria before trusting a repo adoption
• a golden walkthrough with setup/update evidence
• where to report friction and how support loops feed baseline/wiki/skill fixes

Child Coverage

Non-Goals

• Public marketing copy or apps/web landing narrative.
• Client-specific case study material.
• Claiming AI output is inherently reliable.
• Full backoffice UI.
• Replacing existing CLI mechanics runbook.

Acceptance Criteria

• A routed internal onboarding path explains what to trust, what not to trust, and the misuse boundaries.
• Validation story distinguishes automatic checks, human verification, and remaining judgment.
• Failure model documents stale prompts, broad/unchecked subagents, missing validation, bad docs, local tool drift, and blind trust.
• Criteria checklist defines what must be true before a harnessed repo is considered adoption-ready.
• Golden repo walkthrough shows realistic punks scaffold setup / punks update adoption evidence, generated-file categories, expected agent behavior, validation gates, and failure handling.
• Operator runbook bundle links to CLI scaffolding mechanics without duplicating every command detail.
• Support/feedback loop explains CLI report submission, GitHub follow-up, Linear planning boundary, and how accepted fixes flow into skills/docs/harness/baselines.
• meta.json, wiki index, wiki log, docs/README.md, and routed pages stay synchronized.

Constraints

• Private/internal audience.
• Do not expose raw internal methodology as public narrative.
• apps/wiki owns canonical source content.
• Raw/generated walkthrough evidence can live in root docs/ or apps/wiki/raw/ until polished.
• Use proof and boundaries, not reliability theater.

Technical Notes

• Existing source pages to extend: harness-operating-system, validation-and-tools, adopt-repository, baseline-update-feedback.
• Likely new routed section: /docs/harness/trust-and-adoption.
• Existing docs/runbooks/dp-cli-scaffolding.md should be linked as mechanics, not duplicated wholesale.

Validation Plan

• JSON validation for all changed meta.json.
• bun run check
• bun run check-types
• browser smoke for /docs/harness/trust-and-adoption and golden walkthrough route.
• Manual checklist in implementation notes verifying IP-135/IP-136 coverage.

Decision Log

Open Questions