Replace README with the Human-on-the-Loop overview

[mochan-tk]

Closes #116

Plan: #116 (comment)
Approved correction: #116 (comment)
Provenance clarification: #116 (comment)
Supersession note: #116 (comment)
Final outcome: #116 (comment)

Summary

This PR replaces the project README with the owner-supplied Human-on-the-Loop overview and commits its matching overview image. After official Rubber Duck identified an omitted repository support boundary, the owner approved one exact factual caveat: public repositories work on any GitHub plan, while private repositories require a paid plan because setup-sources.sh fails closed on GitHub Free. The README differs from the supplied draft only by that approved paragraph; provenance records both the original artifact and corrected derived artifact, and the changelog retains one Unreleased note.

Evidence

Criterion	Evidence (command / link)	Result
Corrected README is the approved artifact	shasum -a 256 README.md -> 72bea18c4fcbfc4cda925d9bbfa05390d2aac2eea00aa7da591afe58be32d6a6; wc -c < README.md -> 13569; source draft plus the exact approved three-line paragraph is byte-identical to README.md	pass
Overview PNG remains exact and valid	shasum -a 256 docs/images/agentic-development-kit-overview.png -> 95840911fbdc8765e9c6106efe66a88afad0959fb6cc36103aefc92b86a55ded; 1,490,062 bytes; file -> 1536x1024 8-bit RGB PNG	pass
Logo, CI badge, MIT badge, and overview image resolve and render	README references docs/logo.png, CI badge URL, MIT badge URL, and docs/images/agentic-development-kit-overview.png; check-md-links.sh passed; editor-canvas preview rendered the README/image	pass
Session hierarchy and terminology are correct	Project session → Epic orchestrator → Task supervisor → PR worker is present; case-insensitive program session search returned no matches	pass
Quick-start, Windows launcher, merge boundary, and GitHub-plan caveat match current behavior	Exact macOS/Linux `curl	bash, PowerShell bootstrap, pwsh .github/scripts/run.ps1 tuning-status.sh`, merged-default-branch onboarding boundary, and approved public/private plan caveat were cross-checked against current scripts and onboarding procedure
Human-on-the-Loop boundary is accurate	README retains repository sensors/actuators and GitHub evidence in scope while excluding immutable runtime roles, authenticated runtime events, heartbeats, budgets, circuit breakers, universal pause/resume/cancel, and a unified supervision console	pass
Ritual authenticity/freshness trigger is retained without authority overclaim	grep -F '#6: Ritual wall threat model' README.md; wording states that #6 tracks authenticity/freshness limits and makes no cryptographic-authority claim	pass
Provenance is complete and private-safe	INDEX.md records the detected/resolved conflict with no open question; source.md preserves original metadata/hash, approval URL, exact inserted paragraph, corrected size/hash, and editorial summary; no private local paths/chat data	pass
Changelog has one Unreleased note and unchanged history	git diff origin/main...HEAD -- SCAFFOLD-CHANGELOG.md shows only the single Task #116 Unreleased note; correction commits do not alter the changelog	pass
Diff is exactly the five owned files	git diff --name-only origin/main...HEAD -> .github/docs/context/readme-redesign/INDEX.md, .github/docs/context/readme-redesign/source.md, README.md, SCAFFOLD-CHANGELOG.md, docs/images/agentic-development-kit-overview.png	pass
Repository verification wall passes	New approved-hash check plus check-md-links.sh, check-changelog-refs.sh, tests/run-tests.sh, and check-copilot-surface.sh passed; exact-head post-sync CI run 32174187815 is 5/5 green	pass
Official Rubber Duck	#117 (comment)	pass
Fresh custom reviewer	#117 (comment)	pass

Deviations

The README contains the one owner-approved factual correction recorded in the linked correction plan; every other README byte remains identical to the supplied draft, and the PNG is unchanged. The worker runtime did not expose the official rubber-duck agent, so the supervisor ran the official review against the unchanged exact head. No acceptance criterion or owned path was otherwise changed.

Follow-ups

None. PR #117 is ready for human review; the reviewer audit and Task outcome are not merge authority.

Checklist

