From 17d5fe9f1a5b1325b5302ace8ba080b8906def40 Mon Sep 17 00:00:00 2001 From: "Sakamoto, Kazunori" Date: Fri, 7 Aug 2026 23:42:21 +0900 Subject: [PATCH 1/8] docs: prefer operational rules over code and document expected repository rules - Restructure AGENTS_EXTRA.md into a minimal, unambiguous rule set that prefers operational rules over accommodating code, and sync the wbfy-generated agent instruction files. - Add docs/expected-repository-rules.md summarizing the rules wbfy and wb expect of target repositories, linked from README. Co-authored-by: WillBooster (Claude Code) --- .cursor/rules/general.mdc | 9 +++--- AGENTS.md | 9 +++--- AGENTS_EXTRA.md | 9 +++--- CLAUDE.md | 9 +++--- GEMINI.md | 9 +++--- README.md | 4 +++ docs/expected-repository-rules.md | 53 +++++++++++++++++++++++++++++++ 7 files changed, 82 insertions(+), 20 deletions(-) create mode 100644 docs/expected-repository-rules.md diff --git a/.cursor/rules/general.mdc b/.cursor/rules/general.mdc index cc3df2050..65d5663bc 100644 --- a/.cursor/rules/general.mdc +++ b/.cursor/rules/general.mdc @@ -44,8 +44,9 @@ alwaysApply: true - Assume all environment variables are defined; if validation is needed, `assert` at startup to fail fast. - Assume local tools such as `git`, `gh`, and `ghq` are installed and authenticated. - Ensure compatibility only with macOS and Linux; do not include Windows-specific code. -- Use `project.env` instead of `process.env` on `wb` package. +- Use `project.env` instead of `process.env` in the `wb` package. - Always drop any Windows support. -- `wbfy` specializes in repositories of the WillBooster / WillBoosterLab organizations; support for other repositories is a best-effort extra. -- `wbfy` is primarily a re-configuration tool: its input is almost always what `wbfy` itself generated in a previous run. Design and implement for that input format only; do NOT generalize parsers or generators to handle arbitrary hand-written or third-party files. -- Files that deviate from `wbfy`-generated output are exceptional cases to be fixed manually in the target repository as a rule; do not add code to `wbfy` to accommodate them. +- `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. +- Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast or overwrite with canonical output. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/AGENTS.md b/AGENTS.md index b16128b11..a3a6a72b6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,8 +38,9 @@ - Assume all environment variables are defined; if validation is needed, `assert` at startup to fail fast. - Assume local tools such as `git`, `gh`, and `ghq` are installed and authenticated. - Ensure compatibility only with macOS and Linux; do not include Windows-specific code. -- Use `project.env` instead of `process.env` on `wb` package. +- Use `project.env` instead of `process.env` in the `wb` package. - Always drop any Windows support. -- `wbfy` specializes in repositories of the WillBooster / WillBoosterLab organizations; support for other repositories is a best-effort extra. -- `wbfy` is primarily a re-configuration tool: its input is almost always what `wbfy` itself generated in a previous run. Design and implement for that input format only; do NOT generalize parsers or generators to handle arbitrary hand-written or third-party files. -- Files that deviate from `wbfy`-generated output are exceptional cases to be fixed manually in the target repository as a rule; do not add code to `wbfy` to accommodate them. +- `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. +- Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast or overwrite with canonical output. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/AGENTS_EXTRA.md b/AGENTS_EXTRA.md index 141b45684..6b690b7df 100644 --- a/AGENTS_EXTRA.md +++ b/AGENTS_EXTRA.md @@ -1,5 +1,6 @@ -- Use `project.env` instead of `process.env` on `wb` package. +- Use `project.env` instead of `process.env` in the `wb` package. - Always drop any Windows support. -- `wbfy` specializes in repositories of the WillBooster / WillBoosterLab organizations; support for other repositories is a best-effort extra. -- `wbfy` is primarily a re-configuration tool: its input is almost always what `wbfy` itself generated in a previous run. Design and implement for that input format only; do NOT generalize parsers or generators to handle arbitrary hand-written or third-party files. -- Files that deviate from `wbfy`-generated output are exceptional cases to be fixed manually in the target repository as a rule; do not add code to `wbfy` to accommodate them. +- `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. +- Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast or overwrite with canonical output. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/CLAUDE.md b/CLAUDE.md index 05b53b902..fa9c69ac4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -38,8 +38,9 @@ - Assume all environment variables are defined; if validation is needed, `assert` at startup to fail fast. - Assume local tools such as `git`, `gh`, and `ghq` are installed and authenticated. - Ensure compatibility only with macOS and Linux; do not include Windows-specific code. -- Use `project.env` instead of `process.env` on `wb` package. +- Use `project.env` instead of `process.env` in the `wb` package. - Always drop any Windows support. -- `wbfy` specializes in repositories of the WillBooster / WillBoosterLab organizations; support for other repositories is a best-effort extra. -- `wbfy` is primarily a re-configuration tool: its input is almost always what `wbfy` itself generated in a previous run. Design and implement for that input format only; do NOT generalize parsers or generators to handle arbitrary hand-written or third-party files. -- Files that deviate from `wbfy`-generated output are exceptional cases to be fixed manually in the target repository as a rule; do not add code to `wbfy` to accommodate them. +- `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. +- Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast or overwrite with canonical output. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/GEMINI.md b/GEMINI.md index dbe87f36a..c5b86a4cc 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -38,8 +38,9 @@ - Assume all environment variables are defined; if validation is needed, `assert` at startup to fail fast. - Assume local tools such as `git`, `gh`, and `ghq` are installed and authenticated. - Ensure compatibility only with macOS and Linux; do not include Windows-specific code. -- Use `project.env` instead of `process.env` on `wb` package. +- Use `project.env` instead of `process.env` in the `wb` package. - Always drop any Windows support. -- `wbfy` specializes in repositories of the WillBooster / WillBoosterLab organizations; support for other repositories is a best-effort extra. -- `wbfy` is primarily a re-configuration tool: its input is almost always what `wbfy` itself generated in a previous run. Design and implement for that input format only; do NOT generalize parsers or generators to handle arbitrary hand-written or third-party files. -- Files that deviate from `wbfy`-generated output are exceptional cases to be fixed manually in the target repository as a rule; do not add code to `wbfy` to accommodate them. +- `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. +- Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast or overwrite with canonical output. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/README.md b/README.md index ffa481305..072bce3cc 100644 --- a/README.md +++ b/README.md @@ -5,3 +5,7 @@ [![wbfy](https://img.shields.io/badge/wbfy-12.5.5-1e90ff.svg)](https://github.com/WillBooster/shared/tree/main/packages/wbfy) :recycle: An npm package designed for reusing general code across multiple projects at WillBooster Inc. + +## Documents + +- [Rules that `wbfy` and `wb` expect of target repositories](docs/expected-repository-rules.md) diff --git a/docs/expected-repository-rules.md b/docs/expected-repository-rules.md new file mode 100644 index 000000000..b7b44f8b4 --- /dev/null +++ b/docs/expected-repository-rules.md @@ -0,0 +1,53 @@ +# Rules That `wbfy` and `wb` Expect of Target Repositories + +`wbfy` is a re-configuration tool: its input is almost always what `wbfy` itself generated in a previous run. +Both tools therefore support exactly one canonical format per file and one canonical repository layout. +A repository that deviates from these rules is fixed manually (or by re-running `wbfy`); the tools do not add code to accommodate deviations, and they may fail fast or overwrite deviating files with canonical output. + +## Repository preconditions + +- Bun at or above the pinned minimum version is installed; `wbfy` aborts otherwise. +- The target directory has a `package.json` (or another supported manifest such as `pyproject.toml`, `go.mod`, `pom.xml`, `pubspec.yaml`). +- Monorepos place workspaces under `packages/*` and/or the patterns declared in the root `package.json` `workspaces` array. +- Every managed file is a regular in-repository file: symlinks and paths resolving outside the repository are refused. +- Git dependency specifiers may point only at `WillBooster/*` or `WillBoosterLab/*`; anything else aborts the run. +- The wbfy badge in `README.md` records the applied `wbfy` version and is the idempotency marker; do not edit or remove it. +- Tool versions are pinned in `mise.toml`; environment variables and secrets live in `fnox.toml` (never `.env*` files); `bunfig.toml` uses Bun's isolated linker; `bun.lock` contains no proxy registry URLs. + +## Ownership markers: what a human may edit + +| File(s) | Ownership | +| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AGENTS_EXTRA.md` | The only human-edited agent-instruction file. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/general.mdc`, and `.gemini/styleguide.md` are fully generated from it and are overwritten on every run. | +| `.gitignore`, `.prettierignore`, `.dockerignore` | Human content goes only before `# Generated by wbfy` (head) and after the last `# Project-specific settings` (tail); everything between is regenerated. | +| `oxlint.config.ts`, `oxfmt.config.ts` | Only content outside `// wbfy:start ` / `// wbfy:end ` pairs survives; a file without markers is replaced wholesale. | +| Self-contained GitHub workflows | Owned by `wbfy` iff the first line is exactly `# Generated by wbfy.`; removing that line is the opt-out. Reusable-workflow callers are owned iff every job calls a `WillBooster/reusable-workflows` workflow. | +| `lefthook.yml`, `.lefthook/`, `bunfig.toml` (except raw `[test]` sections), `.editorconfig`, `.gitattributes` | Fully regenerated; manual edits are lost. | +| `package.json` scripts | `wbfy` recognizes only its own generated command shapes (e.g. `bun wb test`, `wb gen-code`, `mise run `); a wrapper must _start with_ the generated command followed by `&&`. Scripts containing shell metacharacters or `cd` are left untouched. | + +## File-format rules + +- `package.json` must be strict JSON and is always rewritten via `sort-package-json`. +- `tsconfig.json`, `.vscode/settings.json`, and `pyrightconfig.json` must be JSONC; `.releaserc.json` strict JSON; workflows YAML mappings; `renovate.jsonc` is the only supported Renovate config location. +- Unparseable input is skipped with a warning and never overwritten — except `mise.toml` and `fnox.toml`, whose parse or layout errors fail the run. +- `fnox.toml` layout is strict: an age provider named exactly `[providers.age]`, no `import`, no profile-specific providers, a root `fnox.toml` when nested ones exist, and the file must be git-tracked. Development defaults live in `[secrets]`; `test`/`staging`/`production` overrides live in `[profiles..secrets]`. + +## Project structure expected by `wb` + +- Source code lives in `src/`, scripts in `scripts/`, framework code in `app/`. +- Under `test/`, only `unit/`, `e2e/`, `debug/`, `helpers/`, and `fixtures/` may exist, and `*.test.*` / `*.spec.*` files only under the first three; violations fail `wb lint` and `wb test`. A package with its own `playwright.config.ts` must have `test/e2e/`. +- `package.json` scripts follow the `wbfy`-generated set (`typecheck`, `lint`, `test`, `test/ci`, `verify`, …); optional hooks such as `build`, `gen-code`, `deploy`, `deploy:staging`, `seed`, and `docker/build/prepare` are picked up by name. +- `WB_ENV` is one of `development` / `test` / `staging` / `production`; environment variables come from `fnox.toml` plus `mise env`. +- Docker apps have a `Dockerfile` whose container listens on port 8080 (the host port comes from `PORT`); dev servers default to port 3000 (8787 for plain Workers). +- Cloudflare Workers use a `wrangler.jsonc`/`wrangler.json` config; `wb deploy` targets Workers only, requires `WB_ENV` of `staging`/`production`, and reads Cloudflare credentials from `.env.cloudflare` (gitignored and untracked). `.dev.vars` and `worker-configuration.d.ts` are generated, never hand-written. +- Prisma schemas live at `prisma/schema.prisma`, `prisma/schema/`, or `db/schema.prisma`; i18n resources in `i18n/` with default locale `ja-JP`; a Chakra theme at `src/theme.ts`. +- Real Node.js must be on `PATH` (not a Bun shim) for Playwright, wrangler, and vinext. +- macOS and Linux only; Windows is unsupported. + +## GitHub-side conventions (WillBooster / WillBoosterLab repositories) + +- Squash-only merges with `PR_TITLE` messages, auto-merge enabled, and head-branch deletion on merge. +- A `Protect main` ruleset requires the `test / test` and `semantic-pr / semantic-pr` status checks and forbids force-pushes and deletion. +- CI calls `WillBooster/reusable-workflows` at `@main`; repository secrets follow the shared contract (`FNOX_AGE_KEY`, `TAKUMI_GUARD_TOKEN`, and `VERDACCIO_TOKEN` only for private-package consumers). +- A fixed label taxonomy (`d1`–`d5`, `p1`–`p4`, `r: …`, `s: …`, `t: …`) replaces GitHub's default labels. +- Releases use semantic-release with Conventional Commits; the version field is `0.0.0-semantically-released`. From 5b20e5ec12e3221a2cfe979ea79e0b1478092433 Mon Sep 17 00:00:00 2001 From: "Sakamoto, Kazunori" Date: Sat, 8 Aug 2026 00:16:40 +0900 Subject: [PATCH 2/8] docs: fix documented rules to match wbfy/wb behavior and sync .gemini/styleguide.md Apply review feedback: sync .gemini/styleguide.md with the rewritten AGENTS_EXTRA.md, and correct docs/expected-repository-rules.md (workflow ownership vs deletion, WillBooster-only ruleset, per-organization reusable-workflows mirror, PUBLIC_FNOX_AGE_KEY, .env.cloudflare exception, Takumi Guard lockfile scope, ignore-file deletion, redundant-generation script rewrite, workflow marker prefix, and unparseable-input exceptions). Co-authored-by: WillBooster (Claude Code) --- .gemini/styleguide.md | 9 +++++---- docs/expected-repository-rules.md | 24 ++++++++++++------------ 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md index 00c3186cd..62f655515 100644 --- a/.gemini/styleguide.md +++ b/.gemini/styleguide.md @@ -13,8 +13,9 @@ Review in English based on the following coding standards. - Assume all environment variables are defined; if validation is needed, `assert` at startup to fail fast. - Assume local tools such as `git`, `gh`, and `ghq` are installed and authenticated. - Ensure compatibility only with macOS and Linux; do not include Windows-specific code. -- Use `project.env` instead of `process.env` on `wb` package. +- Use `project.env` instead of `process.env` in the `wb` package. - Always drop any Windows support. -- `wbfy` specializes in repositories of the WillBooster / WillBoosterLab organizations; support for other repositories is a best-effort extra. -- `wbfy` is primarily a re-configuration tool: its input is almost always what `wbfy` itself generated in a previous run. Design and implement for that input format only; do NOT generalize parsers or generators to handle arbitrary hand-written or third-party files. -- Files that deviate from `wbfy`-generated output are exceptional cases to be fixed manually in the target repository as a rule; do not add code to `wbfy` to accommodate them. +- `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. +- Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast or overwrite with canonical output. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/docs/expected-repository-rules.md b/docs/expected-repository-rules.md index b7b44f8b4..eae33c5e7 100644 --- a/docs/expected-repository-rules.md +++ b/docs/expected-repository-rules.md @@ -12,24 +12,24 @@ A repository that deviates from these rules is fixed manually (or by re-running - Every managed file is a regular in-repository file: symlinks and paths resolving outside the repository are refused. - Git dependency specifiers may point only at `WillBooster/*` or `WillBoosterLab/*`; anything else aborts the run. - The wbfy badge in `README.md` records the applied `wbfy` version and is the idempotency marker; do not edit or remove it. -- Tool versions are pinned in `mise.toml`; environment variables and secrets live in `fnox.toml` (never `.env*` files); `bunfig.toml` uses Bun's isolated linker; `bun.lock` contains no proxy registry URLs. +- Tool versions are pinned in `mise.toml`; environment variables and secrets live in `fnox.toml`, never in `.env*` application files — the sole exception is `.env.cloudflare`, a gitignored, untracked file holding Cloudflare deploy credentials; `bunfig.toml` uses Bun's isolated linker; `bun.lock` contains no Takumi Guard (`npm.flatt.tech`) URLs (legitimate scoped private-registry URLs such as Verdaccio's remain). ## Ownership markers: what a human may edit -| File(s) | Ownership | -| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AGENTS_EXTRA.md` | The only human-edited agent-instruction file. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/general.mdc`, and `.gemini/styleguide.md` are fully generated from it and are overwritten on every run. | -| `.gitignore`, `.prettierignore`, `.dockerignore` | Human content goes only before `# Generated by wbfy` (head) and after the last `# Project-specific settings` (tail); everything between is regenerated. | -| `oxlint.config.ts`, `oxfmt.config.ts` | Only content outside `// wbfy:start ` / `// wbfy:end ` pairs survives; a file without markers is replaced wholesale. | -| Self-contained GitHub workflows | Owned by `wbfy` iff the first line is exactly `# Generated by wbfy.`; removing that line is the opt-out. Reusable-workflow callers are owned iff every job calls a `WillBooster/reusable-workflows` workflow. | -| `lefthook.yml`, `.lefthook/`, `bunfig.toml` (except raw `[test]` sections), `.editorconfig`, `.gitattributes` | Fully regenerated; manual edits are lost. | -| `package.json` scripts | `wbfy` recognizes only its own generated command shapes (e.g. `bun wb test`, `wb gen-code`, `mise run `); a wrapper must _start with_ the generated command followed by `&&`. Scripts containing shell metacharacters or `cd` are left untouched. | +| File(s) | Ownership | +| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AGENTS_EXTRA.md` | The only human-edited agent-instruction file. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/general.mdc`, and `.gemini/styleguide.md` are fully generated from it and are overwritten on every run. | +| `.gitignore`, `.prettierignore`, `.dockerignore` | Human content goes only before `# Generated by wbfy` (head) and after the last `# Project-specific settings` (tail); everything between is regenerated. `.prettierignore` exists only in Java repositories and `.dockerignore` only alongside a `Dockerfile`/`docker-compose.yml`; when the repository stops qualifying, the whole file — including its head/tail content — is deleted. | +| `oxlint.config.ts`, `oxfmt.config.ts` | Only content outside `// wbfy:start ` / `// wbfy:end ` pairs survives; a file without markers is replaced wholesale. | +| Self-contained GitHub workflows | Owned by `wbfy` iff the file starts with `# Generated by wbfy.`; removing that prefix is the opt-out. In reusable-workflow callers, every job calling the organization's `reusable-workflows` is normalized on each run (other jobs in the same file are left alone); `wbfy` deletes a whole caller file only when every job calls a workflow it is retiring. | +| `lefthook.yml`, `.lefthook/`, `bunfig.toml` (except raw `[test]` sections), `.editorconfig`, `.gitattributes` | Fully regenerated; manual edits are lost. | +| `package.json` scripts | `wbfy` recognizes only its own generated command shapes (e.g. `bun wb test`, `wb gen-code`, `mise run `); a wrapper must _start with_ the generated command followed by `&&`. Scripts containing shell metacharacters or `cd` are left untouched — except a legacy generation script whose commands are all redundant with `wb gen-code`, which is replaced with the canonical command. | ## File-format rules - `package.json` must be strict JSON and is always rewritten via `sort-package-json`. - `tsconfig.json`, `.vscode/settings.json`, and `pyrightconfig.json` must be JSONC; `.releaserc.json` strict JSON; workflows YAML mappings; `renovate.jsonc` is the only supported Renovate config location. -- Unparseable input is skipped with a warning and never overwritten — except `mise.toml` and `fnox.toml`, whose parse or layout errors fail the run. +- Unparseable auxiliary configs (tsconfig, workflows, Renovate, VS Code, pyright) are skipped with a warning and never overwritten. Exceptions: an invalid `package.json` marks the target invalid and fails the run; `mise.toml` and `fnox.toml` parse or layout errors fail the run; an unparseable `.gemini/config.yaml` is replaced with the canonical config. - `fnox.toml` layout is strict: an age provider named exactly `[providers.age]`, no `import`, no profile-specific providers, a root `fnox.toml` when nested ones exist, and the file must be git-tracked. Development defaults live in `[secrets]`; `test`/`staging`/`production` overrides live in `[profiles..secrets]`. ## Project structure expected by `wb` @@ -47,7 +47,7 @@ A repository that deviates from these rules is fixed manually (or by re-running ## GitHub-side conventions (WillBooster / WillBoosterLab repositories) - Squash-only merges with `PR_TITLE` messages, auto-merge enabled, and head-branch deletion on merge. -- A `Protect main` ruleset requires the `test / test` and `semantic-pr / semantic-pr` status checks and forbids force-pushes and deletion. -- CI calls `WillBooster/reusable-workflows` at `@main`; repository secrets follow the shared contract (`FNOX_AGE_KEY`, `TAKUMI_GUARD_TOKEN`, and `VERDACCIO_TOKEN` only for private-package consumers). +- A `Protect main` ruleset (WillBooster-owned repositories only, excluding `reusable-workflows`) requires the `test / test` and `semantic-pr / semantic-pr` status checks — plus `test-rust / test-rust` when the repository contains a `Cargo.toml` — and forbids force-pushes and deletion. +- CI calls the organization's own `reusable-workflows` repository (`WillBooster/…` or `WillBoosterLab/…`) at `@main`; repository secrets follow the shared contract (`FNOX_AGE_KEY` for private repositories, `PUBLIC_FNOX_AGE_KEY` for public WillBooster repositories, `TAKUMI_GUARD_TOKEN`, and `VERDACCIO_TOKEN` only for private-package consumers). - A fixed label taxonomy (`d1`–`d5`, `p1`–`p4`, `r: …`, `s: …`, `t: …`) replaces GitHub's default labels. - Releases use semantic-release with Conventional Commits; the version field is `0.0.0-semantically-released`. From 2afe758c37e86e34f244a5f43a6d703a8359a4d3 Mon Sep 17 00:00:00 2001 From: "Sakamoto, Kazunori" Date: Sat, 8 Aug 2026 00:47:05 +0900 Subject: [PATCH 3/8] docs: correct remaining rule descriptions per second review round Amend the canonical-format rule to allow skip-with-warning, and fix docs/expected-repository-rules.md: mise.toml parse errors are only logged, Python manifests are poetry.lock/uv.lock, git-dependency policy covers package.json only, gen-pr*.yml deletion by filename, published willbooster-configs oxlint.config.ts preservation, postinstall custom segments, fnox root requirement scope, test-layout exemptions, and VERDACCIO_TOKEN for publishers. Co-authored-by: WillBooster (Claude Code) --- .cursor/rules/general.mdc | 2 +- .gemini/styleguide.md | 2 +- AGENTS.md | 2 +- AGENTS_EXTRA.md | 2 +- CLAUDE.md | 2 +- GEMINI.md | 2 +- docs/expected-repository-rules.md | 28 ++++++++++++++-------------- 7 files changed, 20 insertions(+), 20 deletions(-) diff --git a/.cursor/rules/general.mdc b/.cursor/rules/general.mdc index 65d5663bc..d6348d063 100644 --- a/.cursor/rules/general.mdc +++ b/.cursor/rules/general.mdc @@ -48,5 +48,5 @@ alwaysApply: true - Always drop any Windows support. - `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. - Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. -- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast or overwrite with canonical output. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast, overwrite with canonical output, or skip it with a warning — never partially accommodate it. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. - `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md index 62f655515..c031c6791 100644 --- a/.gemini/styleguide.md +++ b/.gemini/styleguide.md @@ -17,5 +17,5 @@ Review in English based on the following coding standards. - Always drop any Windows support. - `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. - Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. -- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast or overwrite with canonical output. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast, overwrite with canonical output, or skip it with a warning — never partially accommodate it. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. - `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/AGENTS.md b/AGENTS.md index a3a6a72b6..270400e2e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,5 +42,5 @@ - Always drop any Windows support. - `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. - Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. -- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast or overwrite with canonical output. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast, overwrite with canonical output, or skip it with a warning — never partially accommodate it. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. - `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/AGENTS_EXTRA.md b/AGENTS_EXTRA.md index 6b690b7df..11f5a3d27 100644 --- a/AGENTS_EXTRA.md +++ b/AGENTS_EXTRA.md @@ -2,5 +2,5 @@ - Always drop any Windows support. - `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. - Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. -- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast or overwrite with canonical output. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast, overwrite with canonical output, or skip it with a warning — never partially accommodate it. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. - `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/CLAUDE.md b/CLAUDE.md index fa9c69ac4..658cacfa3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -42,5 +42,5 @@ - Always drop any Windows support. - `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. - Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. -- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast or overwrite with canonical output. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast, overwrite with canonical output, or skip it with a warning — never partially accommodate it. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. - `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/GEMINI.md b/GEMINI.md index c5b86a4cc..27ca60dbb 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -42,5 +42,5 @@ - Always drop any Windows support. - `wbfy` targets WillBooster / WillBoosterLab repositories; others are best-effort. - Simplify implementation to the extreme: whenever a problem can be solved either by code or by an operational rule (a constraint on developers or target repositories), choose the rule. -- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast or overwrite with canonical output. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. +- `wbfy` re-configures its own previous output: support exactly one canonical format per file, and on deviating input, fail fast, overwrite with canonical output, or skip it with a warning — never partially accommodate it. Never add fallback, auto-detection, compatibility, or migration code for hand-written, legacy, or third-party files; fix such files manually in the target repository instead. - `docs/expected-repository-rules.md` lists the rules `wbfy` and `wb` expect of target repositories; update it in the same change when adding or relying on a new expectation. diff --git a/docs/expected-repository-rules.md b/docs/expected-repository-rules.md index eae33c5e7..5e029ff7c 100644 --- a/docs/expected-repository-rules.md +++ b/docs/expected-repository-rules.md @@ -7,35 +7,35 @@ A repository that deviates from these rules is fixed manually (or by re-running ## Repository preconditions - Bun at or above the pinned minimum version is installed; `wbfy` aborts otherwise. -- The target directory has a `package.json` (or another supported manifest such as `pyproject.toml`, `go.mod`, `pom.xml`, `pubspec.yaml`). +- The target directory has a `package.json` (or another supported manifest such as `poetry.lock`, `uv.lock`, `go.mod`, `pom.xml`, `pubspec.yaml`). - Monorepos place workspaces under `packages/*` and/or the patterns declared in the root `package.json` `workspaces` array. - Every managed file is a regular in-repository file: symlinks and paths resolving outside the repository are refused. -- Git dependency specifiers may point only at `WillBooster/*` or `WillBoosterLab/*`; anything else aborts the run. +- Git dependency specifiers in `package.json` files may point only at `WillBooster/*` or `WillBoosterLab/*`; anything else aborts the run (other ecosystems' manifests are not checked). - The wbfy badge in `README.md` records the applied `wbfy` version and is the idempotency marker; do not edit or remove it. - Tool versions are pinned in `mise.toml`; environment variables and secrets live in `fnox.toml`, never in `.env*` application files — the sole exception is `.env.cloudflare`, a gitignored, untracked file holding Cloudflare deploy credentials; `bunfig.toml` uses Bun's isolated linker; `bun.lock` contains no Takumi Guard (`npm.flatt.tech`) URLs (legitimate scoped private-registry URLs such as Verdaccio's remain). ## Ownership markers: what a human may edit -| File(s) | Ownership | -| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AGENTS_EXTRA.md` | The only human-edited agent-instruction file. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/general.mdc`, and `.gemini/styleguide.md` are fully generated from it and are overwritten on every run. | -| `.gitignore`, `.prettierignore`, `.dockerignore` | Human content goes only before `# Generated by wbfy` (head) and after the last `# Project-specific settings` (tail); everything between is regenerated. `.prettierignore` exists only in Java repositories and `.dockerignore` only alongside a `Dockerfile`/`docker-compose.yml`; when the repository stops qualifying, the whole file — including its head/tail content — is deleted. | -| `oxlint.config.ts`, `oxfmt.config.ts` | Only content outside `// wbfy:start ` / `// wbfy:end ` pairs survives; a file without markers is replaced wholesale. | -| Self-contained GitHub workflows | Owned by `wbfy` iff the file starts with `# Generated by wbfy.`; removing that prefix is the opt-out. In reusable-workflow callers, every job calling the organization's `reusable-workflows` is normalized on each run (other jobs in the same file are left alone); `wbfy` deletes a whole caller file only when every job calls a workflow it is retiring. | -| `lefthook.yml`, `.lefthook/`, `bunfig.toml` (except raw `[test]` sections), `.editorconfig`, `.gitattributes` | Fully regenerated; manual edits are lost. | -| `package.json` scripts | `wbfy` recognizes only its own generated command shapes (e.g. `bun wb test`, `wb gen-code`, `mise run `); a wrapper must _start with_ the generated command followed by `&&`. Scripts containing shell metacharacters or `cd` are left untouched — except a legacy generation script whose commands are all redundant with `wb gen-code`, which is replaced with the canonical command. | +| File(s) | Ownership | +| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AGENTS_EXTRA.md` | The only human-edited agent-instruction file. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/general.mdc`, and `.gemini/styleguide.md` are fully generated from it and are overwritten on every run. | +| `.gitignore`, `.prettierignore`, `.dockerignore` | Human content goes only before `# Generated by wbfy` (head) and after the last `# Project-specific settings` (tail); everything between is regenerated. `.prettierignore` exists only in Java repositories and `.dockerignore` only alongside a `Dockerfile`/`docker-compose.yml`; when the repository stops qualifying, the whole file — including its head/tail content — is deleted. | +| `oxlint.config.ts`, `oxfmt.config.ts` | Only content outside `// wbfy:start ` / `// wbfy:end ` pairs survives; a file without markers is replaced wholesale — except a published `willbooster-configs` package's `oxlint.config.ts`, which is preserved as product content. | +| Self-contained GitHub workflows | Owned by `wbfy` iff the file starts with `# Generated by wbfy.`; removing that prefix is the opt-out. In reusable-workflow callers, every job calling the organization's `reusable-workflows` is normalized on each run (other jobs in the same file are left alone); `wbfy` deletes a whole caller file only when every job calls a workflow it is retiring — except files named `gen-pr*.yml`, which are deleted by filename alone regardless of content. | +| `lefthook.yml`, `.lefthook/`, `bunfig.toml` (except raw `[test]` sections), `.editorconfig`, `.gitattributes` | Fully regenerated; manual edits are lost. | +| `package.json` scripts | `wbfy` recognizes only its own generated command shapes (e.g. `bun wb test`, `wb gen-code`, `mise run `); a wrapper of a generated script (e.g. `test`) must _start with_ the generated command followed by `&&`, while in `postinstall`/`gen-code` custom segments before or after the recognized generation segment are preserved in place. Scripts containing shell metacharacters or `cd` are left untouched — except a legacy generation script whose commands are all redundant with `wb gen-code`, which is replaced with the canonical command. | ## File-format rules - `package.json` must be strict JSON and is always rewritten via `sort-package-json`. - `tsconfig.json`, `.vscode/settings.json`, and `pyrightconfig.json` must be JSONC; `.releaserc.json` strict JSON; workflows YAML mappings; `renovate.jsonc` is the only supported Renovate config location. -- Unparseable auxiliary configs (tsconfig, workflows, Renovate, VS Code, pyright) are skipped with a warning and never overwritten. Exceptions: an invalid `package.json` marks the target invalid and fails the run; `mise.toml` and `fnox.toml` parse or layout errors fail the run; an unparseable `.gemini/config.yaml` is replaced with the canonical config. -- `fnox.toml` layout is strict: an age provider named exactly `[providers.age]`, no `import`, no profile-specific providers, a root `fnox.toml` when nested ones exist, and the file must be git-tracked. Development defaults live in `[secrets]`; `test`/`staging`/`production` overrides live in `[profiles..secrets]`. +- Unparseable auxiliary configs (tsconfig, workflows, Renovate, VS Code, pyright) are skipped with a warning and never overwritten. Exceptions: an invalid `package.json` marks the target invalid and fails the run; `fnox.toml` parse or layout errors fail the run; an unparseable `mise.toml` is left untouched and only logged; an unparseable `.gemini/config.yaml` is replaced with the canonical config. +- `fnox.toml` layout is strict: an age provider named exactly `[providers.age]`, no `import`, no profile-specific providers, a root `fnox.toml` when a nested config declares its own age provider, and the file must be git-tracked. Development defaults live in `[secrets]`; `test`/`staging`/`production` overrides live in `[profiles..secrets]`. ## Project structure expected by `wb` - Source code lives in `src/`, scripts in `scripts/`, framework code in `app/`. -- Under `test/`, only `unit/`, `e2e/`, `debug/`, `helpers/`, and `fixtures/` may exist, and `*.test.*` / `*.spec.*` files only under the first three; violations fail `wb lint` and `wb test`. A package with its own `playwright.config.ts` must have `test/e2e/`. +- Under `test/`, only `unit/`, `e2e/`, `debug/`, `helpers/`, and `fixtures/` may exist, and `*.test.*` / `*.spec.*` files only under the first three (fixture data under `test/fixtures/` and hidden entries are exempt); violations fail `wb lint` and `wb test`. A non-workspace-root package with its own `playwright.config.ts` must have `test/e2e/`; a workspace root may share a root-level `playwright.config.ts` while the e2e specs live in one app package. - `package.json` scripts follow the `wbfy`-generated set (`typecheck`, `lint`, `test`, `test/ci`, `verify`, …); optional hooks such as `build`, `gen-code`, `deploy`, `deploy:staging`, `seed`, and `docker/build/prepare` are picked up by name. - `WB_ENV` is one of `development` / `test` / `staging` / `production`; environment variables come from `fnox.toml` plus `mise env`. - Docker apps have a `Dockerfile` whose container listens on port 8080 (the host port comes from `PORT`); dev servers default to port 3000 (8787 for plain Workers). @@ -48,6 +48,6 @@ A repository that deviates from these rules is fixed manually (or by re-running - Squash-only merges with `PR_TITLE` messages, auto-merge enabled, and head-branch deletion on merge. - A `Protect main` ruleset (WillBooster-owned repositories only, excluding `reusable-workflows`) requires the `test / test` and `semantic-pr / semantic-pr` status checks — plus `test-rust / test-rust` when the repository contains a `Cargo.toml` — and forbids force-pushes and deletion. -- CI calls the organization's own `reusable-workflows` repository (`WillBooster/…` or `WillBoosterLab/…`) at `@main`; repository secrets follow the shared contract (`FNOX_AGE_KEY` for private repositories, `PUBLIC_FNOX_AGE_KEY` for public WillBooster repositories, `TAKUMI_GUARD_TOKEN`, and `VERDACCIO_TOKEN` only for private-package consumers). +- CI calls the organization's own `reusable-workflows` repository (`WillBooster/…` or `WillBoosterLab/…`) at `@main`; repository secrets follow the shared contract (`FNOX_AGE_KEY` for private repositories, `PUBLIC_FNOX_AGE_KEY` for public WillBooster repositories, `TAKUMI_GUARD_TOKEN`, and `VERDACCIO_TOKEN` only for consumers or publishers of `@willbooster-private/*` packages). - A fixed label taxonomy (`d1`–`d5`, `p1`–`p4`, `r: …`, `s: …`, `t: …`) replaces GitHub's default labels. - Releases use semantic-release with Conventional Commits; the version field is `0.0.0-semantically-released`. From 86065df0bf10b6ac573707abd2f594a2864cae99 Mon Sep 17 00:00:00 2001 From: "Sakamoto, Kazunori" Date: Sat, 8 Aug 2026 01:02:30 +0900 Subject: [PATCH 4/8] docs: note that bunfig.toml preserves an explicit install.exact = false Co-authored-by: WillBooster (Claude Code) --- docs/expected-repository-rules.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/expected-repository-rules.md b/docs/expected-repository-rules.md index 5e029ff7c..c534fe683 100644 --- a/docs/expected-repository-rules.md +++ b/docs/expected-repository-rules.md @@ -16,14 +16,14 @@ A repository that deviates from these rules is fixed manually (or by re-running ## Ownership markers: what a human may edit -| File(s) | Ownership | -| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AGENTS_EXTRA.md` | The only human-edited agent-instruction file. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/general.mdc`, and `.gemini/styleguide.md` are fully generated from it and are overwritten on every run. | -| `.gitignore`, `.prettierignore`, `.dockerignore` | Human content goes only before `# Generated by wbfy` (head) and after the last `# Project-specific settings` (tail); everything between is regenerated. `.prettierignore` exists only in Java repositories and `.dockerignore` only alongside a `Dockerfile`/`docker-compose.yml`; when the repository stops qualifying, the whole file — including its head/tail content — is deleted. | -| `oxlint.config.ts`, `oxfmt.config.ts` | Only content outside `// wbfy:start ` / `// wbfy:end ` pairs survives; a file without markers is replaced wholesale — except a published `willbooster-configs` package's `oxlint.config.ts`, which is preserved as product content. | -| Self-contained GitHub workflows | Owned by `wbfy` iff the file starts with `# Generated by wbfy.`; removing that prefix is the opt-out. In reusable-workflow callers, every job calling the organization's `reusable-workflows` is normalized on each run (other jobs in the same file are left alone); `wbfy` deletes a whole caller file only when every job calls a workflow it is retiring — except files named `gen-pr*.yml`, which are deleted by filename alone regardless of content. | -| `lefthook.yml`, `.lefthook/`, `bunfig.toml` (except raw `[test]` sections), `.editorconfig`, `.gitattributes` | Fully regenerated; manual edits are lost. | -| `package.json` scripts | `wbfy` recognizes only its own generated command shapes (e.g. `bun wb test`, `wb gen-code`, `mise run `); a wrapper of a generated script (e.g. `test`) must _start with_ the generated command followed by `&&`, while in `postinstall`/`gen-code` custom segments before or after the recognized generation segment are preserved in place. Scripts containing shell metacharacters or `cd` are left untouched — except a legacy generation script whose commands are all redundant with `wb gen-code`, which is replaced with the canonical command. | +| File(s) | Ownership | +| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AGENTS_EXTRA.md` | The only human-edited agent-instruction file. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/general.mdc`, and `.gemini/styleguide.md` are fully generated from it and are overwritten on every run. | +| `.gitignore`, `.prettierignore`, `.dockerignore` | Human content goes only before `# Generated by wbfy` (head) and after the last `# Project-specific settings` (tail); everything between is regenerated. `.prettierignore` exists only in Java repositories and `.dockerignore` only alongside a `Dockerfile`/`docker-compose.yml`; when the repository stops qualifying, the whole file — including its head/tail content — is deleted. | +| `oxlint.config.ts`, `oxfmt.config.ts` | Only content outside `// wbfy:start ` / `// wbfy:end ` pairs survives; a file without markers is replaced wholesale — except a published `willbooster-configs` package's `oxlint.config.ts`, which is preserved as product content. | +| Self-contained GitHub workflows | Owned by `wbfy` iff the file starts with `# Generated by wbfy.`; removing that prefix is the opt-out. In reusable-workflow callers, every job calling the organization's `reusable-workflows` is normalized on each run (other jobs in the same file are left alone); `wbfy` deletes a whole caller file only when every job calls a workflow it is retiring — except files named `gen-pr*.yml`, which are deleted by filename alone regardless of content. | +| `lefthook.yml`, `.lefthook/`, `bunfig.toml` (except raw `[test]` sections and an explicit `[install]` `exact = false`), `.editorconfig`, `.gitattributes` | Fully regenerated; manual edits are lost. | +| `package.json` scripts | `wbfy` recognizes only its own generated command shapes (e.g. `bun wb test`, `wb gen-code`, `mise run `); a wrapper of a generated script (e.g. `test`) must _start with_ the generated command followed by `&&`, while in `postinstall`/`gen-code` custom segments before or after the recognized generation segment are preserved in place. Scripts containing shell metacharacters or `cd` are left untouched — except a legacy generation script whose commands are all redundant with `wb gen-code`, which is replaced with the canonical command. | ## File-format rules From e1e0b0707225fb790bc85e6327b5890edcf3848b Mon Sep 17 00:00:00 2001 From: "Sakamoto, Kazunori" Date: Sat, 8 Aug 2026 01:19:43 +0900 Subject: [PATCH 5/8] docs: refine workflow deletion and gen-code segment descriptions Co-authored-by: WillBooster (Claude Code) --- docs/expected-repository-rules.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/expected-repository-rules.md b/docs/expected-repository-rules.md index c534fe683..ff905332b 100644 --- a/docs/expected-repository-rules.md +++ b/docs/expected-repository-rules.md @@ -16,14 +16,14 @@ A repository that deviates from these rules is fixed manually (or by re-running ## Ownership markers: what a human may edit -| File(s) | Ownership | -| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AGENTS_EXTRA.md` | The only human-edited agent-instruction file. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/general.mdc`, and `.gemini/styleguide.md` are fully generated from it and are overwritten on every run. | -| `.gitignore`, `.prettierignore`, `.dockerignore` | Human content goes only before `# Generated by wbfy` (head) and after the last `# Project-specific settings` (tail); everything between is regenerated. `.prettierignore` exists only in Java repositories and `.dockerignore` only alongside a `Dockerfile`/`docker-compose.yml`; when the repository stops qualifying, the whole file — including its head/tail content — is deleted. | -| `oxlint.config.ts`, `oxfmt.config.ts` | Only content outside `// wbfy:start ` / `// wbfy:end ` pairs survives; a file without markers is replaced wholesale — except a published `willbooster-configs` package's `oxlint.config.ts`, which is preserved as product content. | -| Self-contained GitHub workflows | Owned by `wbfy` iff the file starts with `# Generated by wbfy.`; removing that prefix is the opt-out. In reusable-workflow callers, every job calling the organization's `reusable-workflows` is normalized on each run (other jobs in the same file are left alone); `wbfy` deletes a whole caller file only when every job calls a workflow it is retiring — except files named `gen-pr*.yml`, which are deleted by filename alone regardless of content. | -| `lefthook.yml`, `.lefthook/`, `bunfig.toml` (except raw `[test]` sections and an explicit `[install]` `exact = false`), `.editorconfig`, `.gitattributes` | Fully regenerated; manual edits are lost. | -| `package.json` scripts | `wbfy` recognizes only its own generated command shapes (e.g. `bun wb test`, `wb gen-code`, `mise run `); a wrapper of a generated script (e.g. `test`) must _start with_ the generated command followed by `&&`, while in `postinstall`/`gen-code` custom segments before or after the recognized generation segment are preserved in place. Scripts containing shell metacharacters or `cd` are left untouched — except a legacy generation script whose commands are all redundant with `wb gen-code`, which is replaced with the canonical command. | +| File(s) | Ownership | +| --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AGENTS_EXTRA.md` | The only human-edited agent-instruction file. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/general.mdc`, and `.gemini/styleguide.md` are fully generated from it and are overwritten on every run. | +| `.gitignore`, `.prettierignore`, `.dockerignore` | Human content goes only before `# Generated by wbfy` (head) and after the last `# Project-specific settings` (tail); everything between is regenerated. `.prettierignore` exists only in Java repositories and `.dockerignore` only alongside a `Dockerfile`/`docker-compose.yml`; when the repository stops qualifying, the whole file — including its head/tail content — is deleted. | +| `oxlint.config.ts`, `oxfmt.config.ts` | Only content outside `// wbfy:start ` / `// wbfy:end ` pairs survives; a file without markers is replaced wholesale — except a published `willbooster-configs` package's `oxlint.config.ts`, which is preserved as product content. | +| Self-contained GitHub workflows | Owned by `wbfy` iff the file starts with `# Generated by wbfy.`; removing that prefix is the opt-out. In reusable-workflow callers, every job calling the organization's `reusable-workflows` is normalized on each run (other jobs in the same file are left alone — except in `test-rust.yml` of a Rust repository, where every job not calling a reusable workflow is removed); `wbfy` deletes a whole caller file only when every job calls a workflow it is retiring — except `gen-pr*.yml`, `autofix.yml`, `autofix-apply.yml`, and `.github/semantic.yml`, which are deleted by filename alone regardless of content. | +| `lefthook.yml`, `.lefthook/`, `bunfig.toml` (except raw `[test]` sections and an explicit `[install]` `exact = false`), `.editorconfig`, `.gitattributes` | Fully regenerated; manual edits are lost. | +| `package.json` scripts | `wbfy` recognizes only its own generated command shapes (e.g. `bun wb test`, `wb gen-code`, `mise run `); a wrapper of a generated script (e.g. `test`) must _start with_ the generated command followed by `&&`, while custom segments in `postinstall` (and in a hand-written `gen-code`) keep their position relative to the recognized generation segment, and a managed `gen-code` is rewritten as `bun wb gen-code` followed by the custom segments. Scripts containing shell metacharacters or `cd` are left untouched — except a legacy generation script whose commands are all redundant with `wb gen-code`, which is replaced with the canonical command. | ## File-format rules From d069608a9ac8f0f9a2b5492bc688b95bb6532cdd Mon Sep 17 00:00:00 2001 From: "Sakamoto, Kazunori" Date: Sat, 8 Aug 2026 01:41:17 +0900 Subject: [PATCH 6/8] docs: add sync-init.yml and branchless release.yml workflow deletion paths Co-authored-by: WillBooster (Claude Code) --- docs/expected-repository-rules.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/expected-repository-rules.md b/docs/expected-repository-rules.md index ff905332b..24ad38534 100644 --- a/docs/expected-repository-rules.md +++ b/docs/expected-repository-rules.md @@ -16,14 +16,14 @@ A repository that deviates from these rules is fixed manually (or by re-running ## Ownership markers: what a human may edit -| File(s) | Ownership | -| --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AGENTS_EXTRA.md` | The only human-edited agent-instruction file. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/general.mdc`, and `.gemini/styleguide.md` are fully generated from it and are overwritten on every run. | -| `.gitignore`, `.prettierignore`, `.dockerignore` | Human content goes only before `# Generated by wbfy` (head) and after the last `# Project-specific settings` (tail); everything between is regenerated. `.prettierignore` exists only in Java repositories and `.dockerignore` only alongside a `Dockerfile`/`docker-compose.yml`; when the repository stops qualifying, the whole file — including its head/tail content — is deleted. | -| `oxlint.config.ts`, `oxfmt.config.ts` | Only content outside `// wbfy:start ` / `// wbfy:end ` pairs survives; a file without markers is replaced wholesale — except a published `willbooster-configs` package's `oxlint.config.ts`, which is preserved as product content. | -| Self-contained GitHub workflows | Owned by `wbfy` iff the file starts with `# Generated by wbfy.`; removing that prefix is the opt-out. In reusable-workflow callers, every job calling the organization's `reusable-workflows` is normalized on each run (other jobs in the same file are left alone — except in `test-rust.yml` of a Rust repository, where every job not calling a reusable workflow is removed); `wbfy` deletes a whole caller file only when every job calls a workflow it is retiring — except `gen-pr*.yml`, `autofix.yml`, `autofix-apply.yml`, and `.github/semantic.yml`, which are deleted by filename alone regardless of content. | -| `lefthook.yml`, `.lefthook/`, `bunfig.toml` (except raw `[test]` sections and an explicit `[install]` `exact = false`), `.editorconfig`, `.gitattributes` | Fully regenerated; manual edits are lost. | -| `package.json` scripts | `wbfy` recognizes only its own generated command shapes (e.g. `bun wb test`, `wb gen-code`, `mise run `); a wrapper of a generated script (e.g. `test`) must _start with_ the generated command followed by `&&`, while custom segments in `postinstall` (and in a hand-written `gen-code`) keep their position relative to the recognized generation segment, and a managed `gen-code` is rewritten as `bun wb gen-code` followed by the custom segments. Scripts containing shell metacharacters or `cd` are left untouched — except a legacy generation script whose commands are all redundant with `wb gen-code`, which is replaced with the canonical command. | +| File(s) | Ownership | +| --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AGENTS_EXTRA.md` | The only human-edited agent-instruction file. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/general.mdc`, and `.gemini/styleguide.md` are fully generated from it and are overwritten on every run. | +| `.gitignore`, `.prettierignore`, `.dockerignore` | Human content goes only before `# Generated by wbfy` (head) and after the last `# Project-specific settings` (tail); everything between is regenerated. `.prettierignore` exists only in Java repositories and `.dockerignore` only alongside a `Dockerfile`/`docker-compose.yml`; when the repository stops qualifying, the whole file — including its head/tail content — is deleted. | +| `oxlint.config.ts`, `oxfmt.config.ts` | Only content outside `// wbfy:start ` / `// wbfy:end ` pairs survives; a file without markers is replaced wholesale — except a published `willbooster-configs` package's `oxlint.config.ts`, which is preserved as product content. | +| Self-contained GitHub workflows | Owned by `wbfy` iff the file starts with `# Generated by wbfy.`; removing that prefix is the opt-out. In reusable-workflow callers, every job calling the organization's `reusable-workflows` is normalized on each run (other jobs in the same file are left alone — except in `test-rust.yml` of a Rust repository, where every job not calling a reusable workflow is removed); `wbfy` deletes a whole caller file only when every job calls a workflow it is retiring — except `gen-pr*.yml`, `autofix.yml`, `autofix-apply.yml`, `sync-init.yml`, and `.github/semantic.yml`, which are deleted by filename alone regardless of content, and `release.yml`, which is deleted wholesale when no release branch is configured. | +| `lefthook.yml`, `.lefthook/`, `bunfig.toml` (except raw `[test]` sections and an explicit `[install]` `exact = false`), `.editorconfig`, `.gitattributes` | Fully regenerated; manual edits are lost. | +| `package.json` scripts | `wbfy` recognizes only its own generated command shapes (e.g. `bun wb test`, `wb gen-code`, `mise run `); a wrapper of a generated script (e.g. `test`) must _start with_ the generated command followed by `&&`, while custom segments in `postinstall` (and in a hand-written `gen-code`) keep their position relative to the recognized generation segment, and a managed `gen-code` is rewritten as `bun wb gen-code` followed by the custom segments. Scripts containing shell metacharacters or `cd` are left untouched — except a legacy generation script whose commands are all redundant with `wb gen-code`, which is replaced with the canonical command. | ## File-format rules From 6f9c52d0d95eb8404c4e29237f244b7f021144a5 Mon Sep 17 00:00:00 2001 From: "Sakamoto, Kazunori" Date: Sat, 8 Aug 2026 01:47:37 +0900 Subject: [PATCH 7/8] docs: scope the Takumi Guard lockfile rule to resolved fields Co-authored-by: WillBooster (Claude Code) --- docs/expected-repository-rules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/expected-repository-rules.md b/docs/expected-repository-rules.md index 24ad38534..d929c6f59 100644 --- a/docs/expected-repository-rules.md +++ b/docs/expected-repository-rules.md @@ -12,7 +12,7 @@ A repository that deviates from these rules is fixed manually (or by re-running - Every managed file is a regular in-repository file: symlinks and paths resolving outside the repository are refused. - Git dependency specifiers in `package.json` files may point only at `WillBooster/*` or `WillBoosterLab/*`; anything else aborts the run (other ecosystems' manifests are not checked). - The wbfy badge in `README.md` records the applied `wbfy` version and is the idempotency marker; do not edit or remove it. -- Tool versions are pinned in `mise.toml`; environment variables and secrets live in `fnox.toml`, never in `.env*` application files — the sole exception is `.env.cloudflare`, a gitignored, untracked file holding Cloudflare deploy credentials; `bunfig.toml` uses Bun's isolated linker; `bun.lock` contains no Takumi Guard (`npm.flatt.tech`) URLs (legitimate scoped private-registry URLs such as Verdaccio's remain). +- Tool versions are pinned in `mise.toml`; environment variables and secrets live in `fnox.toml`, never in `.env*` application files — the sole exception is `.env.cloudflare`, a gitignored, untracked file holding Cloudflare deploy credentials; `bunfig.toml` uses Bun's isolated linker; `bun.lock` carries no Takumi Guard (`npm.flatt.tech`) URLs in its `resolved` fields (explicit direct tarball dependency URLs and legitimate scoped private-registry URLs such as Verdaccio's remain). ## Ownership markers: what a human may edit From adbe3bb971c27db5b16daf99516ef3289a005a5b Mon Sep 17 00:00:00 2001 From: "Sakamoto, Kazunori" Date: Sat, 8 Aug 2026 02:03:28 +0900 Subject: [PATCH 8/8] docs: prefer operational rules over code and document expected repository rules Co-authored-by: WillBooster (Claude Code)