Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changes/ai-slop/docs-config-locations-68a16396.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/attribution/docs-config-locations-5b4128d9.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/bugs/docs-config-locations-739d7f23.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/code-metrics/docs-config-locations-92638a9f.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/codebase-health/docs-config-locations-79f8d46b.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/discovery/docs-config-locations-50746568.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/disk-hygiene/docs-config-locations-f11d0f1b.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/docs-naming/docs-config-locations-584b7616.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/harness-config/docs-config-locations-b3320463.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/improvement/docs-config-locations-65215255.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/multi-agent/docs-config-locations-74199461.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/mutation-testing/docs-config-locations-9c5b0b10.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/overengineering/docs-config-locations-2d5f4636.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/plugin-quality/docs-config-locations-17f7b5a2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/source-control/docs-config-locations-e40b32a8.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
7 changes: 7 additions & 0 deletions .changes/testing/docs-config-locations-18626a62.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Carries a generated copy of the config-cascade contract's config locations page at `reference/config-locations.md`, the one list of where plugin config lives.
14 changes: 8 additions & 6 deletions docs/contracts/commit-convention/README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Commit-convention enforcement seam
# Commit-convention enforcement contract

Owner doc for the machine-readable **enforcement** read of a consumer's commit-subject /
PR-title convention. This concern is consumed by **more than one plugin**: `source-control`
Expand All @@ -17,12 +17,12 @@ Enforcement reads a key that file lacks from the folder-form file below. Draftin
the folder-form file: the model resolves the YAML and the personal markdown layers in
[`source-control/reference/config-resolution.md`](../../../plugins/source-control/reference/config-resolution.md).
That document owns **drafting** resolution: how `/source-control:commit` and `/source-control:pull-request`
compose a compliant subject/title. This seam owns the **enforcement** resolution: how a
compose a compliant subject/title. This contract owns the **enforcement** resolution: how a
zero-dependency hook decides whether an *already-formed* subject/title is allowed.

The two reads are deliberately not identical:

| | Drafting (config-resolution.md) | Enforcement (this seam) |
| | Drafting (config-resolution.md) | Enforcement (this contract) |
|---|---|---|
| Reader | the model | a POSIX sh hook (`[[ =~ ]]` / `grep -E`) |
| Layers read | user-global, team, local, per-key merge | **team-tracked**: `docs/conventions/source-control.yaml`, then the folder-form `docs/conventions/source-control/commit-convention.yml`; for `subject_pattern` only, and only where those set none, the git-ignored personal `docs/conventions/source-control.local.yaml`, never merged |
Expand Down Expand Up @@ -59,6 +59,8 @@ name the file to change.
it: an operator who wants `/source-control:commit` to draft to the same pattern also sets
`## subject_pattern` in the drafting personal override, `.claude/source-control.local.md`.

A plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../config-cascade/locations.md) says.

The folder-form file, and its fail-closed checks, are read only for a key the YAML lacks: a
broken folder-form file never disables a key the YAML supplies. Each key holds exactly one
value, never a list.
Expand All @@ -82,7 +84,7 @@ name the file to change.
## The folder-form convention file

