Skip to content

chore: delete executed plans, stop ignoring files that ship - #18

Merged
ttncode merged 1 commit into
mainfrom
refactor/comments-in-workflows-and-services
Sep 12, 2026
Merged

ttncode merged 1 commit into
mainfrom
refactor/comments-in-workflows-and-services

Conversation

@ttncode

@ttncode ttncode commented Sep 12, 2026

Copy link
Copy Markdown
Owner

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 work
orders addressed to agents β€” each opens with
> **For agentic workers:** REQUIRED SUB-SKILL: … β€” and between them carry 305
checkboxes that are all still - [ ], in a repository where every one of those
tasks shipped months ago. One still says "Work on feat/interactive-wizard,
already cut from main at b23d6dc"
. What was decided lives in
docs/decisions/ (24 ADRs), what it means lives in docs/tour/, and what was
built lives in the code. docs/superpowers/specs/ stays: those are design
documents with no checkboxes, and docs/tour/09-wizard.md sends a reader to
one. The two inbound references to the plans now point at ADR-0021 and at
specs/ instead.

.gitignore ignored four files that ship. package.json and
pnpm-lock.yaml were unanchored, so they 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 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 -A without a word, and the projects generated after it
would be missing a file. Anchored to /package.json and /pnpm-lock.yaml;
node_modules/ and tmp/ stay unanchored, since a stray can appear anywhere.
git ls-files -i -c --exclude-standard is now empty.

Comments, in the trees the last branch did not reach.

before after
common/.github/workflows/* (5 files) 43 28
.github/workflows/adapters.yml 32 21
.github/workflows/pull-request.yml 18 14
adapters/laravel-inertia/mise.toml 31 19
services/* 19 7

The worst of it was in common/.github/workflows/, which ships into every
client 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.yml
alone should not have to find the explanation in build.yml.

services/ turned up a copy that had drifted: the three-line "loopback, not
0.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.env carried a five-line note about the
digest-per-service rule β€” a contract every service obeys, which is why the other
three had nothing. It moved to lib/contract.sh, next to
REQUIRED_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.
  • Every YAML and TOML touched was re-parsed with yq.
  • git ls-files -i -c --exclude-standard before and after, for the ignore rule.
  • grep -rn "superpowers/plans" over the tree, for dangling references.
  • tests/cli.bats gained a check that git ls-files -i -c --exclude-standard is
    empty; 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 md5sum reports as identical are symlinks (120000) in
tests/fixtures/, or per-adapter copies that the adapter contract requires each
adapter to own.

Checklist

  • mise run lint passes
  • mise run test-runner passes
  • New behaviour has a test that fails without the change
  • Docs that describe changed behaviour were updated in the same commit
  • No unrelated changes

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
ttncode merged commit 277d8a8 into main Sep 12, 2026
19 checks passed
@ttncode
ttncode deleted the refactor/comments-in-workflows-and-services branch September 12, 2026 17:55
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant