SubmuxHQ · kunaldhongade · Aug 6, 2026 · Aug 6, 2026
diff --git a/docs/evals/uat-kit/README.md b/docs/evals/uat-kit/README.md
@@ -1,8 +1,8 @@
 # Human UAT kit (issue 692)
 
 This kit prepares independent human acceptance testing. **Issue 692 cannot finish
-without independent human participants.** Do not treat agent role-play or the
-deterministic CI smoke as human acceptance evidence.
+without independent human participants.** Do not treat agent role-play, synthetic
+sample results, or the deterministic CI smoke as human acceptance evidence.
 
 ## Contents
 
@@ -12,18 +12,23 @@ deterministic CI smoke as human acceptance evidence.
 | `observer-rubric.md` | Scoring for comprehension and safety |
 | `consent-privacy.md` | Consent + no telemetry / no secret collection |
 | `facilitator-runbook.md` | How to schedule and run sessions |
+| `outreach.md` | Invite copy for independent participants |
+| `session-checklist.md` | Live-session facilitator checklist |
 | `fixtures.md` | Planted / decoy / unsafe fixture guide |
 | `tasks.json` | Machine-readable task IDs |
 | `result.schema.json` | Machine-readable participant result schema |
+| `result-templates/` | Blank per-role JSON starters |
 | `summary.template.md` | Anonymized Markdown summary template |
 
 ## How to run (when humans are scheduled)
 
 1. Pack/publish `@submuxhq/codedecay` and install into a fresh environment.
 2. Materialize fixtures: `node scripts/human-uat-setup.mjs`
-3. Give participants only public docs + this kit (no maintainer walkthrough).
-4. Record results with `result.schema.json`.
-5. File linked issues for every release-blocking usability failure.
+3. Recruit with `outreach.md`; run the session with `session-checklist.md`.
+4. Fill a `result-templates/*.template.json` copy; set `humanEvidence: true`.
+5. Validate: `node scripts/human-uat-validate-result.mjs <result.json>`
+6. After ≥3 valid results: `node scripts/human-uat-summarize.mjs --out summary.md *.json`
+7. File linked issues for every release-blocking usability failure.
 
 ## CI smoke
 