`docs/conventions/source-control/commit-convention.yml` is a flat-scalar YAML file, the
tool-agnostic file any consumer (this seam's resolver, a commit-msg hook, CI, another agent) reads
tool-agnostic file any consumer (the enforcement resolver, a commit-msg hook, CI, another agent) reads
with one sed. It is the path the org standards sync writes. Enforcement reads it only for a key
`docs/conventions/source-control.yaml` lacks.

Expand Down Expand Up @@ -115,7 +117,7 @@ Contract points:
- **`dialect:`** (optional, default `posix-ere`) declares the regex dialect for non-enforcement
consumers (a JS CI runner, a PCRE hook) so they know what they are reading instead of silently
misreading it. Enforcement itself stays POSIX-ERE-only: a declared non-`posix-ere` dialect
disables this seam's enforcement with a diagnostic, exactly like a PCRE-ism in the pattern.
disables enforcement with a diagnostic, exactly like a PCRE-ism in the pattern.
- **Fail closed.** A tracked file that is unreadable, carries a key with an empty value, or is a
symlink or sits under a symlinked path segment whose physical target leaves the repository root
(the target must be a regular file physically under the repo) disables enforcement with a
Expand Down Expand Up @@ -165,6 +167,6 @@ purposes without it.
`scripts/shared-copies.txt`, the commit-msg entry installs both as assets, and a change to either
canonical carries a guardrails release so consumers receive it.

Naming coincidence recorded per the seam rules: the convention file is `docs/conventions/source-control.yaml`, named
Naming coincidence recorded per the shared-concern naming rules: the convention file is `docs/conventions/source-control.yaml`, named
after the concern (delivery workflow), not the plugin. The plugin-name collision is incidental; the
file is not renamed.
4 changes: 4 additions & 0 deletions docs/contracts/config-cascade/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@ adding an optional layer or relaxing a rule additively is a minor bump.

No contract change.

- **`locations.md` lists where plugin config lives.** One editable page of the four layers, the
`.local` naming and the paths outside the contract, pointing at this README's sections. Plugins
that teach a config location carry a generated copy at `reference/config-locations.md`. The
layering axis is unchanged, so `contract_version` stays.
- **`plugin-quality` gets a `standards_repo` row.** A team-only key in `<home>/plugin-quality.yaml`
beside `verification`, read by the auditor agent; unset resolves no standards repository.
- **`improvement` and the `architecture` `improve` object get Implementers rows.** `improvement`
Expand Down
4 changes: 3 additions & 1 deletion docs/contracts/config-cascade/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,9 @@ surface has learned all of them.

This directory is the source of truth: `README.md` (the contract), `CHANGELOG.md` (version history),
and topic siblings such as [`consumer-gotchas.md`](consumer-gotchas.md) (concatenating consumer gotchas
for participating skills, #3547).
for participating skills, #3547). [`locations.md`](locations.md) is the one editable list of config
file locations; each plugin that teaches one carries a generated copy at
`reference/config-locations.md`.

## Boundary: this contract owns the axis, never the keys

Expand Down
48 changes: 48 additions & 0 deletions docs/contracts/config-cascade/locations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Where plugin config lives

The one editable list of config file locations for this marketplace's plugins. Each plugin that
teaches a location carries a generated copy at `reference/config-locations.md`; edit
`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md)
owns the rules; this page points at them.

## The four layers

Lowest first, a higher layer refining a lower one key by key
([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)):

1. **Plugin default**: bundled in the plugin.
2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person,
across repositories.
3. **Team**: `<home>/<concern>.yaml` for keyed values, `<home>/<concern>.md` for prose, tracked
([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)).
4. **Personal override**: `<home>/<concern>.local.<ext>`, gitignored by one
`<home>/**/*.local.*` line
([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)).

`<home>` is the repository's convention home, bound by the pointer region in `AGENTS.md` or
`CLAUDE.md`, default `docs/conventions`
([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)).
`<concern>` is the plugin's name, or a cross-plugin convention's name.

## Not a plugin config location

- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/<name>`.
- **No new `.claude/` file for plugin config.** Write new team and personal files at `<home>`.
- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`,
`.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`.
- **Machine-scope plugin state** under `~/.claude/` is outside it too
([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)).

## A plugin that still reads an old path

Some plugins still read `~/.claude/<name>` or `.claude/<name>.local.<ext>`. Those reads keep
working until each plugin migrates in its own change; they are not locations to copy.

A tracked `.claude/<name>` team file is still a supported team-layer location, read only when no
`<home>` file supplies the layer
([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)).

A plugin's own docs name what it reads today; the contract's
[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers)
table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations)
section list each one.
2 changes: 2 additions & 0 deletions docs/contracts/finding-suppression/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ The consuming plugin names its own surface. The first adopter, `harness-config`'
| 2 | team (tracked) | `<home>/harness-config.yaml` (`<home>` from the convention-home pointer line, default `docs/conventions`) |
| 3 | personal override (gitignored) | `.claude/audit-pass.local.md` |

A plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../config-cascade/locations.md) says.

In a YAML concern file the `suppressions` mapping sits at the root with the entry shape below; a
reader that uses the shared YAML-subset parser needs the `"anchor/v1":` key quoted.

Expand Down
6 changes: 4 additions & 2 deletions docs/contracts/rendered-views/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -830,8 +830,8 @@ validation answer set). Fleet audits check those surfaces against this section.
copies the state the user built out as text they can paste into the session or commit. For
the author's version of this rule, see S2, section "Custom editing interfaces"
([source list](../../finding-your-unknowns.md#sources-and-citation-shape)). The doctrine
recurs three times independently in the corpus; it is what keeps a throwaway editor inside
the agent loop instead of becoming a dead end.
recurs three times independently in the corpus; without the control, the state a user
builds in a throwaway editor stays in the browser, so the session never sees it.

**Who is bound.** Skills that emit interactive HTML artifacts cite this section.

Expand Down Expand Up @@ -928,6 +928,8 @@ lane. A skill runs its `resolve` command and never reads the files itself.
chain). Each lane registers once in the medium registry with its view kinds, whether it is
hosted-capable, and its default.

A plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../config-cascade/locations.md) says.

## Template vendoring posture

**Decision.** Do not vendor the 31 html-effectiveness corpus templates (20 gallery +
Expand Down
2 changes: 2 additions & 0 deletions docs/conventions/review-digest.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,8 @@ an earlier one key by key:
the layer below.
3. personal override `.claude/review-digest.local.json`

A plugin still reads, or reports as retired, the `.claude/` paths named here; until the plugin migrates, keep config where this page says it is read, then move it where [config locations](../contracts/config-cascade/locations.md) says.

The result names the layer that supplied each value (`team <commit>:<path>`, `user-global <path>`,
`personal-override <path>`, or `default`). Quote glob values in the YAML file (`"**/hooks/**"`),
since a plain `*` opens an alias.
Expand Down
51 changes: 51 additions & 0 deletions plugins/ai-slop/reference/config-locations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
<!-- GENERATED from docs/contracts/config-cascade/locations.md by scripts/sync-shared-copies.sh. Do not edit this copy:
edit the canonical source, then rerun the script. -->

# Where plugin config lives

The one editable list of config file locations for this marketplace's plugins. Each plugin that
teaches a location carries a generated copy at `reference/config-locations.md`; edit
`docs/contracts/config-cascade/locations.md` in claude-code-plugins, never a copy. The [config-cascade contract](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md)
owns the rules; this page points at them.

## The four layers

Lowest first, a higher layer refining a lower one key by key
([The layers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#the-layers)):

1. **Plugin default**: bundled in the plugin.
2. **`userConfig`**: the plugin's option in Claude Code user or managed settings, per person,
across repositories.
3. **Team**: `<home>/<concern>.yaml` for keyed values, `<home>/<concern>.md` for prose, tracked
([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)).
4. **Personal override**: `<home>/<concern>.local.<ext>`, gitignored by one
`<home>/**/*.local.*` line
([Personal override naming](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#personal-override-naming-and-the-consumer-gitignore)).

`<home>` is the repository's convention home, bound by the pointer region in `AGENTS.md` or
`CLAUDE.md`, default `docs/conventions`
([Expression doctrine](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)).
`<concern>` is the plugin's name, or a cross-plugin convention's name.

## Not a plugin config location

- **No user-global file.** A per-person value goes in `userConfig`, never `~/.claude/<name>`.
- **No new `.claude/` file for plugin config.** Write new team and personal files at `<home>`.
- **Claude Code's own files are outside this contract**: `~/.claude/settings.json`,
`.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `CLAUDE.local.md`.
- **Machine-scope plugin state** under `~/.claude/` is outside it too
([Scope](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#expression-doctrine-which-surfaces-are-files-and-which-are-convention-docs)).

## A plugin that still reads an old path

Some plugins still read `~/.claude/<name>` or `.claude/<name>.local.<ext>`. Those reads keep
working until each plugin migrates in its own change; they are not locations to copy.

A tracked `.claude/<name>` team file is still a supported team-layer location, read only when no
`<home>` file supplies the layer
([Location of the team layer](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#location-of-the-team-layer-a-docs-convention-file-or-claudename)).

A plugin's own docs name what it reads today; the contract's
[Implementers](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#implementers)
table and [Deviations](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/config-cascade/README.md#deviations)
section list each one.
4 changes: 3 additions & 1 deletion plugins/ai-slop/skills/audit/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -214,7 +214,9 @@ the fix flow, under [Non-repository targets](#non-repository-targets).
- `plugins/` is not in scope; plugin content is audited in its own repository.
- The detector's user config layer is the JSON file `$HOME/.claude/ai-slop.json`, even when
`CLAUDE_CONFIG_DIR` is set; the team and personal layers are YAML. Its project layers come from
the session's project directory.
the session's project directory. The plugin still reads that JSON file until it migrates
([#18004](https://github.com/melodic-software/claude-code-plugins/issues/18004)); then it moves
where [config locations](../../reference/config-locations.md) says.
- A path target such as `~/.claude` covers every `*.md` beneath it.

### Non-repository targets
Expand Down
Loading
Loading