docs(installer): ./setup as primary entry + runtime-agnostic bridge setup (one-click-installer S4) - #451
Merged
Merged
Conversation
artyhoo
enabled auto-merge (squash)
June 10, 2026 18:17
artyhoo
added a commit
that referenced
this pull request
Jun 10, 2026
…non-fast-forward diagnosis (#455) Modes: every blob's tree entry hardcoded mode 100644, silently stripping the exec bit off executables and mispushing symlinks. Now the mode is resolved per path — git index (ls-files --stage) → HEAD (ls-tree) → filesystem bits fallback — so 100755 and 120000 survive; a symlink blob carries the link target string; gitlink/tree modes (160000/040000) are rejected loudly instead of being pushed as corrupt 100644 blobs. Ref edge: the branch-update PATCH {force:false} now diagnoses a 422 non-fast-forward explicitly — shows the moved remote tip and the new commit's actual parent, suggests re-run or a fresh --branch, and states it will NOT auto-force — instead of dying on a raw gh error. Found live while dogfooding this push: branch existence must key off gh's exit code, not stdout — on 404 `gh api --jq` prints the error body to stdout, so a non-empty-stdout check takes the PATCH path for absent branches (pinned in the test stub). Incidents (one-click-installer umbrella, 2026-06-10): the S4 pushes (#449-#451) required hand-editing the tree payload to preserve the repo-root `setup` script's 100755 mode, and the S5 push (#452) needed manual hand-holding of the force:false ref PATCH. Both adaptations are now parameterized and pinned by a paired-negative test (tests/dispatcher/harvest-via-api.test.sh — stubbed gh, no network), wired into audit-self.yml#principles-meta-tests. Prior-art: skipped — hardening + test for an existing helper, no new capability.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
README entry-point restructure + runtime-bridge-setup residual delta (one-click-installer S4-docs, plan Task 8, delta-only):
./setupis now the documented primary entry (one-click: framework + companions + bridge; flags--yes/--all/--dry-run+ positional stack, verified againstsetup:7-14).install.shstays documented as the advanced/direct framework-file-deploy path.setup.shreduced to a one-line legacy note (superseded by./setup; will be absorbed) per maintainer decision 2026-06-10. Companion section rewritten from the removedCOMPANIONS=…env flow to the manifest flow (setup.d/companions.manifest+setup.d/engine.sh: detect-first, consent per companion, no version pin); TaskMaster noted as withdrawn. All 4 staleinstall.sh:NNline-citations dropped with their stale claims (post-S1 install.sh has zero companion logic). "What gets installed automatically" table and manual-work paragraph re-anchored to the file-deploy reality (.dependency-cruiser.cjs+ package.json scripts are wiring steps, not auto-installs)../setupone-click path + the spec-§5 health-first framing —/health-keyed runtime-agnostic detection (docker OR native), run-mode diagnosis with matching bring-up instruction, re-probe-and-report-explicitly on re-run, and the script-side explicit no-UUID → ManualBackend warning. Elements already shipped by feat(setup): S2-bridge — guided-detect lib + auto-dispatch opt-in flip (one-click-installer) #445/feat(runtime-bridge): invert buildKickoffSpec default — library-layer opt-in (S2-bridge follow-up, kickoff §7) #446 (our-side writes para, transportconfig showguidance,requireAutoMarkerlibrary-layer note) kept untouched. Authoritative-for header intact.Verify-trace
npx markdownlint-cli2 README.md docs/runtime-bridge-setup.md→Summary: 0 error(s)(observed)grep -n 'install\.sh:[0-9]\|setup\.sh:[0-9]' README.md→ exit 1, zero hits (observed)git diff --stat→ onlyREADME.md+docs/runtime-bridge-setup.md, 43(+)/33(-) (observed)docs/runtime-bridge-setup.md:3-4, observed)tests verified locally, CI wiring lands in S5
Scope
Delta-only docs change.
setup.shitself untouched per maintainer decision 2026-06-10 (legacy wording in README only). No edits tosetup,install.sh,setup.d/*, spec, plan,.claude/rules/,packages/. B-delta was non-empty (see Backward-check coverage table) — the no-edit branch did not apply.Note (orchestrator): branch was recreated server-side via the Git Data API on top of staging HEAD
9c10c68(git SSH/HTTPS transport blocked by the known flaky tunnel; documented fallback). Local pre-push hooks did not run on push — compensated by the worker's local markdownlint runs above and by CI on this PR.§1.7 Forward-check applied
README claims checked against shipped reality:
./setupflags--yes/--all/--dry-run+ positionalts-server|react-nextfrom the arg-parse loop atsetup:7-14; preflight probes exactlybash git python3 curl(setup:17); companions loop + external-service routing atsetup:30-34; bridge[y/N]default-skip atsetup:42-44. install.sh post-S1 state:grep -n 'COMPANIONS\|Superpowers\|TaskMaster\|claude plugin' install.sh→ zero hits (no companion blocks); stack picker atinstall.sh:142-149backs "omit to get a stack picker"; printed wiring steps (npm install --save-devlist, "Add scripts to package.json (see INSTALL.md §3)", "npx husky init") atinstall.sh:420-447back the "deploys files; does not run npm install" claim;.dependency-cruiser.cjsnot copied perinstall.sh:389comment. Non-tty prompt default-N backed bysetup.d/engine.sh:28-31(read -r ans || ans=""→ case default "no"). Doc-authority: README goal section untouched (diff hunks none overlapREADME.md:31-68);docs/runtime-bridge-setup.md:3-4Authoritative-for header byte-identical.§1.7 Backward-check applied
Citation sweep — every pre-edit
install.sh:NN/setup.sh:NNcitation verified against current files, verdict per hit:install.sh:337-338(README old:132, "tty fallback") — STALE: those lines are now the Scripts section;COMPANIONSenv removed repo-wide → DROPPED with its claim; replaced by engine prompt-EOF→N behaviour (setup.d/engine.sh:28-31).install.sh:62-69(README old:136, "arg/env parse") — HALF-STALE: arg parse exists shifted atinstall.sh:59-68but the env half (COMPANIONS) no longer exists → DROPPED (whole citation line removed; stable path refs instead).install.sh:371(README old:136, "Superpowers install") — STALE: line 371 is now inside the eslint-rules section; Superpowers lives insetup.d/companions.manifest→ DROPPED.install.sh:411(README old:136, "TaskMaster install") — STALE: region is now stack-templates/Done summary;grep TaskMaster install.sh→ 0 hits → DROPPED.Post-sweep:
grep -n 'install\.sh:[0-9]\|setup\.sh:[0-9]' README.md→ exit 1 (zero remaining).Spec-§5 element-by-element coverage for
docs/runtime-bridge-setup.md(element → current-doc line, added-here vs pre-existing):/healthprimary signal, transport-agnostic (docker OR native)setup.d/bridge-guided.sh:3-17#445;setup-runtime-bridge.sh:58)bridge-guided.sh:11-29; v1 prints instruction + re-run, no [Y/n] auto bring-up — doc matches shipped)/health+ explicit reachable/not reportbridge-guided.sh:23-29,setup-runtime-bridge.sh:57-61)config show,transport:"cli")setup-runtime-bridge.sh:77-78)setup-runtime-bridge.sh:83-86)requireAutoMarkerlibrary-layer opt-in note