[justinmerrell]

Summary

• .config/ gets a defined key. A concern names the files a tool reads (actions, markdown, yaml, …).
  A tool that reads every file is named for what it looks for (prose, security, spelling).
  CONF-14 checks that a subdirectory is a registered concern. CONF-15 checks that a known tool sits in its own
  concern. EC-0011 now says what .config/ is for: repository-wide quality configuration. A product's language
  toolchain configuration stays with the product. Vale moves from markdown/ to prose/.

• Tool strictness floors (new EC-0044, CONF-16 – CONF-23). Each tool starts from its maintained preset:

  • yamllint extends default;
  • markdownlint keeps default;
  • pyright/basedpyright run at strict, recommended or all;
  • tsconfig sets strict;
  • Biome keeps recommended;
  • gitleaks keeps its default rules.

  Two review requirements add that warnings fail the gate, and that every departure from a preset carries its
  reason.

• A tool-wrapper task layer (TASK-25 – TASK-28, HOOKS-15, TASK-20 relaxed).

  • .config/ holds the rules.
  • taskfiles/tools/<tool>.Taskfile.yml is the one internal place a binary, its --config and its severity
    flags appear.
  • Area fragments compose wrappers, and the root holds the verbs.
  • Hooks and CI run tasks, not binaries.
  • TASK-28 reports a sources glob that matches nothing. Such a task stays "up to date" forever.

• This repository adopts all of it.

  • 18 wrappers.
  • The area fragments match their task names:
    • secrets, schemas, generate and prose split out;
    • checks:check → checks:compile;
    • invariants/classify → cli:*;
    • every fixer ends in :fix.
  • Deterministic gates are cached with go-task sources (checksum). The sources include the tool's config,
    mise.lock and the Taskfiles. A second task check with nothing changed takes about 20 s instead of about
    6 min. task --force check reruns everything.

• A CI pass-marker pilot (decision 0040),
  off by default.

  • A Validate job whose inputs are byte-identical to a proven passing run of the same PR, or of main, can skip.
  • Only CI writes markers, and detect re-proves each one: key, ref, run, and that the workflow and action
    trees are unchanged.
  • Markers are never read on push, merge_group or forks.
  • It is gated by the repository variable CI_PASS_MARKERS, which merges unset, so CI behaves exactly as
    before.

• CODEOWNERS selective gate (feat: a shared CODEOWNERS check, and drop this repo's * catch-all #118).

  • This repository owns only /.github/, /.repo/, /engineering-conventions/definitions/ and two .claude
    trust paths.
  • COMM-09 forbids a catch-all; a waiver is the allowlist.
  • COMM-10 reports a root-anchored path that doesn't exist.

Fixes #118 in part: the offline checks and this repository's file. Owner resolution and write access need the
GitHub API, so they stay on the issue.

Decisions 0038 (concerns and strictness),
0039 (tool wrappers and caching) and
0040 (pass markers) record the reasoning.

Consumer impact

• Requirement IDs touched:
  • new: CONF-14 – CONF-23, TASK-25 – TASK-28, HOOKS-15, COMM-09, COMM-10, EC-0044
  • changed: TASK-20 (relaxed for tool wrappers), COMM-03, COMM-04 and COMM-08 prose
  • changed message: COPY's Vale path is now .config/prose/vale.ini
• Change class: new requirements at warning → feat (a patch in 0.x). TASK-20 relaxed → fix.
• Breaking? No. Everything is proposed at warning.
  • Expect new warnings for a .config/ bucket outside the vocabulary, a Vale config in markdown/, a *
    catch-all in CODEOWNERS, and a fragment task named outside its area.
  • The runner now preparses tsconfig.json, pyrightconfig.json, biome.json(c) and markdownlint JSON. A file
    jsonnet cannot parse gets a PARSE finding, as devcontainer.json already does.
• since is 0.9.2, because release PR chore(release): release 0.9.2 #116 is still open. If chore(release): release 0.9.2 #116 merges first, these move to 0.9.3.

AI usage

• This PR contains code generated by AI coding agents
• I have manually reviewed and tested all AI-generated logic

Test plan

• task --force check passes locally:
  • conventions:self reports "No findings." from both runners;
  • 1112 Rego tests pass;
  • 983 pytest tests pass, fixture repos included.
• Each new conftest requirement ships a fixture repo that fires plus a near-miss, and the findings snapshot is
  updated.
• Generated files were regenerated with task generate; generate:check is clean.
• Caching:
  • a second task check skips unchanged gates;
  • editing one .md reruns only markdownlint, typos and Vale;
  • editing mise.lock invalidates every cached gate;
  • task tool:yamllint is refused as internal.
• lefthook run pre-commit with staged files whose names need quoting.
• ci-pass.sh:
  • the key mode tests pass;
  • prove passes 12 scenarios against a mock gh, including an edit-then-revert forgery, which it refuses.
• Pass-marker trial (needs an admin): set CI_PASS_MARKERS=on and follow decision 0040's "Trying it" steps.

Follow-on issues

• Grouped Dependabot titles exceed the 72-column subject limit #105 (Dependabot titles over 72 columns) is not included: the fix it proposes needs a pull_request_target
  job, which the zizmor gate flags.
• After release: migration issues where the new warnings land:
  • platform's comments/, positioning/ and python/ buckets;
  • infra's flat .config/;
  • the SDK and CLI repositories.

BEGIN_COMMIT_OVERRIDE
feat(conventions): key .config/ concerns on the files a tool reads
feat(conventions): set a strictness floor for tool configuration
feat(conventions): add TASK-25 to TASK-28 and HOOKS-15 for tool wrappers
fix(checks): let a tool wrapper's include set internal under TASK-20
feat(checks): read the Taskfiles in taskfiles/tools/
feat(conventions): forbid a CODEOWNERS catch-all and dead paths
fix(conventions): name .config/prose/vale.ini in the COPY message
END_COMMIT_OVERRIDE

🤖 Generated with Claude Code