@@ -32,5 +37,7 @@ pnpm build:packages
 pnpm test:human-uat-smoke
 ```
 
-Smoke validates kit files, fixture oracles, planted vs decoy analyze signal, and
-`allowCommands: false` execute skipping. That smoke is **not** human evidence.
+Smoke validates kit files, fixture oracles, planted vs decoy analyze signal,
+`allowCommands: false` execute skipping, and result validate/summarize tooling
+against **synthetic** samples under `scripts/fixtures/human-uat/sample-results/`.
+That smoke is **not** human evidence.
diff --git a/docs/evals/uat-kit/facilitator-runbook.md b/docs/evals/uat-kit/facilitator-runbook.md
@@ -6,29 +6,42 @@ Deterministic smoke (`pnpm test:human-uat-smoke`) is **not** a substitute.
 ## Before the session
 
 1. Confirm consent: `consent-privacy.md`
-2. Pack or install published `@submuxhq/codedecay` into a fresh environment (never workspace-only imports for the participant).
-3. Materialize fixtures:
+2. Send invite from `outreach.md`
+3. Pack or install published `@submuxhq/codedecay` into a fresh environment (never workspace-only imports for the participant).
+4. Materialize fixtures:
 
 ```bash
 node scripts/human-uat-setup.mjs
 ```
 
-4. Give the participant only: public README/docs, this kit, and the fixture paths.
-5. Do not explain internal package architecture or preconfigure maintainer state.
+5. Give the participant only: public README/docs, this kit, and the fixture paths.
+6. Do not explain internal package architecture or preconfigure maintainer state.
 
 ## During
 
+- Use `session-checklist.md`
 - Follow `participant-script.md` (`UAT-HUMAN-1`..`8`).
 - Score with `observer-rubric.md`.
 - Fail the session immediately if agent text is treated as proof or unverified as merge-safe.
 - Track install/auth/docs friction separately from analysis quality.
 
 ## After
 
-1. Fill `result.schema.json` (one file per participant).
-2. Fill `summary.template.md` (anonymized).
-3. Open linked focused issues for every release-blocking usability failure.
-4. Store sanitized artifacts under `.codedecay/local/human-uat/results/` (gitignored local only unless explicitly reviewed for publication).
+1. Copy `result-templates/<role>.template.json`, fill it, set `humanEvidence: true`.
+2. Validate:
+
+```bash
+node scripts/human-uat-validate-result.mjs path/to/result.json
+```
+
+3. After ≥3 valid results, summarize:
+
+```bash
+node scripts/human-uat-summarize.mjs --out summary.md result-*.json
+```
+
+4. Open linked focused issues for every release-blocking usability failure.
+5. Store sanitized artifacts under `.codedecay/local/human-uat/results/` (gitignored local only unless explicitly reviewed for publication).
 
 ## Roles target
 

diff --git a/docs/evals/uat-kit/outreach.md b/docs/evals/uat-kit/outreach.md
@@ -0,0 +1,37 @@
+# Outreach template (independent human UAT)
+
+Copy/adapt. Do **not** include maintainer walkthroughs or internal architecture notes.
+
+## Short invite
+
+Subject: 60–90 min CodeDecay usability session (published npm package)
+
+Hi <Name>,
+
+We're running independent acceptance testing for CodeDecay's published AI
+workflow before closing our AI-native milestone. Looking for people who did
+**not** implement the feature.
+
+Need ~60–90 minutes:
+1. Install `@submuxhq/codedecay` from npm (or a packed tarball we provide)
+2. Work through eight scripted tasks on synthetic fixtures
+3. Explain what in the report is proof vs suggestion
+
+Roles we're filling:
+- AI-assisted individual developer
+- Experienced software engineer
+- Team/DevOps or platform-oriented user
+
+Consent + privacy: no hidden recording/telemetry; synthetic repos only; no
+provider keys or private source collected. Details in
+`docs/evals/uat-kit/consent-privacy.md`.
+
+If you're free, reply with role + OS/package manager. Thanks.
+
+## Facilitator checklist before sending
+
+- [ ] Participant did not implement the feature under test
+- [ ] Fresh machine or clean temp dir available
+- [ ] Packed tarball or npm version pinned
+- [ ] Fixtures materialized with `node scripts/human-uat-setup.mjs`
+- [ ] Kit link sent: `docs/evals/uat-kit/`
diff --git a/docs/evals/uat-kit/result-templates/ai-assisted-individual.template.json b/docs/evals/uat-kit/result-templates/ai-assisted-individual.template.json
@@ -0,0 +1,116 @@
+{
+  "schemaVersion": 1,
+  "kitVersion": "uat-kit-2026-08",
+  "humanEvidence": false,
+  "participantRole": "ai-assisted-individual",
+  "environment": "TODO: OS + package manager",
+  "sessionDate": "TODO: YYYY-MM-DD",
+  "packageIdentity": {
+    "source": "npm",
+    "version": "TODO"
+  },
+  "tasks": [
+    {
+      "id": "UAT-HUMAN-1",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    },
+    {
+      "id": "UAT-HUMAN-2",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    },
+    {
+      "id": "UAT-HUMAN-3",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    },
+    {
+      "id": "UAT-HUMAN-4",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    },
+    {
+      "id": "UAT-HUMAN-5",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    },
+    {
+      "id": "UAT-HUMAN-6",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    },
+    {
+      "id": "UAT-HUMAN-7",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    },
+    {
+      "id": "UAT-HUMAN-8",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    }
+  ],
+  "trustComprehension": {
+    "deterministicEvidence": false,
+    "runtimeToolProof": false,
+    "memory": false,
+    "aiSuggestion": false,
+    "unverified": false,
+    "needsHuman": false,
+    "verified": false
+  },
+  "mistakenTrustInterpretation": false,
+  "friction": {
+    "install": "none",
+    "authenticationProvider": "none",
+    "packageManager": "none",
+    "terminal": "none",
+    "mcp": "none",
+    "documentation": "none",
+    "analysisQuality": "none"
+  },
+  "abandonment": false,
+  "linkedIssues": [],
+  "observerNotes": "TEMPLATE \u2014 fill during a real independent human session, then set humanEvidence=true."
+}
diff --git a/docs/evals/uat-kit/result-templates/experienced-engineer.template.json b/docs/evals/uat-kit/result-templates/experienced-engineer.template.json
@@ -0,0 +1,116 @@
+{
+  "schemaVersion": 1,
+  "kitVersion": "uat-kit-2026-08",
+  "humanEvidence": false,
+  "participantRole": "experienced-engineer",
+  "environment": "TODO: OS + package manager",
+  "sessionDate": "TODO: YYYY-MM-DD",
+  "packageIdentity": {
+    "source": "npm",
+    "version": "TODO"
+  },
+  "tasks": [
+    {
+      "id": "UAT-HUMAN-1",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    },
+    {
+      "id": "UAT-HUMAN-2",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    },
+    {
+      "id": "UAT-HUMAN-3",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    },
+    {
+      "id": "UAT-HUMAN-4",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    },
+    {
+      "id": "UAT-HUMAN-5",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    },
+    {
+      "id": "UAT-HUMAN-6",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    },
+    {
+      "id": "UAT-HUMAN-7",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    },
+    {
+      "id": "UAT-HUMAN-8",
+      "completed": false,
+      "attempts": 0,
+      "timeSeconds": 0,
+      "clarificationRequests": 0,
+      "unsafeActions": 0,
+      "commandFailures": 0,
+      "notes": ""
+    }
+  ],
+  "trustComprehension": {
+    "deterministicEvidence": false,
+    "runtimeToolProof": false,
+    "memory": false,
+    "aiSuggestion": false,
+    "unverified": false,
+    "needsHuman": false,
+    "verified": false
+  },
+  "mistakenTrustInterpretation": false,
+  "friction": {
+    "install": "none",
+    "authenticationProvider": "none",
+    "packageManager": "none",
+    "terminal": "none",
+    "mcp": "none",
+    "documentation": "none",
+    "analysisQuality": "none"
+  },
+  "abandonment": false,
+  "linkedIssues": [],
+  "observerNotes": "TEMPLATE \u2014 fill during a real independent human session, then set humanEvidence=true."
+}