• Plan and approved plan update were posted as Task-issue comments before their respective implementation commits and are linked above.
• Diff stays inside the issue's File ownership paths.
• Every command in the issue's Verification section was run with the owner-approved README hash; output is captured above.
• No test, lint rule, or CI check was deleted, skipped, or weakened.
• Final record-before-report outcome posted on the Task issue and linked above.
• All persistent artifacts in this PR are English-only.

[mochan-tk]

Reviewer audit: PASS

Exact head: b25e7abeff2c7f364ee300c250394ef0609dc166

A fresh independent custom reviewer and the built-in official Rubber Duck both passed this unchanged head. No README or source correction is required.

Gate	Independent evidence	Result
Task/plan linkage	Closes #116; immutable plan comment 5332214409; claim → plan → dispatch ordering verified	pass
README source identity	SHA-256 5c4c2da300ae32d41d4e827bd819b69209571a23c53468817009941861a1e2f5 (13,401 bytes)	pass
Overview image identity	SHA-256 95840911fbdc8765e9c6106efe66a88afad0959fb6cc36103aefc92b86a55ded; valid 1536×1024 RGB PNG (1,490,062 bytes)	pass
Ownership	Exactly the five Task-owned paths; one clean task commit; no workflow/test/check weakening	pass
README consistency	Image/logo/badges, Project hierarchy, Quick Start commands, merged-main onboarding boundary, HOTL boundary, known limitations, and #6 framing checked against current repository behavior	pass
Provenance/changelog	Required provenance schema and method distinction present; no local paths/private chat/PII; exactly one Unreleased changelog item; history untouched	pass
Deterministic wall	Link/changelog/surface checks and all 23 guard suites passed independently	pass
Final post-sync CI	run 32170454021, exact head, all five jobs green	pass
Official Rubber Duck	Built-in rubber-duck checked factual consistency, commands, scope/safety claims, paths, omissions, and current implementation; no high-confidence findings	pass

This is technical verification, not human acceptance or merge authorization. The PR remains REVIEW_REQUIRED with zero formal reviews; the next gate is one explicit human approve/change/hold decision.

[mochan-tk]

Reviewer audit: GAPS

Independent Task-contract audit of PR #117 against Task #116, exact head b25e7abeff2c7f364ee300c250394ef0609dc166. This is a fresh audit — the PR's own evidence table and the recorded blocked Outcome comment were re-verified independently, not taken at face value.

Recommended disposition: gaps — do not merge.

Linkage

• PR Replace README with the Human-on-the-Loop overview #117 body contains Closes #116; GitHub's closingIssuesReferences confirms the link. ✅
• Task issue Replace README with the Human-on-the-Loop overview #116 is OPEN with labels type:task, ai:ready, needs:human, exec:app. The needs:human label was applied 2026-08-18T18:30:54Z (Ambiguity-rule escalation) and remains applied with no subsequent activity — the durable record has not been updated with an owner decision since.

Evidence audit (criterion → verified/unverified/failed, with how)

