docs(sdd): record install-research explores and the defect-6 verdict - #373
Merged
Conversation
…rdict Three parallel explore sessions converged on one root cause: the hub validates itself, and nobody ever runs the installer against a repository that is not the hub. Seven defects surfaced in 40 minutes of real use; zero in 369 CI PRs. - explore-consumer-install-defects: seven defects from a real Windows/APP install (kit-root asymmetry, cp-same-file, _template failing the gate, verify.sh hub misdetection x2, dangling guide pointers, project.md never materializing), plus the adversarial verdict on defect 6: the pointer-rewrite recommendation died (78 references in 23 files, 10-11 with no delivered target, 10 spec lines locking the text, KEEP-on-exists blocking existing installs); the decided fix is shipping the guide itself via a MANIFEST COPY entry with a template mirror inside sdd-kit/. - explore-agent-mediated-install: decisions D1-D7 (single acquisition path, whole kit in target, detected profile, guaranteed language question, imperative README, INSTALL.md direction, reinstall comparison), with the D1 consequence that two of the seven defects disappear by path deletion. - explore-python-onboarding-ux: Python states S1-S5, alert ordering, session-lock finding (flock absent on both target platforms), macOS portability layers (bash 3.2, BSD sed/realpath), the confirmed hypothesis that no pre-1.14.0 install could complete on macOS, and the retraction of the sha256sum claim after the real Mac report. Exploration artifacts only - no kit code changes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.
Records three parallel explore sessions as durable research artifacts, so the 1.15.0 proposal session reads them from the repo instead of chat scrollback. Exploration only — no kit code changes.
Root cause all three converge on: the hub validates itself. Seven defects in 40 minutes of real consumer use; zero in 369 CI PRs.
explore-consumer-install-defects— seven defects from a real Windows/APP install, plus the adversarial verdict on defect 6: the pointer-rewrite plan died under two clean-context agents (78 dangling references in 23 shipped files, 10–11 with no delivered target, 10 spec lines locking the pointer text, KEEP-on-exists blocking existing installs). Decided fix: ship the guide itself (template mirror insidesdd-kit/+ one MANIFEST COPY entry + parity gate + honest delta to the two "never receives it" spec sentences — which restores the founding design''s original intent from 2026-06-17).explore-agent-mediated-install— decisions D1–D7 for the single-acquisition-path future (1.16.0 scope).explore-python-onboarding-ux— Python detection states, alert ordering, the flock finding, macOS portability layers, and the confirmed hypothesis that no pre-1.14.0 install could ever complete on macOS (BSD realpath rejects the GNU flags), including one retraction after the real Mac report.🤖 Generated with Claude Code