docs(upstream): AI Hero course lanes 3–6 — decision records and consolidated provenance

[kyle-sexton]

No linked issue

Summary

Chain-close PR for the AI Hero course discussion lanes 3–6 (docs-only, per the maintainer's one-PR-at-chain-end decision): the compaction, plan-mode, and grilling-parity decision records, and the lane 6 harvest that consolidates every lane's rows into docs/upstream/aihero-course.md — now the authoritative provenance record for the course's six original lessons and nine steering lessons.

Fix

• docs/upstream/aihero-course.md: consolidated record — lanes 1–2 (ported from the contract branch, their only home), lanes 3–5 reconciled as dual parallel-run closures with per-lane provenance notes (verdicts convergent; the chain's audit-answers pass supersedes where they conflict; the union of filed items context-guard: document verified auto-compact-window interplay with zones #2995/planning: eval coverage for interview lock-mode STOP-on-gap and auto-detect auto-guard (aihero lane 4) #2997/planning: interview prototype detour + plan-mode-off guidance (aihero lane 5 audit findings) #2998 stands), lanes 7–9 carried from the steering record, the C1–C9 and lane-9 harness-claims verdict tables graduated (C8 re-verify caveat carried), 15 term-adoption verdicts, and the 15-lesson coverage index (the journey's completion gate).
• Interim records aihero-core-lanes.md and aihero-steering-lanes.md dissolved per their own headers; the live references in docs/conventions/invocation-mode/README.md and docs/specs/invocation-mode-doctrine-brief.md repointed.
• docs/conventions/invocation-mode/README.md: new "Cross-skill invocation phrasing" doctrine (routed lane 7 candidate, adopted adapted, named upstream provenance).
• SSOT bookkeeping in mattpocock-skills.md / mattpocock-skills-v12-map.md: diagnosing-bugs TRACK row annotated with the unreleased post-mortem drop; the row-35 "measured bands" overclaim corrected per audit amendment A1; the stale "Claude-only private marketplace" wording corrected (repo is public); cross-link to the new record.

Verification

• markdownlint-cli2 clean on every touched file (0 issues).
• Diff is docs-only (6 files), nothing under docs/topics/** (contract-slice prune gate untouched).
• No dangling references to the dissolved records: repo-wide grep shows only the consolidated doc's own provenance prose and one deliberate historical mention in the doctrine brief.
• Lane 6 ran interview-first per contract (register 11/11, gate clean) with a two-validator /planning:audit-answers pass that corrected three answers before the harvest locked.

Related

• Refs session-flow: aihero course lane 3: compaction doctrine (fork-beats-compaction, auto-compact stance, evidence-degraded marker) #2901, planning: aihero course lane 4: plan-mode asset-rush critique vs interview-first sequencing #2902, planning/interview: aihero course lane 5: grilling parity check #2903, docs(upstream): aihero course lane 6: shared vocabulary adoption and aihero-course provenance doc #2904 (the lane issues this chain closed — already closed, not re-closed here)
• Refs docs(upstream): AI Hero course journey roadmap — remaining lanes and filed follow-ons, in order #2994 (journey roadmap; carries the contract-branch supersession warning)
• Refs context-guard: document verified auto-compact-window interplay with zones #2995, planning: eval coverage for interview lock-mode STOP-on-gap and auto-detect auto-guard (aihero lane 4) #2997, planning: interview prototype detour + plan-mode-off guidance (aihero lane 5 audit findings) #2998, docs: materialize the project glossary for the lane-6 adopted terms (curate-language deferred creation) #3000 (filed follow-ons riding their own branches)

🤖 Generated with Claude Code

https://claude.ai/code/session_01QbfCrj3X9FfGL7VRZYmrn4

---

Generated by Claude Code

[claude]

Claude finished @kyle-sexton's task in 3m 16s —— View job

---

Code review complete

• Gather context (PR diff, CLAUDE.md, skill instructions)
• Review changed files for correctness/maintainability
• Post inline findings
• Final summary

This is a docs-only chain-close PR (6 files, no code). I read the full diff against the shipped origin/main (via gh pr diff 3001, since this checkout is shallow) and checked the new consolidated record's internal consistency and cross-file references.

Findings (1, posted inline):

• Lane 8's closing paragraph is missing its filed-issue citations (docs/upstream/aihero-course.md:308) — it says "enforcement filed, flip filed" with no issue numbers, unlike every sibling lane section (Lane 7 cites #2962/#2963 inline, Lane 9 cites #2987/#2989 inline). The numbers (#2968 enforcement, #2969 flip) are recoverable from the coverage index at the bottom of the file and from other docs, but this breaks the document's own stated completeness invariant that every claim maps to a filed work item "in the named lane section." Suggested fix posted as an inline comment.

Verified independently:

• No dangling markdown links to the deleted docs/upstream/aihero-steering-lanes.md — the two remaining mentions (in the new consolidated doc and in invocation-mode-doctrine-brief.md) are inline-code historical provenance references, not live links.
• aihero-shipping-course.md, docs/conventions/upstream-drift/README.md, docs/specs/write-for-agents-brief.md, and docs/specs/agent-doc-surfaces.md — all referenced paths that should exist on this branch — do exist.
• References to docs/topics/pocock-course-lanes/** (the separate, unmerged contract branch) correctly do not resolve here; the document itself flags this as expected pending-merge state, not a bug.
• Cross-checked every lane's "N rows / N house decisions" claim in the coverage index against the actual row counts in each lane's table (lanes 1–5) — all match.
• Filed-issue lists per lane in the coverage index match the issue numbers cited inline in each lane section, except the Lane 8 gap noted above.
• aihero-core-lanes.md (mentioned in the PR body as dissolved) was created and deleted entirely within this branch's own commit history, so it correctly doesn't appear in the final diff — not a discrepancy.

Nothing else rose to the "careful senior reviewer would block" bar — the rest is prose/provenance content I can't independently fact-check (issue numbers, upstream PR references, session claims), which is out of scope for this lane per the skill's high-signal bar.

Branch: claude/pocock-steering-course-00zkvd

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 78e06a4de9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

Claude has reviewed this PR 2 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[claude]

Claude finished @kyle-sexton's task in 2m 3s —— View job

---

Code review complete

• Gather context (PR diff at HEAD 9ac354b, CLAUDE.md, prior review findings)
• Check whether prior findings (lane 8 citations, phrasing-doctrine scope, re-fetch basis) were addressed
• Review changed files for new correctness/maintainability issues
• Post inline findings (none — see below)
• Final summary

This is the /review:code-review CI lane, re-run because the branch was pushed forward since the last review (78e06a4 → 9ac354b). I diffed those two commits directly and re-read the full PR diff against origin/main via gh pr diff 3001 (this checkout's origin/main ref has no merge-base with HEAD, so git diff origin/main...HEAD isn't usable here — gh pr diff is the reliable path).

Prior findings — all three addressed in 9ac354b:

1. My own prior finding (lane 8 missing inline issue citations) — fixed: docs/upstream/aihero-course.md:385-389 now cites #2968 (enforcement) and #2969 (flip) inline, matching sibling lanes 7 and 9.
2. Codex's "re-fetch basis" finding — addressed: a new paragraph, docs/upstream/aihero-course.md:57-65, explicitly documents that the lesson pastes are deliberately non-durable (maintainer-decided, account-gated course pages) and names the durable proxy (the pinned companion skills repo) for future re-fetches. This doesn't make the lesson text itself persist, but it converts an implicit gap into a stated, deliberate tradeoff with a recheck path — reasonable for a docs-only provenance record.
3. Codex's "normalize existing cross-skill calls" finding — addressed: docs/conventions/invocation-mode/README.md:75-86 now scopes the rule to new/edited skill text, explicitly acknowledges the existing fleet is mixed (citing the knowledge-pipeline handoffs as an example), and points at the filed normalization sweep #3002. I independently confirmed the cited example is real: plugins/knowledge/skills/map-corpus/SKILL.md:177 does hand off to /knowledge:docpage-digest in bare form, so the new scope note accurately reflects the codebase rather than just asserting it.

New review of this head: no new findings. The two touched sections (aihero-course.md's re-fetch-basis paragraph and lane 8 fleet re-grade paragraph; invocation-mode/README.md's scope note) are internally consistent with the rest of the document — issue numbers match the coverage index, the #3002 reference is consistent between the two files it appears in, and no new dangling references were introduced.

Nothing else rose to the "careful senior reviewer would block" bar. The remainder of the diff (prose/provenance content, issue numbers, upstream claims) is out of independent-verification scope for this lane, same as the prior pass.

Branch: claude/pocock-steering-course-00zkvd