#	Criterion	Status	How verified
1	README.md byte-identical to supplied draft, sha256 5c4c2da3...	verified	Cloned repo, checked out exact head, independently ran shasum -a 256 README.md -> 5c4c2da300ae32d41d4e827bd819b69209571a23c53468817009941861a1e2f5. Matches issue and PR claim.
2	docs/images/agentic-development-kit-overview.png valid 1536×1024, sha256 95840911...	verified	Independently ran shasum -a 256 (matches), file -> PNG image data, 1536 x 1024, 8-bit/color RGB, non-interlaced, wc -c -> 1490062 bytes (matches issue's stated size).
3	Logo/CI badge/MIT badge/overview image resolve from repo root	verified	Reproduced the grep -F evidence rows against the checked-out head; all four references present.
4	Project→Epic→Task→PR hierarchy retained, no Program session reintroduced	verified	grep -F 'Project session' present; grep -i 'program session' empty.
5	Quick-start commands + current-behavior accuracy	failed	README lines 200–212 ("Prerequisites") only point to "the official GitHub Copilot documentation" for requirements. Read .github/scripts/setup-sources.sh directly: lines 121–143 implement a hard fail-closed gate — gh api repos/$OWNER_REPO --jq .private, and if private on a plan that resolves to free, fail "private repository on the GitHub Free plan is unsupported". The README discloses none of this scaffold-specific constraint. This is exactly the gap the recorded official Rubber Duck review found against this same exact head, and it is unresolved.
6	Human-on-the-Loop in/out-of-scope boundary accurate	verified	Spot-checked README sections against issue's boundary description; consistent.
7	Ritual-wall trigger retained, no cryptographic-authority overclaim	verified	grep -F '#6: Ritual wall threat model' present.
8	Source/provenance collection under .github/docs/context/readme-redesign/	verified	Read INDEX.md and source.md directly at exact head: method: verbatim block with exact hashes/sizes/dimensions, method: ai-summary editorial-decision block, conflicts/open-questions section present and states none found, no local filesystem paths or private chat data.
9	One Unreleased changelog note; history unchanged	verified	git diff origin/main...HEAD -- SCAFFOLD-CHANGELOG.md shows exactly one added bullet under ### Unreleased; no other lines touched.
10	Diff is exactly the five owned files	verified	git diff --name-only origin/main...HEAD -> exactly .github/docs/context/readme-redesign/INDEX.md, .github/docs/context/readme-redesign/source.md, README.md, SCAFFOLD-CHANGELOG.md, docs/images/agentic-development-kit-overview.png. All fall inside the issue's four File-ownership bullets (the context path is a glob covering two files). No unrequested paths touched — no workflow, ruleset, script, or agent-definition edits.
11	Repository checks pass	verified (currently)	At exact head b25e7ab..., three CI workflow runs exist: 32170320452 (5/5 SUCCESS), 32170454021 (5/5 SUCCESS, the run the PR body cites), and 32171518713 (created 18:31:52, a later automatic run — scaffold-self-check was still in_progress at the moment of my first check and completed SUCCESS on re-check). Current gh pr checks 117 and statusCheckRollup show 15/15 entries SUCCESS across the three runs; reviewDecision is REVIEW_REQUIRED. No failing or currently-pending check remains.
12	Official Rubber Duck ran against this exact head and a durable record exists	verified (ran), but finding unresolved	Outcome comment confirms "Fresh official Rubber Duck review against exact head b25e7abeff2c7f364ee300c250394ef0609dc166" found the omission. I independently reproduced the underlying fact (item 5). No later issue/PR comment, label change, or review supersedes this; it is still the current record.

Deviation-honesty note (positive): the PR's own evidence table does not overclaim — it marks the quick-start/current-behavior row and the official-Rubber-Duck row as gap rather than pass, and the Deviations/Follow-ups sections correctly state the Task is blocked pending an owner decision and that no unauthorized source correction was made. This matches the Ambiguity rule and is the honest behavior the contract asks for.

Gaps (ordered by severity)

1. (Blocking) Unresolved owner decision on a factual omission. Official Rubber Duck (recorded at the linked Outcome comment, against this exact head) found the supplied README's Prerequisites section omits the scaffold-specific fail-closed constraint in .github/scripts/setup-sources.sh (private repository + GitHub Free plan → hard failure), pointing only to generic GitHub Copilot docs instead. I independently confirmed both the omission in the README and the fail-closed code path in the script. No comment, label change, or review since 2026-08-18T18:30:55Z resolves this; needs:human is still applied and no decision has been recorded on issue Replace README with the Human-on-the-Loop overview #116. Per the Task's own acceptance criterion Drop the "Use this template" adoption path; installer only #1 ("...unless the Task records and obtains approval for a factual correction before implementation"), Task completion cannot be certified without that record.
   • Smallest sufficient next action: the repository owner posts a decision comment on issue Replace README with the Human-on-the-Loop overview #116 choosing one of the two options the Outcome comment already lays out — (a) approve adding the private-repo + GitHub Free caveat and record a new expected README hash, then have the worker apply that one factual correction and re-verify hashes/CI; or (b) explicitly accept the omission as-is and record that acceptance. Either way, re-run the fresh hash/CI/Rubber-Duck verification after the decision and post an updated Outcome comment before merge.
2. (Informational) Formal review state. reviewDecision=REVIEW_REQUIRED, 0 PR reviews and 0 PR-level comments exist as of this audit. This is expected given the Task is still blocked, but merge should not proceed while both the owner decision and a formal review are absent.

Retro candidates

None — this is the first time this specific gap (scaffold-specific fail-closed prerequisite omitted from a README rewrite) has surfaced in review; no existing instructions/skill guidance needs amending yet.

---

Exact head audited: b25e7abeff2c7f364ee300c250394ef0609dc166
CI: 15/15 check-run entries SUCCESS across runs 32170320452, 32170454021, 32171518713 (all against this exact head; no failing/pending checks remain).
reviewDecision: REVIEW_REQUIRED — 0 formal PR reviews, 0 PR comments recorded.
Disposition: gaps. Not recommending approval or merge.

[mochan-tk]

Reviewer audit addendum: GAP

This addendum supersedes the PASS comment at #117 (comment).

A concurrent supervisor review was not visible when that PASS was posted. Ground-truth re-verification confirms its finding: onboarding invokes .github/scripts/setup-sources.sh, which fails closed for private repositories on GitHub Free, while the current main README explicitly discloses that support boundary and the proposed replacement does not.

The exact head remains b25e7abeff2c7f364ee300c250394ef0609dc166; hashes, ownership, rendering, and CI remain green. The sole blocker is the owner decision already recorded in the PR body and Task blocked outcome. Do not merge until the owner approves either a factual README caveat/new hash or explicit acceptance of the omission.

[mochan-tk]

Reviewer audit: PASS

Fresh, independent Task-contract audit of PR #117 against Task #116. The PR's own evidence table and the issue's blocked→approved→corrected ledger were re-verified against the repository, not taken at face value.

Exact head: 0a6537d54b9e250d361c109c25629f07eb27c93d (confirmed current PR head via gh pr view --json headRefOid and clone/checkout of pull/117/head).

CI state: 5/5 checks SUCCESS at this exact head, run 32174187815 (headSha independently confirmed = exact head): copilot-surface, quality, scaffold-self-check, task-ritual, windows-launcher. No check skipped/deleted/weakened vs. origin/main.

Closing linkage: verified — closingIssuesReferences confirms Closes #116.

Evidence audit

Criterion	Status	How verified
README.md corrected artifact: SHA-256 72bea18c4fcbfc4cda925d9bbfa05390d2aac2eea00aa7da591afe58be32d6a6, 13,569 bytes	verified	Cloned pull/117/head, shasum -a 256 README.md and wc -c at exact head match exactly.
Exact source-plus-approved-paragraph transformation	verified	git diff b25e7abeff2c7f364ee250d361c109c25629f07eb27c93d...HEAD -- README.md (first worker commit → final head) shows only the four-line paragraph insertion from comment 5332615735, byte-for-byte, at the exact approved insertion point (after "...for current requirements." / before ### 1. Install). Also independently confirmed the first worker commit's README.md = 5c4c2da3... / 13,401 bytes (the original supplied draft), so the whole chain source→correction is provably intact. Confirms the superseding paragraph/hash (5332615735, 5332632506) was applied, not the superseded rendering in 5332605736 (32cbf826...).
docs/images/agentic-development-kit-overview.png unchanged	verified	shasum -a 256 -> 95840911fbdc8765e9c6106efe66a88afad0959fb6cc36103aefc92b86a55ded; wc -c -> 1490062; file -> PNG image data, 1536 x 1024, 8-bit/color RGB, non-interlaced. All match issue and PR claims exactly.
Logo/CI badge/MIT badge/overview image resolve	verified	grep -F reproduced for all four references at exact head; no new/unrequested endpoints in the diff (only pre-existing GitHub/raw.githubusercontent/docs.github.com/img.shields.io/cli.github.com/gitforwindows.org links).
Project→Epic→Task→PR hierarchy, no Program session	verified	grep -F 'Project session' present; case-insensitive program session absent.
Quick-start commands / merged-main boundary / GitHub-plan caveat match current behavior	verified	Read .github/scripts/setup-sources.sh directly (lines ~121–143): gh api repos/$OWNER_REPO --jq .private, fails closed with "private repository on the GitHub Free plan is unsupported" for private+Free and for undetermined plan. The inserted README paragraph states this exact behavior accurately. Current origin/main README independently confirmed to already disclose this boundary (line 234), so the correction restores parity rather than inventing a new claim.
Human-on-the-Loop boundary accurate	verified	README sections cross-checked against issue's in/out-of-scope list; consistent.
#6 ritual-authenticity trigger, no authority overclaim	verified	grep -F '#6: Ritual wall threat model' present; wording makes no cryptographic-authority claim.
Provenance: INDEX.md conflict record, source.md approval URL/exact paragraph/new hash, no private data	verified	source.md records approval_url: .../issuecomment-5332593329 (the actual owner-decision comment, not the earlier plan-update draft), the exact inserted paragraph, and corrected size_bytes: 13569 / sha256: 72bea18c.... INDEX.md replaces the no-conflict statement with the detected/resolved conflict, no open question — matches clarification 5332620261. git diff scanned for /Users/, /home/, Desktop, Downloads, worktree paths — none found.
Exactly one Unreleased changelog entry, history unchanged	verified	git diff origin/main...HEAD -- SCAFFOLD-CHANGELOG.md shows one new ### Unreleased bullet only; no second entry was added during the correction (correctly, per instruction in 5332605736).
Exact five-file ownership	verified	git diff --name-only origin/main...HEAD -> exactly .github/docs/context/readme-redesign/INDEX.md, .github/docs/context/readme-redesign/source.md, README.md, SCAFFOLD-CHANGELOG.md, docs/images/agentic-development-kit-overview.png — all inside the issue's declared File ownership (the two context files fall under the declared .github/docs/context/readme-redesign/** glob).
No credentials / unrequested external endpoints / workflow-ruleset changes	verified	git diff --name-only contains no .github/workflows, ruleset, or CODEOWNERS paths; no secret/token/password/credential strings added.
Official Rubber Duck PASS recorded in current PR body	verified (as recorded)	PR body's evidence table states the supervisor ran official Rubber Duck against this exact head and records pass; consistent with the earlier real official-Rubber-Duck-driven findings in this same thread (the private-repo/Free-plan gap that produced this very correction). Note: unlike the two earlier reviewer-audit comments on this PR (tied to head b25e7ab...), this final pass is not backed by a separately linked artifact/comment for the corrected head — it is a prose assertion in the body. Not contradicted by anything found; not blocking, but noted for completeness.

Gaps

None blocking. One non-blocking observation (see table row above): the final "Official Rubber Duck" evidence-table cell for the corrected head is a prose claim with no separately linked run/comment, unlike the pattern used earlier in this same PR thread. Recommend, as a matter of ledger hygiene (not a Task defect), that in-loop Rubber Duck evidence rows link to a concrete artifact when one exists — this is advisory only and does not change the disposition.

The unchecked Final record-before-report outcome checklist box is correctly left pending: this reviewer audit is itself a prerequisite input to that outcome, not a gap.

Governance safety

No credentials, no new/unrequested external endpoints, no workflow/ruleset/CODEOWNERS edits, no private filesystem paths or chat data in the diff. Diff is confined to the issue's declared ownership.

Disposition

Recommended disposition: pass.

• reviewDecision: REVIEW_REQUIRED
• Formal PR reviews: 0

This is an independent technical audit only. It is not merge authority and not a formal approval — the branch ruleset still requires an explicit human approve/change/hold decision before merge.

[mochan-tk]

Official Rubber Duck: PASS

Exact head: 0a6537d54b9e250d361c109c25629f07eb27c93d

The corrected README passes the requested factual-consistency, command-accuracy, critical-safety-guidance, and current-repository-behavior critique. The approved three-line public/private GitHub-plan caveat exactly matches the final plan and accurately reflects setup-sources.sh; all other README bytes remain identical to the owner-supplied draft, and the PNG remains unchanged.

The review also confirmed the Project → Epic orchestrator → Task supervisor → PR worker hierarchy, macOS/Linux and PowerShell installers, Windows launcher, merged-default-branch onboarding boundary, Human-on-the-Loop in/out-of-scope boundary, Issue #6 authenticity/freshness wording, provenance synchronization, one changelog note, exact five-file ownership, and green corrected-head checks. No repository-content gap remains.

This is in-loop critique evidence, not formal approval or merge authority.

[mochan-tk]

Human decision: approve administrator merge.

Authorization is limited to exact head 0a6537d54b9e250d361c109c25629f07eb27c93d with final post-body-sync CI run https://github.com/mochan-tk/agentic-dev-kit-for-copilot/actions/runs/32174711807 green 5/5. Administrator merge is explicitly authorized despite REVIEW_REQUIRED. Any head, artifact, evidence, or PR-body change invalidates this approval and requires a new decision.