chore: delete executed plans, stop ignoring files that ship - #18
Merged
Merged
Conversation
Three findings from a pass over every tracked file. docs/superpowers/plans/ is gone: five files, 8,703 lines of work orders addressed to agents, carrying 305 checkboxes that are all still unticked in a repository where every one of those tasks shipped. One still names the branch it was meant to be done on. What was decided lives in docs/decisions/, what it means lives in docs/tour/, and what was built lives in the code. docs/superpowers/specs/ stays β design documents, one of them cited by the tour. The two inbound references now point at ADR-0021 and at specs/. .gitignore ignored four files that ship. package.json and pnpm-lock.yaml were unanchored, so they also matched common/package.json, common/docs/package.json, common/docs/pnpm-lock.yaml and common/packages-types/package.json β templates copied into every generated project. Nothing was broken, because git keeps tracking what it already tracks; the hazard is the next template added beside them, which `git add -A` would drop without a word. Anchored, with a test that fails on the old rule. Comments, in the trees the last branch did not reach. The worst was common/.github/workflows/, which ships into every client repository: two blocks copy-pasted verbatim into all five call sites, thirty duplicated lines in every generated project, now two lines each and still present in every file. services/ turned up a copy that had drifted β the loopback comment was in three of four dev fragments, and mysql publishes on loopback the same way β and a note in mysql's service.env about a rule every service obeys, which moved to lib/contract.sh.
ttncode
added a commit
that referenced
this pull request
Sep 13, 2026
* docs: design for the remaining immich parity gaps * docs: implementation plan for the immich parity gaps * docs: number the plan's tasks * feat: carry the files this toolbox already asks of its projects SECURITY.md and CODEOWNERS ship to every generated project and were missing here. A pull request template is enforced on this repository's own pull requests by a CI job and was shipped to nobody. .vscode recommends the tools mise.toml already pins, and tells an editor that the extensionless scaffold file is bash. The placeholder test asserted that no @you survived generation, which a hardcoded account passes. It now asserts CODEOWNERS names the account the run resolved. * refactor(ci): name every step instead of commenting it 63 steps across four workflows, none with a name. immich names 297 of its own and sits at 3.8% comments against our 17.5% β the difference is not that they explain less, it is where. A step's name appears in the GitHub log while the job runs; a comment above it appears only to someone reading the file. No comment was deleted. Every one that survives annotates a key that is not a step β a timeout and the measurement behind it, fetch-depth: 0 for a test that walks this repository's history, the zizmor path scope, the `edited` trigger, and the pull-request-body job name being load-bearing for branch protection. None of those is a fact a step's name could carry. * refactor: local -r, and comments down to their facts immich's install.sh is 107 lines with three comments because main() reads as prose and the function names narrate. Ours has that shape already and still carried a paragraph above each function. local -r for locals assigned once, which is function scope and unlike the file-level readonly this repository rejects β these libraries are re-sourced into child processes by design. What stays is the third-party landmines: jq rather than grep for an asset id, two endpoints for a private release, the trap baking its path and naming its signals, sed delimited on | because a base64 value contains /, and BASH_SOURCE[0]:-$0 because a curl-piped script has none. * refactor: cut adapter.env, dockerignore and prettierignore to their facts adapter.env ran to 53-76% comments, common/.dockerignore to 79%, where immich's equivalents carry none at all. What stays is the traps: the laravel starter kit's inert .github failing zizmor with exit 13, the sed wiring routes/health.php into bootstrap/app.php because Laravel auto-loads neither, the nest v11/v12 jest-vitest regression, and the generator env vars (SHELL_VERBOSITY, COMPOSER_PROCESS_TIMEOUT) with their reasons. Deleted: comments restating what the assignment beside them already says (ADAPTER_TIER citing ADR-0012, the /up note beside ADAPTER_READINESS_PATH) and boilerplate ("never belongs in an image"). tests/*.bats were audited against the same rule β delete a comment the test name already says, keep one that records why the test exists β and found already compliant: every comment explains a shipped defect, an ADR, or a measured behavior no test name conveys. None restated a name, so no test file changed. Co-authored-by: Claude <noreply@anthropic.com> * fix: restore four facts the comment-density cut dropped Final review on chore/immich-parity found one Important and three Minor findings where compression lost a fact with nowhere else to land in the shipped repo: .dockerignore's build-context scope, example.env's appended variables, project.sh's mise.root.toml substitution order, and adapter.env's Nest major-bump validation step. Folded each back in as a clause on the surviving comment. * chore: remove the executed parity plan A plan is a work order. The five left behind before this one claimed 305 undone tasks in a repository where all of it had shipped; PR #18 deleted 8,703 lines of them. The design stays in docs/superpowers/specs/, which is the record. --------- Co-authored-by: iam-truongtrungnghia <navico.ai@tpssoft.com> Co-authored-by: Claude <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
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 this changes
A pass over every tracked file β not only the shell, which the last branch
covered. Two of the three findings are deletions.
docs/superpowers/plans/is gone. Five files, 8,703 lines. They are workorders addressed to agents β each opens with
> **For agentic workers:** REQUIRED SUB-SKILL: β¦β and between them carry 305checkboxes that are all still
- [ ], in a repository where every one of thosetasks shipped months ago. One still says "Work on
feat/interactive-wizard,already cut from
mainatb23d6dc". What was decided lives indocs/decisions/(24 ADRs), what it means lives indocs/tour/, and what wasbuilt lives in the code.
docs/superpowers/specs/stays: those are designdocuments with no checkboxes, and
docs/tour/09-wizard.mdsends a reader toone. The two inbound references to the plans now point at ADR-0021 and at
specs/instead..gitignoreignored four files that ship.package.jsonandpnpm-lock.yamlwere unanchored, so they matchedcommon/package.json,common/docs/package.json,common/docs/pnpm-lock.yamlandcommon/packages-types/package.jsonβ templates copied into every generatedproject. Nothing was broken today, because git keeps tracking a file it already
tracks; the hazard is the next one. A new template added beside those four would
be dropped by
git add -Awithout a word, and the projects generated after itwould be missing a file. Anchored to
/package.jsonand/pnpm-lock.yaml;node_modules/andtmp/stay unanchored, since a stray can appear anywhere.git ls-files -i -c --exclude-standardis now empty.Comments, in the trees the last branch did not reach.
common/.github/workflows/*(5 files).github/workflows/adapters.yml.github/workflows/pull-request.ymladapters/laravel-inertia/mise.tomlservices/*The worst of it was in
common/.github/workflows/, which ships into everyclient repository: two comment blocks were copy-pasted verbatim into all five
call sites β thirty duplicated lines in every generated project. Each is now two
lines, still present in every file, because a client opening
security.ymlalone should not have to find the explanation in
build.yml.services/turned up a copy that had drifted: the three-line "loopback, not0.0.0.0" comment was in mongodb, postgres and redis but not mysql, which
publishes on loopback exactly the same way. All four now carry one identical
line. And
services/mysql/service.envcarried a five-line note about thedigest-per-service rule β a contract every service obeys, which is why the other
three had nothing. It moved to
lib/contract.sh, next toREQUIRED_SERVICE_VARS.How it was verified
mise run lintβ clean.mise run test-runnerβ both lanes under the runner's own environment.mise exec -- bats tests/provenance.bats.mise exec -- zizmor --min-severity medium .github/workflows/β no findings.yq.git ls-files -i -c --exclude-standardbefore and after, for the ignore rule.grep -rn "superpowers/plans"over the tree, for dangling references.tests/cli.batsgained a check thatgit ls-files -i -c --exclude-standardisempty; run against the old rule it fails and names all four files.
What the audit checked and found nothing to do about: no function is defined
and never called; no test fixture is unreferenced; no tracked file is empty; no
paragraph is repeated across README, CONTRIBUTING, the tour and the runbooks.
The files that
md5sumreports as identical are symlinks (120000) intests/fixtures/, or per-adapter copies that the adapter contract requires eachadapter to own.
Checklist
mise run lintpassesmise run test-runnerpasses