Session Handoff [default]: Instruction Set Converged, Workflow Chain Adoption and README Next

[ptr727]

Next Steps, in Priority Order

1. Adopt the hub's reusable workflow chain. This is the hub rollout item "ESPHome-NonRoot (docker-prepare hook for the upstream pin)" in the hub's docs/reusable-workflows.md "Stage 4", plus the Stage 2 gates.
   • Delete the six hub-hosted task files: build-docker-task.yml, build-release-task.yml, check-upstream-version-task.yml, get-version-task.yml, publish-plan-task.yml, and validate-task.yml.
   • Replace them with caller stubs pinned to a hub release SHA, plus hooks:
     • docker-prepare, which reads upstream-version.json for the :<esphome> tag and the ESPHOME_VERSION / DEVICE_BUILDER_VERSION build args.
     • A validate hook carrying the firmware compile-test job.
     • resolve-upstream for the tracker.
   • Fold check-upstream-dependency.yml into the hub's check-upstream-version-task.yml with auto-merge: false, per the hub's spec/divergences.json note on that file.
   • Delete repo-config/ (disposition retire) and sweep its inbound references in WORKFLOW.md.
   • Add the devcontainers Dependabot ecosystem for both branches.
   • This also closes Re-carry AGENTS.md, WORKFLOW.md, and publish-plan-task.yml: the hub adopted both upstream proposals, with changes #168, whose publish-plan-task.yml convergence the deletion supersedes.
   • Done when python3 spec/audit.py --branch <feature-branch> ESPHome-NonRoot shows no hub-only:, interface: or dependabot: finding, and a real publish succeeds after promotion. The publish is the true test, since secrets:, permissions: and hook resolution only resolve in a real run.
2. Fix Compile Error: "Opus: 'patch' command not found" #279, the image missing a patch utility. ESP-IDF's micro-opus managed component shells out to patch, so a build using it fails in the image. Add the Debian patch package to the Dockerfile's runtime stage, and consider a compile-test fixture that pulls a managed component. Done when the reporter's configuration class compiles in a locally built image.
3. README structure PR. Bring README.md in line with the hub's spec/readme-structure.md:
   • Make the tagline link-free.
   • Add the Table of Contents, Build and Distribution, Questions or Issues and 3rd Party Tools sections.
   • Delete the retired byob.yarr.is last-build shield.
   • Rename commit-link to commits-link and docker-link to docker-hub-link, strip the suffix from license-link, and group the reference definitions.
   • Then set the About panel and the Docker Hub short description from the tagline, which today differ from it by a trailing period.
4. Promote develop to main once the above land, using merge-and-release with an explicit go-ahead. The first promotion meets an EOL-only conflict on upstream-version.json, because main's tracker still writes CRLF until promotion. Resolve it by taking develop's side.

External Blockers

• The stale DOCKER_HUB_PASSWORD secret in both the Actions and Dependabot stores is claimed by no mechanism, since the workflows read DOCKER_HUB_ACCESS_TOKEN. Deleting a secret is the maintainer's call. Ask, and meanwhile leave it alone.

Internal Dependencies

• Step 1 before step 4: promoting before the workflow adoption would ship the carried task copies to main, only to delete them in the next promotion.
• Step 3 is independent of step 1, but branch it from develop after step 1 merges rather than stacking it. A stacked child loses its coverage statement and reopens its diff when the parent squash-merges, per A stacked pull request's diff reopens after the parent squash-merges, and nothing documents it ProjectTemplate#1742.

State

• develop is at c383370, with Move the Repository to the Fleet LF Line-Ending Default #275 and Split AGENTS.md Onto the Fleet Router Model and Carry the Instruction Set #276 merged. main has neither, so no promotion or release has happened.
• Worktrees from this round, to remove once their branches are gone: resync/eol-lf and resync/instruction-set in ESPHome-NonRoot, and one detached hub worktree at hub main. Re-derive them with git worktree list.
• Repository configuration was applied with the hub's configure.sh apply. check reports Configuration matches.
• Audit on develop: 2026-09-26T13:21:36Z | hub 45669468 | branch override develop reports 11 findings, all in the classes named in the next steps.

Parked Decision Queue

0 issues carry decision in this repository.

What the Last Round Did

• Merged Move the Repository to the Fleet LF Line-Ending Default #275, which moved the repo to the fleet LF default and made the tracker and watcher write LF.
• Merged Split AGENTS.md Onto the Fleet Router Model and Carry the Instruction Set #276, which split AGENTS.md onto the router model. It added CLAUDE.md, GOVERNANCE.md, OPERATIONS.md, AUDIT.md, host-tools.json and the .github/skills tree, and re-vendored CODESTYLE.md and .github/copilot-instructions.md.
• Applied the fleet label set (12 labels were missing).
• Commented recurrence evidence on Promotion candidates and two interface gaps found resyncing NxWitness ProjectTemplate#1116 (mirror-to-develop and human-authored comments, both local here) and on A stacked pull request's diff reopens after the parent squash-merges, and nothing documents it ProjectTemplate#1742 (stacked-PR reconcile conflicts and lost coverage).

What Not to Repeat

• Do not stack a PR on a whole-tree mechanical parent. Split AGENTS.md Onto the Fleet Router Model and Carry the Instruction Set #276 was stacked on the EOL renormalization in Move the Repository to the Fleet LF Line-Ending Default #275. After Move the Repository to the Fleet LF Line-Ending Default #275 squash-merged, reconciling the child conflicted on every file both had touched, even though the parent's content was identical to develop. Taking the child's side was correct, but it took a merge commit, and the reconciled head then lost its Copilot coverage statement for two more rounds.
• Do not trust the old AGENTS.md "Devcontainer" claim that the devcontainer's extensions mirror the workspace recommendations. The lists differ, so the claim was dropped rather than carried.

New Learnings

• The stacked-PR costs are recorded on A stacked pull request's diff reopens after the parent squash-merges, and nothing documents it ProjectTemplate#1742.

[ptr727]

State update after this link was written: next step 4 (the promotion) is done, ahead of steps 1 to 3, at the maintainer's direction.

• Promote the Fleet Resync to Main #281 promoted develop to main as merge commit ec95072. The EOL-only conflict on upstream-version.json was resolved on a promote/develop-to-main branch by taking develop's side, and was verified content-identical.
• Name the Image's Real Build Inputs in AGENTS.md and WORKFLOW.md #282 landed on develop first. It answers a promotion-PR finding that AGENTS.md and WORKFLOW.md called the Dockerfile the only build input.
• The publish run the merge triggered (run 36248623351) ran its plan job and skipped publishing, as designed for a maintainer merge. No release was cut.
• The 11 CodeRabbit findings against hub-carried content are dispositioned on Promote the Fleet Resync to Main #281. The three new hub defects among them are Three Carried-Skill Defects Raised on a Downstream Promotion PR ProjectTemplate#1891.
• A new local defect was surfaced: this repo's publish-plan-task.yml no-ops a feature-ref dispatch, where D2.3 requires failing fast. It closes with next step 1, which retires that file in favor of the hub task.
• Audit on main: 2026-09-26T14:29:25Z | hub 45669468 reports 11 findings, the same classes this link's steps 1 to 3 name. main and develop hold the same content.

Parked decision queue: 0.