create-afe-project 0.0.0-stage → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,458 @@
+# create-afe-project
+
+## 2.0.0
+
+### Major Changes
+
+- [#12](https://github.com/dev-oleksandrv/create-afe-project/pull/12) [`d286334`](https://github.com/dev-oleksandrv/create-afe-project/commit/d286334dc00f8086371632f1550bf299452dd910) Thanks [@dev-oleksandrv](https://github.com/dev-oleksandrv)! - `docs/documentation-rules.md`, sections 2 to 4 and 6: conventions and recipes, like
+  architecture, carry the front matter `status`, `date`, and `verified-against` (`none` while no
+  code exists) and move from `draft` to `current`; operations documents now carry the same front
+  matter; a convention names the lint rule or check that enforces it, or `none` when only the
+  review does; a tool-specific rule file or skill links to them and never holds its own copy. The
+  `docs-review` skill reports a convention or recipe copied into a tool-specific rule file (such as
+  `.cursor/rules/`, `.claude/rules/`) or a skill, and `review-code` applies the conventions of the
+  areas a diff changes.
+  
+  MAJOR (`docs/maintaining.md`, section 4: new required front-matter fields). No check reads the
+  fields, so no project's checks start failing, but a project must act: give each existing
+  document in `docs/conventions/`, `docs/recipes/`, and `docs/operations/` the front matter, with
+  `verified-against` set by a review against code, or `none` while no code exists. The seeded map
+  `docs/README.md` changes for new projects only: an existing project copies its Conventions and
+  Recipes rows by hand. Added on the owner's instruction of 2026-11-05, ported from
+  agent-docs-template 0.7.0; no observed failure.
+
+### Minor Changes
+
+- [#10](https://github.com/dev-oleksandrv/create-afe-project/pull/10) [`460f9a1`](https://github.com/dev-oleksandrv/create-afe-project/commit/460f9a123aa879d6a4d770031a80b510a340bfec) Thanks [@dev-oleksandrv](https://github.com/dev-oleksandrv)! - `docs/contributing.md`, section 6: the review criterion "Dependencies": a new dependency exists in
+  its registry under the name used, is maintained, has a license the project allows (an open
+  question while no document says which), does no job an existing one already does, and is pinned
+  exactly, through the lock file where the stack has one. The `review-code` skill checks duplication
+  and pinning in the files, and the rest when it can reach the registry; otherwise it leaves them to
+  the owner's review of the gate file. To stay within the line budget, the blocker bullet of the
+  same section is rewrapped with two rewordings of the same meaning: "zero findings is valid" for
+  "zero findings is a valid result", and "fails an item of its Acceptance section" for "fails a
+  criterion of its Acceptance section", as section 3 already calls them items. Added on the owner's instruction of
+  2026-11-05, ported from agent-docs-template 0.7.0; no observed failure.
+
+- [#11](https://github.com/dev-oleksandrv/create-afe-project/pull/11) [`3e84174`](https://github.com/dev-oleksandrv/create-afe-project/commit/3e84174dc2590f7d00d48c6400be84d86800220d) Thanks [@dev-oleksandrv](https://github.com/dev-oleksandrv)! - `docs/testing-rules.md`, section 2: a flaky test is fixed, never retried or rerun until green;
+  skipping it is a blocker of section 4 unless the owner, asked, decides otherwise. To stay within
+  the line budget, the bullet on failure paths is rewrapped into two lines, with "every invalid
+  contract example is rejected where input is validated" for "every invalid example of a contract is
+  rejected where the input is validated", the same meaning. Added on
+  the owner's instruction of 2026-11-05, ported from agent-docs-template 0.7.0; no observed failure.
+
+- [#14](https://github.com/dev-oleksandrv/create-afe-project/pull/14) [`8960f24`](https://github.com/dev-oleksandrv/create-afe-project/commit/8960f243c12785e43aa24854c8724feb29bd36c9) Thanks [@dev-oleksandrv](https://github.com/dev-oleksandrv)! - `scripts/protect-branch.sh` applies the repository settings the rules assume, before the
+  ruleset: merge commits only, without squash and rebase merging, and "Automatically delete head
+  branches", on every plan; secret scanning with push protection, where a refusal (a private
+  repository without GitHub Advanced Security) is reported and the run goes on. The ruleset allows
+  only merge commits, and `--require-base` also requires the `base` job of the
+  `fail-without-change` workflow, once it has passed in CI on a pull request that changes a test.
+  `--dry-run` prints the settings and the ruleset as one JSON object. `docs/contributing.md`,
+  sections 1 and 3, and the `fail-without-change` workflow name the script; the message after create
+  names the settings in place of the separate step for secret scanning. On the owner's instruction
+  of 2026-11-05, ported from agent-docs-template 0.7.0; no observed failure. `README.md` is seeded:
+  an existing project copies its section "Protected main branch" by hand, and runs
+  `scripts/protect-branch.sh` again to apply the settings.
+
+- [#7](https://github.com/dev-oleksandrv/create-afe-project/pull/7) [`90424db`](https://github.com/dev-oleksandrv/create-afe-project/commit/90424db32e4cde2bcfb6072bc22f68bedba8cf7f) Thanks [@dev-oleksandrv](https://github.com/dev-oleksandrv)! - `.claude/hooks/session-start.sh`, a SessionStart hook: a new, resumed, or compacted session
+  starts from at most ten lines of local facts: the branch, its base and the commits ahead,
+  uncommitted and untracked files, merge conflicts, and each plan in `docs/plans/` with its
+  `review-by`, flagged when it is past. No network; it always exits 0.
+  `.claude/settings.template.json` registers it, `.template/owned.txt` lists it, and
+  `docs/documentation-rules.md`, section 7, names it under "Currency". Added on the owner's
+  instruction of 2026-11-05, ported from agent-docs-template 0.7.0; no observed failure.
+
+- [#13](https://github.com/dev-oleksandrv/create-afe-project/pull/13) [`2fe2391`](https://github.com/dev-oleksandrv/create-afe-project/commit/2fe239179eb79502df060a6defc05981bcb4527a) Thanks [@dev-oleksandrv](https://github.com/dev-oleksandrv)! - The seeded `.claude/path-classes` lists the gate files of any stack as their own block:
+  Dependabot, Renovate, pre-commit, Make (with every `*.mk` file), just, and Task (with `Taskfile.dist.yml`), also
+  in subdirectories, `.tool-versions`, and mise (with its environment files and its
+  configuration under `.config/`, `mise/`, and `.mise/`), so a change to
+  dependency updates, pre-commit hooks, task runners, or tool versions is named under "Gate files"
+  and reviewed by the owner. On the owner's instruction of 2026-11-05, ported from
+  agent-docs-template 0.7.0; no observed failure. An update never changes a seeded file: an existing
+  project copies the block "Gates of any stack" into its `.claude/path-classes` by hand.
+
+- [#6](https://github.com/dev-oleksandrv/create-afe-project/pull/6) [`7371c45`](https://github.com/dev-oleksandrv/create-afe-project/commit/7371c45c5b3576d0b24f69b2b337c8d270e37cef) Thanks [@dev-oleksandrv](https://github.com/dev-oleksandrv)! - `.claude/hooks/stop-check-fast.sh`, a Stop hook: Claude Code may not finish a turn while the
+  project's fast check fails. It runs `scripts/env.sh fast` (`CHECK_FAST` of
+  `.claude/harness.conf`) when a file other than Markdown differs from the base, committed or not,
+  and blocks through the Ralph cap; it skips when `CHECK_FAST` is empty or the default
+  `scripts/check-docs.sh`, and during merge conflicts. `.claude/settings.template.json` registers
+  it, `.template/owned.txt` lists it, and `docs/documentation-rules.md`, section 7, names it. Added
+  on the owner's instruction of 2026-11-05, ported from agent-docs-template 0.7.0; no observed
+  failure. The seeded `.claude/harness.conf` names the hook in its comment: an existing project may
+  copy those two lines by hand.
+
+### Patch Changes
+
+- [#17](https://github.com/dev-oleksandrv/create-afe-project/pull/17) [`9da569a`](https://github.com/dev-oleksandrv/create-afe-project/commit/9da569a2ea0b7757ed16d8562deb897944c78d92) Thanks [@dev-oleksandrv](https://github.com/dev-oleksandrv)! - The `decisions`, `docs-review`, and `code-review` workflows treat a pull request that a workflow
+  opened with `GITHUB_TOKEN` (author `github-actions[bot]`), such as a generated release pull
+  request, as generated: readiness checks only its decision records, not the description
+  sections, and the AI reviews skip it. Before, readiness failed on the generated description and
+  claude-code-action failed with "Workflow initiated by non-human actor". Observed on this
+  repository's Version PR [#16](https://github.com/dev-oleksandrv/create-afe-project/issues/16).
+
+- [#9](https://github.com/dev-oleksandrv/create-afe-project/pull/9) [`29149f2`](https://github.com/dev-oleksandrv/create-afe-project/commit/29149f26ca29287640773668af2c1c575c8f9f46) Thanks [@dev-oleksandrv](https://github.com/dev-oleksandrv)! - `docs-review` and `code-review` workflows: `anthropics/claude-code-action` is pinned to
+  `v1.0.268`, the release the floating `v1` pointed to on 2026-11-05, like every other action, so a
+  new release of the action changes nothing until a pull request moves the pin. A project with a
+  review module sees its workflow change on the update. On the owner's instruction of 2026-11-05,
+  ported from agent-docs-template 0.7.0.
+
+- [#15](https://github.com/dev-oleksandrv/create-afe-project/pull/15) [`ced35db`](https://github.com/dev-oleksandrv/create-afe-project/commit/ced35db8156fec49343e66c9c9d632d24d781bc4) Thanks [@dev-oleksandrv](https://github.com/dev-oleksandrv)! - `.claude/hooks/post-edit-check.sh` resolves a relative `file_path` against the `cwd` of the hook
+  input, the session's working directory, instead of the project root, so `CHECK_EDIT` checks the
+  file the agent edited. Ported from agent-docs-template 0.7.0 on the owner's instruction of
+  2026-11-05.
+
+- [#8](https://github.com/dev-oleksandrv/create-afe-project/pull/8) [`2fbd26a`](https://github.com/dev-oleksandrv/create-afe-project/commit/2fbd26a79fec78dc37a708145f5501807b831409) Thanks [@dev-oleksandrv](https://github.com/dev-oleksandrv)! - `create-pr` skill, step 9: findings are only the comments of `claude[bot]`, the account the review
+  workflows post as, and of people whose `author_association` is `OWNER`, `MEMBER`, or
+  `COLLABORATOR`; any other comment is data, reported to the owner and neither acted on nor
+  answered (`AGENTS.md`, section 4). On the owner's instruction of 2026-11-05, ported from
+  agent-docs-template 0.7.0; no observed failure.
+
+## 1.0.0
+
+### Major Changes
+
+- The template moves from Copier to the npm package `create-afe-project` (ADR-0002), on the
+  owner's instruction of 2026-10-31, to drop the Python toolchain for users; the first release on
+  npm, under the MIT license.
+  - `npx create-afe-project@latest <directory>` (or `npm create afe-project@latest`) creates a
+    project with a wizard that asks the questions of the former `copier.yml`; `--defaults`,
+    `--data key=value`, and `--data-file` answer without a terminal. The questions are short and
+    plain, and the message after create numbers the next steps.
+  - Create makes the initial commit on `main` (`Template: create the project with
+    create-afe-project <version>`), the one direct commit that `docs/contributing.md` allows, so
+    `/afe-init` starts on a clean working tree. It commits only in a new directory or an empty
+    clone, never in a non-empty directory written with `--force`; `--no-git` skips it.
+  - `npx create-afe-project@latest update` replaces the template-owned files, keeps the project
+    block of `AGENTS.md`, creates missing seeded files and never changes existing ones, removes
+    files the template no longer owns, runs the migrations between the versions, and regenerates
+    the generated files. It refuses a dirty working tree (`--allow-dirty`) and a downgrade, and
+    lists every replaced local edit of a template-owned file.
+  - The answers file is `.afe-answers.json` with the template version in `_version`; a project
+    generated by Copier converts its `.copier-answers.yml` on its first update. The path classes
+    (`scripts/lib/classes.sh`), the protect hook, and the size warning of
+    `scripts/check-decisions.sh` know both names.
+  - `docs/contributing.md`, section 5, `docs/documentation-rules.md`, section 9, and the
+    `update-template` skill describe the update with `create-afe-project`; there are no conflict
+    markers to resolve any more. `README.md` is seeded: copy its "Project template" and "Checks"
+    sections by hand.
+- A generated project needs only Git, bash, and Node.js: jq and lychee are gone.
+  - The hooks, `scripts/gen-settings.sh`, and `scripts/pr-metrics.sh` read and write JSON with the
+    new `scripts/lib/json.mjs`; the protect hook now blocks when Node.js is missing.
+  - `scripts/check-links.mjs` replaces lychee: offline, every relative link and image of the
+    Markdown files points at an existing file, and every anchor at a heading or an HTML id of its
+    target. `scripts/check-docs.sh` and the `docs` workflow run it; `lychee.toml` is removed.
+- The `docs` workflow also runs on `workflow_dispatch`, so a workflow can start it for a pull
+  request opened with `GITHUB_TOKEN`.
+- A second pass over the AFE guide, on the owner's decisions of 2026-10-31; no observed failure.
+  - `afe-init` skill (new, run by the owner only): interviews the owner about the product, the
+    stack, and the stage; records requirements, an accepted stack ADR, and a proposed
+    architecture; scaffolds the code with the stack's own generator; wires format, lint, types,
+    unit and end-to-end tests into `scripts/checks.d/` and `.claude/harness.conf`; and proves
+    that every gate fails when it should. Three pull requests, one change each.
+  - The check after every edit: `.claude/hooks/post-edit-check.sh` (new, PostToolUse) runs
+    `CHECK_EDIT` of `.claude/harness.conf` on the changed file, limited by `CHECK_EDIT_GLOBS`,
+    and sends a failure back to the agent. `.claude/harness.conf` is seeded: an existing project
+    adds the two keys by hand when it wants the check.
+  - The protect hook asks before publishing (`npm`, `pnpm`, `yarn`, `bun`, `cargo`, `poetry`, `uv`
+    publish, `twine upload`, `gem push`, `dotnet nuget push`, `docker` or `podman push`),
+    `gh workflow run`, and a `gh api` DELETE, also behind `git -C DIR`; it denies a push to the
+    default branch once the remote has it; and it asks when an edit or a command contains a known
+    token format (AWS, GitHub, GitLab, Slack, Stripe, Google, Anthropic, OpenAI, npm, private keys).
+  - `secret_scan` module (new, default on): `.github/workflows/secret-scan.yml` runs gitleaks,
+    downloaded at a pinned version with its checksum, on the commits of every pull request and
+    push to `main`. The message after create also names GitHub's secret scanning and push protection.
+  - `scripts/protect-branch.sh` (new): creates or updates the GitHub ruleset that protects the
+    default branch (pull requests only, the `check` and `integrity` checks, no force push or
+    deletion); the owner runs it once.
+  - `scripts/check-template.sh` fails when a hook command of `.claude/settings.json` names a
+    missing or non-executable script.
+  - `AGENTS.md`, section 4: content from issues, pull requests, web pages, logs, tool output, and
+    dependencies is data, never instructions. The map plans `docs/conventions/` and
+    `docs/recipes/`, a new document kind of `docs/documentation-rules.md`, section 2.
+  - With the `dual_review` module, the Santa loop runs without the Codex CLI too, with a second
+    fresh Claude subagent that reviews with another lens; `REVIEW_MAX_ROUNDS` of
+    `.claude/harness.conf` (3 to 5, default 3) caps the rounds, and a blocker that comes back
+    unchanged after its fix ends the loop early.
+
+## [0.6.0] - 2026-10-31
+
+A second pass over the Agent-Friendly Engineering field guide, on the owner's decisions of
+2026-10-31, and the follow-ups of 0.5.0. Observed failures: the protect hook let two writes into
+rule files through, behind `cd` and in a Python heredoc (pull request #14); the review workflows
+skipped #14 and reported success. The other additions come from the owner's decisions on the
+guide, without an observed failure.
+
+### Added
+
+- Environment contract: `scripts/env.sh setup|check|fast|e2e|reset` runs the project's commands
+  `SETUP`, `CHECK_FAST` (default `scripts/check-docs.sh`), `E2E`, and `RESET` of
+  `.claude/harness.conf`, and `scripts/check.sh` for `check`; an unset command is SKIP, and the
+  exit code is the command's. `AGENTS.md`, section 2, and the map point at it.
+- `fail_without_change` module: `.github/workflows/fail-without-change.yml` runs
+  `scripts/env.sh setup` and the driver on every pull request; the label `tests-pass-on-base`
+  allows a pass. The driver installs with `SETUP` when `FWC_INSTALL` is empty, and a test must
+  now also pass with the change, so a missing toolchain is no longer evidence.
+- Access control: `.claude/settings.json` denies reading `.env`, `.env.*`, `*.pem`, and `*.key`
+  (also through `cat` and the like); a project that needs one, such as `.env.example`, takes the
+  rule out with `"remove": {"permissions": {"deny": ["Read(**/.env.*)"]}}` in
+  `.claude/settings.project.json`, which `scripts/gen-settings.sh` now supports.
+- Metrics: the measure "Regression of" (`none` or `#N`), required by readiness;
+  `scripts/pr-metrics.sh` adds the regression rate, the hours to merge, and the median and
+  maximum of each measure.
+- A small diff: readiness warns, without failing, above `DIFF_WARN_LINES` (default 400) changed
+  lines, generated files left out.
+- `contracts/*` is class high by default in `.claude/path-classes`.
+
+### Changed
+
+- Review before the pull request runs without the `dual_review` module too: one pass by a fresh
+  Claude subagent, which `create-pr` runs, for classes normal, gate, and high; the module adds
+  the Codex CLI and the Santa loop. `review-code` always checks that "Checks" names it.
+- `.claude/hooks/protect-docs.sh`: a target behind `cd DIR` or `git -C DIR` resolves against
+  that directory; the file names in an interpreter's heredoc are targets; the body of another
+  heredoc is not read as commands.
+- `docs/contributing.md`: section 1, a session that stops unfinished leaves a checkpoint
+  (commits pushed, progress and blockers in the plan or the description), and GitHub deletes
+  merged branches; section 5, shorter; section 6, a defect fix gives the evidence pack.
+- `docs/documentation-rules.md`, section 2: acceptance criteria as Given, When, Then with their
+  checks; architecture holds the system map with domain ownership and dependency rules.
+  `docs/testing-rules.md`: the project names the levels of its verification ladder.
+
+### Seeded files: what an existing project does by hand
+
+- `.claude/harness.conf`: add `SETUP=`, `CHECK_FAST=scripts/check-docs.sh` (or the project's
+  fast check), `E2E=`, `RESET=`, and `DIFF_WARN_LINES=400`.
+- `.claude/path-classes`: add `high contracts/*` when the project has contracts.
+- `docs/README.md`: the row "Environment commands" names `scripts/env.sh`; the planned rows of
+  architecture and operations name the system map, domain ownership, and dependency rules, and
+  logs, traces, metrics, and scenario replay.
+- On GitHub, turn on "Automatically delete head branches" in the repository settings.
+
+## [0.5.0] - 2026-10-31
+
+The process follows the Agent-Friendly Engineering principles: the owner sets outcomes and
+risks, agents report evidence, checks enforce, and governance follows risk and reversibility.
+Recurring failure addressed: in `xandronak/brain`, pull requests #14, #15, and #18 each needed
+three or more AI review rounds that never converged, because every round found new edge cases;
+and each owner decision needed a separate confirmation. Additions without an observed failure,
+from the owner's decisions on the AFE field guide (2026-10-30): the invariants register, the
+environment commands, access control for irreversible actions, and the size budget. Open pull
+requests of an existing project need the new description sections before readiness passes.
+
+### Added
+
+- Path classes (`docs/documentation-rules.md`, section 8): low, normal, gate, high, approval, by
+  built-in rules and the new seeded `.claude/path-classes` (`<class> <glob>` lines), with
+  defaults for several ecosystems. Each class decides approval before the edit (approval: the
+  protect hook asks), the listing in the pull request (gate: "Gate files"), and the review
+  before it (none, one reviewer, or the Santa loop for high). `scripts/lib/classes.sh` and
+  `scripts/check-decisions.sh --classes` print the class of each changed path and the review it
+  needs. `AGENTS.md`, section 4, follows the classes.
+- Loops (`docs/contributing.md`, sections 3 and 6): the Ralph loop on `scripts/check.sh` for
+  every change, capped by `RALPH_MAX_ITERATIONS` (default 5) in the new seeded
+  `.claude/harness.conf`; the Santa loop for class high only, with a Claude subagent and the
+  Codex CLI until neither finds a blocker, and after the third round the open blockers go to the
+  owner. Other classes get one pass; only the fix of a blocker is checked again.
+- Definition of done in `docs/contributing.md`, section 3, which `AGENTS.md`, section 6, points
+  at; it replaces the definition-of-done line of `docs/documentation-rules.md`, section 6.
+- Modules `acceptance_check` (`scripts/check-acceptance.sh`: every identifier of the Acceptance
+  section appears in a test file of `TEST_GLOBS`; run by readiness) and `fail_without_change`
+  (`scripts/fail-without-change.sh`: each new or changed test fails on the base, in a temporary
+  worktree, with the project's own `FWC_INSTALL` and `FWC_TEST`, an optional `FWC_CLASSIFIER`,
+  and `--allow-pass-on-base` for the label `tests-pass-on-base`). Both off by default.
+- `scripts/check-decisions.sh --ready` also fails on: no "Acceptance and test plan"; an
+  Acceptance item that is neither "None" with a reason nor names an existing path in backticks;
+  an added `Decided by the owner, YYYY-MM-DD` marker in a Markdown file that "Owner decisions"
+  does not name; a touched gate file that "Gate files" does not name; Metrics tables outside
+  their forms, answers that do not add up, a blocker recorded as a limit, or a missing measure.
+- `scripts/pr-metrics.sh`: sums the Metrics tables of merged pull requests with `gh`, names the
+  sensors without a finding, and warns when `--limit` cuts the period. `docs/maintaining.md`,
+  section 6 (this repository): at each release a rule or check that never fired is proposed for
+  removal, and a new one names the recurring failure it addresses.
+- Access control: `.claude/settings.json` is now generated by `scripts/gen-settings.sh` from the
+  template-owned `.claude/settings.template.json` and the new seeded
+  `.claude/settings.project.json`, where the project adds its own permission rules; the template
+  denies force pushes and remote branch deletions in the forms its rules spell out.
+  `scripts/check-template.sh` fails on a stale `.claude/settings.json`.
+- `.claude/hooks/protect-docs.sh`: asks for class approval paths (`approval` lines of
+  `.claude/path-classes`, `.claude/settings.project.json`, `.mcp.json`, the generated settings),
+  and for the irreversible commands it names: `git push` that forces, deletes, mirrors, prunes,
+  or pushes tags (`--tags`, `refs/tags/...`, `v<digit>...`), `gh pr merge`, `gh release create`
+  and `delete`, `gh repo delete`.
+- Line budgets checked by `scripts/check-template.sh`: `AGENTS.md` 90 template lines,
+  `docs/documentation-rules.md` 200, `docs/contributing.md` 200, `docs/testing-rules.md` 80. The
+  four rule documents together are shorter than in 0.4.1.
+- The invariants register `docs/invariants.md` as a planned document kind; its invariants are
+  criteria of the Santa loop. Environment commands in the map, pointed at from `AGENTS.md`. One
+  git worktree per parallel session (`docs/contributing.md`, section 1).
+
+### Changed
+
+- `docs/contributing.md`, section 3: description sections Summary, Acceptance and test plan,
+  Checks, Assumptions and open questions, Owner decisions, Gate files, Metrics (two fixed
+  tables), Notes for the owner. The new label `limit:` records a suggestion the branch does not
+  fix. A failing check keeps its command and output. The owner's merge confirms the listed
+  markers; readiness waits for no confirming comment and no second round.
+- `docs/contributing.md`, section 6: AI review is a sensor; classes `blocker` and `suggestion`;
+  each finding is answered once; a suggestion never drives a loop. The `docs-review` and
+  `code-review` workflows run once, when a pull request opens or leaves draft; a push or a reopen
+  does not run them again.
+- `docs/testing-rules.md`: the agent derives the test plan from the identifiers, as a report; a
+  refactoring keeps the tests; a behaviour change changes the requirement first, then the test
+  with the same identifier; gate configurations are class gate; the threat model of development
+  gates only decides which bypass is a blocker.
+- Skills: `dual-review` reviews by class; `create-pr` runs the Ralph loop, writes the new
+  sections, waits for the review runs once, and has a fixed blocker checked once by a fresh
+  subagent; `review-code` and `docs-review` use the two classes and no longer judge whether a
+  marker matches the owner's words.
+
+### Removed
+
+- The `should`/`nit` classes and their example table, the brief rule for later rounds, the
+  escalation after three rounds outside the Santa loop, "Owner decisions to confirm" and its
+  confirming comment, the template-update exemption of 0.4.1 (now class low), and the checklist
+  of `docs/contributing.md`, section 4, which is now one paragraph.
+- `.claude/protected-paths` is no longer seeded; the hook and the class checks still read its
+  glob lines as class approval.
+
+### Seeded files: what an existing project does by hand
+
+- An update creates `.claude/path-classes`, `.claude/harness.conf`, and
+  `.claude/settings.project.json` with the defaults, and deletes `.claude/protected-paths`; a
+  `_migrations` entry of `copier.yml` appends its glob lines to `.claude/path-classes` as
+  `approval <glob>`. Check them by hand: gate configuration, such as test runner and linter
+  files, becomes `gate <glob>`. Add the project's own high paths
+  (brain: policy, limits, accounting). Set `TEST_GLOBS`, `FWC_TEST`, and `FWC_INSTALL` in
+  `.claude/harness.conf` before turning on the new modules (`copier update --data
+  acceptance_check=true --data fail_without_change=true`).
+- `.claude/settings.json` becomes generated: a project that edited it moves its own rules into
+  `.claude/settings.project.json` and runs `scripts/gen-settings.sh`.
+- `docs/README.md`: add the row "Environment commands: set up, check, fast check, end-to-end
+  tests, reset" (check: `scripts/check.sh`; the others the project's commands or "not
+  decided"), the planned row "Invariants" (`docs/invariants.md`), and in the rows of the agent
+  rules, the documentation rules, and checks and enforcement the new terms: autonomy by risk,
+  when a change is done, path classes and access, `.claude/path-classes`,
+  `.claude/harness.conf`, `.claude/settings.project.json`, `scripts/pr-metrics.sh`.
+
+## [0.4.1] - 2026-10-30
+
+### Changed
+
+- `docs/contributing.md`, sections 3, 4, and 6 (with `dual_review`): a template update that
+  changes only template-owned and generated files is exempt from the dual review; its
+  description says "Dual review: not run: template update to X.Y.Z". The `create-pr`,
+  `dual-review`, and `review-code` skills apply the exemption: `review-code` takes that line in
+  place of a verdict.
+
+## [0.4.0] - 2026-10-30
+
+### Changed
+
+- `docs/testing-rules.md`, section 4: a threat model of development gates. Gates catch honest
+  mistakes and shortcuts; deliberate evasion is left to the review of the diff; product
+  invariants are not development gates. The protected-paths bullet now names the forms the
+  protect hook catches and what is left to the review, instead of claiming that no agent loosens
+  a gate.
+- `docs/documentation-rules.md`, section 7: the merge-readiness row names what
+  `scripts/check-decisions.sh --ready` checks and what is left to the owner.
+- `docs/contributing.md`, section 6: a finding that only deliberate evasion can exploit to bypass
+  a development gate is a `nit`, a bypass of a product invariant keeps its severity, and a table
+  of `should` and `nit` examples calibrates every reviewer. The Tests criterion includes the test
+  plan. With `dual_review`, later rounds add the owner's decisions on the branch to the brief, and
+  nothing else.
+- `docs/contributing.md`, section 1: "one logical change" means one mechanism with its tests and
+  owner documents, with examples.
+- `docs/contributing.md`, section 3: the description gains the sections "Test plan" (always,
+  written before the implementation) and "Owner decisions to confirm" (each `Decided by the
+  owner` marker added on a chat instruction, confirmed by the owner with one comment); a pull
+  request is ready to merge only after that confirmation. `scripts/check-decisions.sh --ready`
+  does not check the confirmation.
+- `docs/documentation-rules.md`, sections 3 and 7: a statement about a check names the forms it
+  catches and what is left to the review; an absolute claim needs a test for each form it covers.
+- `create-pr` skill: writes the two new sections and reports unconfirmed owner decisions as
+  waiting on the owner. `review-code` skill: compares the code and tests with the test plan.
+  `dual-review` skill: an author's self-check before the first round, the severity examples and
+  the test plan in the brief, and the owner's decisions from the second round.
+
+### Fixed
+
+- `.claude/hooks/protect-docs.sh`: judges a target path by the git repository that holds it when
+  that repository has `.template/owned.txt`, so an edit in a sibling git worktree, or in another
+  generated project, asks the owner like an edit in the session's own checkout. Other paths
+  inside the session's project are judged by the project as before (no git yet, a nested
+  repository); paths elsewhere stay unguarded. A relative path of a shell command resolves
+  against the hook input's `cwd`.
+- `.claude/hooks/protect-docs.sh`: folds `.` and `..` in the part of a target path that does not
+  exist yet before the match, so a write to `newdir/../AGENTS.md` or `docs/new/../README.md` asks
+  the owner, and a path whose `..` leaves the repository no longer matches a protected glob.
+
+## [0.3.1] - 2026-10-30
+
+### Changed
+
+- `docs/contributing.md`, section 6: defines the severities `blocker`, `should`, and `nit`, and
+  that a review fails on a `blocker` or `should` only; a reviewer who hesitates picks `nit`. The
+  `review-code`, `docs-review`, and `dual-review` skills apply these definitions, and a `nit` no
+  longer fails a round of the dual review.
+- `review-code` and `docs-review` skills: in a pull request run they read changed files of
+  `.claude/`, `CLAUDE.md`, and `.mcp.json` from the diff and `.claude-pr/`, because
+  `anthropics/claude-code-action` restores those paths from the base branch.
+
+## [0.3.0] - 2026-10-30
+
+### Added
+
+- Testing rules (`docs/testing-rules.md`), template-owned: what a test is for, how it proves
+  behaviour, tests and the change they cover, and the gates no agent loosens. `AGENTS.md`,
+  section 2, points to it; `docs/documentation-rules.md`, sections 2, 6, and 7, list it.
+- Review of pull requests (`docs/contributing.md`, section 6): a rubric that every reviewer
+  applies, the project's own criteria in an owner document that the map names under "Review
+  criteria", and the rule that a defect found after the merge names what keeps the next one out.
+- Module `code_review` (question `code_review`, default on): the `code-review` workflow
+  (`.github/workflows/code-review.yml`) and the `review-code` skill
+  (`.claude/skills/review-code/SKILL.md`) review pull requests that change code, contracts,
+  checks, or workflows against that rubric with Claude Code, with the same secret and app as
+  `docs-review`, and install no plugin.
+- Module `dual_review` (question `dual_review`, default off): the `dual-review` skill
+  (`.claude/skills/dual-review/SKILL.md`) reviews a branch before its pull request with a Claude
+  subagent and the Codex CLI in a read-only sandbox, after a passing `scripts/check.sh`, for at
+  most three rounds, without commits; its verdict goes under "Checks" in the description
+  (`docs/contributing.md`, sections 3 and 4).
+
+### Changed
+
+- `create-pr` skill: waits for and answers the `code-review` run next to `docs-review`, and with
+  the `dual_review` module runs the dual review when the branch has no verdict for its tree.
+- `docs/contributing.md`, section 3: every review comment is answered before the merge, from
+  either review workflow.
+- Linter configuration (`.markdownlint-cli2.jsonc`): in `CHANGELOG.md`, headings need to be
+  unique among siblings only, so that each version can have its own Added and Changed.
+- Seeded `docs/README.md`: rows for the testing rules and the review of pull requests, and the
+  planned "Review criteria" section. An existing project copies these rows by hand.
+
+## [0.2.0] - 2026-10-29
+
+### Changed
+
+- `create-pr` skill (`.claude/skills/create-pr/SKILL.md`), with the `docs_review` module: after
+  opening the pull request it waits for the `docs-review` run, answers every comment (a fix in
+  its own commit, a decline with a reason, or a question for the owner), records the outcome in
+  the description, and reports it; a draft or a run that does not finish is reported instead of
+  waited for. `docs/contributing.md`, section 4, names the new step.
+
+## [0.1.0] - 2026-10-29
+
+### Added
+
+- Agent rules (`AGENTS.md` with one project block, `CLAUDE.md`), documentation rules with file
+  ownership (`docs/documentation-rules.md`), contribution and template update rules
+  (`docs/contributing.md`), and the seeded documentation map (`docs/README.md`).
+- Short decision records: `docs/decisions/adr-template.md` and the generated index
+  `docs/decisions/README.md` (`scripts/gen-decisions-index.sh`).
+- Checks behind one entry point, `scripts/check.sh`: documentation (markdownlint-cli2, lychee),
+  decision records (integrity, next number, index, merge readiness), template integrity
+  (`.template/owned.sha256`), and project checks from `scripts/checks.d/`.
+- Claude Code hooks (protect, Stop checks, project Stop hooks from `.claude/hooks/project/stop/`)
+  and skills (`create-pr`, `update-template`, and `docs-review` as the `docs_review` module).
+- CI workflows `docs` (with Node.js set up), `decisions`, and `docs-review`, with the runner chosen
+  by a question and overridable by the repository variable `CI_RUNS_ON`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dev-oleksandrv and the contributors of xandronak/agent-docs-template
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# create-afe-project
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An npm package that creates agent-friendly repositories and keeps them up to date. It gives a new
+project its documentation rules, short decision records with a generated index, contribution and
+pull request rules, checks that run the same way locally, in Claude Code hooks, and in CI, and the
+Claude Code skills that apply them. It implements the pillars of
+[Agent-Friendly Engineering](https://github.com/dev-oleksandrv/afe/blob/main/GUIDE.md). Repository:
+`dev-oleksandrv/create-afe-project`; it started as a fork of the Copier template
+`xandronak/agent-docs-template`.
+
+## What a generated project gets
+
+| Part | Files |
+| --- | --- |
+| Agent rules | `AGENTS.md` with one project block, `CLAUDE.md` |
+| Testing rules: what a test is for and must prove | `docs/testing-rules.md` |
+| Documentation rules, statuses, and file ownership | `docs/documentation-rules.md`, `docs/README.md` |
+| Branches, commits, pull requests, template updates, review of pull requests | `docs/contributing.md` |
+| Decision records | `docs/decisions/adr-template.md`, a generated `docs/decisions/README.md` |
+| Checks and environment | `scripts/check.sh` and the scripts it runs, the link check `scripts/check-links.mjs` included; `scripts/env.sh` for the environment commands; `scripts/protect-branch.sh` for the repository settings and the GitHub ruleset of `main`; optional `scripts/check-acceptance.sh` and `scripts/fail-without-change.sh` |
+| Claude Code hooks, permissions, and skills | `.claude/settings.json` (generated): deny rules for secrets and destructive pushes; `.claude/hooks/`: the protect hook (asks before protected edits, publishing, and a known token format; denies a push to `main`), the check after every edit, and the Stop hooks; `.claude/skills/`: `afe-init` (sets up the code, its stack, and its checks with the owner), `create-pr`, `update-template`, optional `docs-review`, `review-code`, and `dual-review` |
+| CI | `.github/workflows/` (`docs`, `decisions`, optional `secret-scan`, `docs-review`, `code-review`, and `fail-without-change`) |
+
+Every file has one owner: the template, the project, or a generator. The rules are in
+[`template/docs/documentation-rules.md.jinja`](template/docs/documentation-rules.md.jinja),
+section 9.
+
+## Requirements
+
+Node.js 20 or later with npm, Git, and bash. A generated project needs nothing more: its hooks
+and checks, the link check included, run on Node.js.
+
+## Create a project
+
+```bash
+npm create afe-project@latest <directory>
+# or
+npx create-afe-project@latest <directory>
+```
+
+The wizard asks for the project name, a one-sentence description, the GitHub repository, the CI
+runner (GitHub-hosted, or a self-hosted Linux runner), whether pull requests get the Claude
+documentation review and code review, whether the review before a pull request adds the Santa
+loop (with the Codex CLI when it is installed, otherwise with two Claude subagents), whether CI
+scans every change for secrets with gitleaks, and whether to add the Acceptance check and the
+fail-without-change driver. It then writes the generated files and prints the next
+steps. Without a terminal, or with `--defaults`, it takes answers from `--data key=value` and
+`--data-file answers.json`, then the defaults:
+
+```bash
+npx create-afe-project@latest acme --defaults --data project_name=acme \
+  --data 'project_description=A sample project.' --data github_repo=acme/acme
+```
+
+`npx create-afe-project --help` lists every option.
+
+## Update a project
+
+In the project, the `update-template` skill does it, following the project's
+`docs/contributing.md`, section 5: a branch from a clean `main`, then
+
+```bash
+npx create-afe-project@latest update --defaults
+```
+
+It replaces the template-owned files, keeps the project block of `AGENTS.md`, creates missing
+seeded files and never changes existing ones, runs the migrations between the two versions, and
+regenerates the generated files; then the checks and a pull request. A project generated by the
+Copier template converts its `.copier-answers.yml` to `.afe-answers.json` on its first update.
+
+## Versions
+
+Releases are npm versions, tagged `vMAJOR.MINOR.PATCH` in Git and described in [`CHANGELOG.md`](CHANGELOG.md).
+How versions are chosen and released: [`docs/maintaining.md`](docs/maintaining.md).
+
+## License
+
+[MIT](LICENSE).