diff --git a/.changes/architecture/docs-7537-b-move-79fe0a5c.md b/.changes/architecture/docs-7537-b-move-79fe0a5c.md new file mode 100644 index 0000000000..b834bf79b9 --- /dev/null +++ b/.changes/architecture/docs-7537-b-move-79fe0a5c.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Synced contract copies name their canonical source at `docs/contracts//`, where the plugin contracts moved from `docs/conventions//`. diff --git a/.changes/code-tidying/docs-7537-b-move-6a1e612e.md b/.changes/code-tidying/docs-7537-b-move-6a1e612e.md new file mode 100644 index 0000000000..b834bf79b9 --- /dev/null +++ b/.changes/code-tidying/docs-7537-b-move-6a1e612e.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Synced contract copies name their canonical source at `docs/contracts//`, where the plugin contracts moved from `docs/conventions//`. diff --git a/.changes/corrections/docs-7537-b-move-37e46d5c.md b/.changes/corrections/docs-7537-b-move-37e46d5c.md new file mode 100644 index 0000000000..b834bf79b9 --- /dev/null +++ b/.changes/corrections/docs-7537-b-move-37e46d5c.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Synced contract copies name their canonical source at `docs/contracts//`, where the plugin contracts moved from `docs/conventions//`. diff --git a/.changes/coupling/docs-7537-b-move-01e76014.md b/.changes/coupling/docs-7537-b-move-01e76014.md new file mode 100644 index 0000000000..b834bf79b9 --- /dev/null +++ b/.changes/coupling/docs-7537-b-move-01e76014.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Synced contract copies name their canonical source at `docs/contracts//`, where the plugin contracts moved from `docs/conventions//`. diff --git a/.changes/harness-config/docs-7537-b-move-d8691153.md b/.changes/harness-config/docs-7537-b-move-d8691153.md new file mode 100644 index 0000000000..b834bf79b9 --- /dev/null +++ b/.changes/harness-config/docs-7537-b-move-d8691153.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Synced contract copies name their canonical source at `docs/contracts//`, where the plugin contracts moved from `docs/conventions//`. diff --git a/.changes/improvement/docs-7537-b-move-ca5d7691.md b/.changes/improvement/docs-7537-b-move-ca5d7691.md new file mode 100644 index 0000000000..b834bf79b9 --- /dev/null +++ b/.changes/improvement/docs-7537-b-move-ca5d7691.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Synced contract copies name their canonical source at `docs/contracts//`, where the plugin contracts moved from `docs/conventions//`. diff --git a/.changes/planning/docs-7537-b-move-6b23c863.md b/.changes/planning/docs-7537-b-move-6b23c863.md new file mode 100644 index 0000000000..b834bf79b9 --- /dev/null +++ b/.changes/planning/docs-7537-b-move-6b23c863.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Synced contract copies name their canonical source at `docs/contracts//`, where the plugin contracts moved from `docs/conventions//`. diff --git a/.changes/review/docs-7537-b-move-a00661b7.md b/.changes/review/docs-7537-b-move-a00661b7.md new file mode 100644 index 0000000000..b834bf79b9 --- /dev/null +++ b/.changes/review/docs-7537-b-move-a00661b7.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Synced contract copies name their canonical source at `docs/contracts//`, where the plugin contracts moved from `docs/conventions//`. diff --git a/.changes/session-flow/docs-7537-b-move-0b0a75ac.md b/.changes/session-flow/docs-7537-b-move-0b0a75ac.md new file mode 100644 index 0000000000..b834bf79b9 --- /dev/null +++ b/.changes/session-flow/docs-7537-b-move-0b0a75ac.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Changed + +- Synced contract copies name their canonical source at `docs/contracts//`, where the plugin contracts moved from `docs/conventions//`. diff --git a/docs/conformance-dimensions.md b/docs/conformance-dimensions.md index 15448c3823..430ae7084a 100644 --- a/docs/conformance-dimensions.md +++ b/docs/conformance-dimensions.md @@ -28,8 +28,8 @@ not resolve, or whose lane or checks cell is empty. | id | concern | owner | lane | checks | ci | scope | |---|---|---|---|---|---|---| | dim-8 | A plugin that declares `userConfig`, an external prerequisite or non-trivial configuration ships a check-centric setup skill | docs/plugin-philosophy.md#Setup is explicit and repeatable | `node scripts/validate-plugin-contracts.mjs`, findings filtered to `plugins//`; then judgment: does this plugin meet the setup criteria, and if so does its setup skill offer `check` and `apply`, idempotent and safe to rerun? | `scripts/validate-plugin-contracts.mjs`, judgment | yes | plugin | -| dim-9 | Hook status, failure and skip paths are visible: `statusMessage` on every handler, a `systemMessage` on every missing-prerequisite skip (the owner section states the cadence) | docs/conventions/hook-observability/README.md#Conformance | judgment: for each wired hook in `plugins//hooks/hooks.json`, does it meet every bullet of the owner section? | judgment | no | plugin | -| dim-11 | Every cross-plugin reference is presence-gated with a stated fallback, with no marketplace qualification outside an install recipe | docs/conventions/seam-phrasing/README.md#Conformance | judgment: list each reference this plugin makes to another plugin's skill or agent and say whether the gate and fallback are present | judgment | no | plugin | +| dim-9 | Hook status, failure and skip paths are visible: `statusMessage` on every handler, a `systemMessage` on every missing-prerequisite skip (the owner section states the cadence) | docs/contracts/hook-observability/README.md#Conformance | judgment: for each wired hook in `plugins//hooks/hooks.json`, does it meet every bullet of the owner section? | judgment | no | plugin | +| dim-11 | Every cross-plugin reference is presence-gated with a stated fallback, with no marketplace qualification outside an install recipe | docs/contracts/seam-phrasing/README.md#Conformance | judgment: list each reference this plugin makes to another plugin's skill or agent and say whether the gate and fallback are present | judgment | no | plugin | | dim-12 | The plugin's category fits the taxonomy and the plugin is one cohesive capability | docs/catalog-taxonomy.md#Assignment principle | `bash scripts/check-plugin-manifest-presence.sh`, findings filtered to `plugins//`; then judgment: does the subject-wins-if-salient test pick this category, is the plugin one capability, and has any trigger in the Trigger register fired? | `scripts/check-plugin-manifest-presence.sh`, `scripts/validate-plugins.sh`, judgment | yes | plugin | | dim-13 | Skill names are imperative verb phrases with the fixed verb meanings; leaf collisions are registered | docs/plugin-philosophy.md#Naming | `bash scripts/check-skill-leaf-names.sh`, findings filtered to this plugin; then judgment: does any skill use a word another plugin uses with a different meaning (check `docs/glossary.md`)? | `scripts/check-skill-leaf-names.sh`, judgment | yes | plugin | | dim-14 | A natural request reaches the right skill and no other skill catches it too | docs/plugin-philosophy.md#Naming | judgment: in a fresh subagent given only the skill descriptions of this plugin and of every plugin in the same category, which skill does each of five natural requests for this plugin reach, and does a second skill claim it? | `/harness-ops:audit-native-overlap`, judgment | no | plugin | @@ -41,5 +41,5 @@ not resolve, or whose lane or checks cell is empty. | dim-20 | A second plugin needing teardown first moves the shared teardown shape into an owner doc | docs/plugin-philosophy.md#Setup is explicit and repeatable | judgment: which plugins ship an `apply remove` or other teardown operation, and if two or more do, does an owner doc define the shared shape? | judgment | no | fleet | | dim-21 | A plugin that adopts a registered convention conforms to its owner doc; a convention two plugins share has an owner doc | docs/plugin-philosophy.md#Convention registry | judgment: for each Convention registry row this plugin adopts, does it meet the owner doc's Conformance section? | judgment | no | plugin | | dim-22 | Interactive HTML artifacts carry the reply affordance | docs/finding-your-unknowns.md#Reply-affordance convention | judgment: do this plugin's interactive HTML templates carry the structured capture and reply template the owner section requires? (applies to `prototype`) | judgment | no | plugin | -| dim-23 | Every guardrails hook fix pins its over-fire as a stay-quiet test case | docs/conventions/hook-precision/README.md#Conformance | judgment: for each hook under `plugins/guardrails/hooks/`, does its co-located test carry a stay-quiet case for each over-fire fix? (applies to `guardrails`) | judgment | no | plugin | -| dim-24 | No plugin states a pre-PR step order that conflicts with the canonical one | docs/conventions/pre-pr-ordering/README.md#Conformance | judgment: does any surface in this plugin list pre-PR steps, and if so does it cite the sequence instead of re-listing it in another order? | judgment | no | plugin | +| dim-23 | Every guardrails hook fix pins its over-fire as a stay-quiet test case | docs/contracts/hook-precision/README.md#Conformance | judgment: for each hook under `plugins/guardrails/hooks/`, does its co-located test carry a stay-quiet case for each over-fire fix? (applies to `guardrails`) | judgment | no | plugin | +| dim-24 | No plugin states a pre-PR step order that conflicts with the canonical one | docs/contracts/pre-pr-ordering/README.md#Conformance | judgment: does any surface in this plugin list pre-PR steps, and if so does it cite the sequence instead of re-listing it in another order? | judgment | no | plugin | diff --git a/docs/conventions/enforcement-ladder/CHANGELOG.md b/docs/contracts/enforcement-ladder/CHANGELOG.md similarity index 100% rename from docs/conventions/enforcement-ladder/CHANGELOG.md rename to docs/contracts/enforcement-ladder/CHANGELOG.md diff --git a/docs/conventions/enforcement-ladder/README.md b/docs/contracts/enforcement-ladder/README.md similarity index 100% rename from docs/conventions/enforcement-ladder/README.md rename to docs/contracts/enforcement-ladder/README.md diff --git a/docs/conventions/hook-observability/README.md b/docs/contracts/hook-observability/README.md similarity index 100% rename from docs/conventions/hook-observability/README.md rename to docs/contracts/hook-observability/README.md diff --git a/docs/conventions/hook-precision/README.md b/docs/contracts/hook-precision/README.md similarity index 100% rename from docs/conventions/hook-precision/README.md rename to docs/contracts/hook-precision/README.md diff --git a/docs/conventions/hook-precision/guard-precision.md b/docs/contracts/hook-precision/guard-precision.md similarity index 100% rename from docs/conventions/hook-precision/guard-precision.md rename to docs/contracts/hook-precision/guard-precision.md diff --git a/docs/conventions/pr-scope-budget/README.md b/docs/contracts/pr-scope-budget/README.md similarity index 100% rename from docs/conventions/pr-scope-budget/README.md rename to docs/contracts/pr-scope-budget/README.md diff --git a/docs/conventions/pre-pr-ordering/README.md b/docs/contracts/pre-pr-ordering/README.md similarity index 100% rename from docs/conventions/pre-pr-ordering/README.md rename to docs/contracts/pre-pr-ordering/README.md diff --git a/docs/conventions/seam-phrasing/README.md b/docs/contracts/seam-phrasing/README.md similarity index 100% rename from docs/conventions/seam-phrasing/README.md rename to docs/contracts/seam-phrasing/README.md diff --git a/docs/conventions/standards/CHANGELOG.md b/docs/contracts/standards/CHANGELOG.md similarity index 100% rename from docs/conventions/standards/CHANGELOG.md rename to docs/contracts/standards/CHANGELOG.md diff --git a/docs/conventions/standards/README.md b/docs/contracts/standards/README.md similarity index 100% rename from docs/conventions/standards/README.md rename to docs/contracts/standards/README.md diff --git a/docs/conventions/standards/examples/worked-index.md b/docs/contracts/standards/examples/worked-index.md similarity index 100% rename from docs/conventions/standards/examples/worked-index.md rename to docs/contracts/standards/examples/worked-index.md diff --git a/docs/conventions/standards/standards.schema.json b/docs/contracts/standards/standards.schema.json similarity index 92% rename from docs/conventions/standards/standards.schema.json rename to docs/contracts/standards/standards.schema.json index bd690cca11..3c00fbb52e 100644 --- a/docs/conventions/standards/standards.schema.json +++ b/docs/contracts/standards/standards.schema.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/standards/standards.schema.json", + "$id": "https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/standards/standards.schema.json", "title": "Standards concern file (.claude/standards.yaml)", "description": "Consumer-side single source of truth for the standards convention. Every key is optional; absent keys mean the documented defaults.", "type": "object", diff --git a/plugins/architecture/skills/improve/research/enforcement-ladder.md b/plugins/architecture/skills/improve/research/enforcement-ladder.md index 25b8b7b020..71249993ab 100644 --- a/plugins/architecture/skills/improve/research/enforcement-ladder.md +++ b/plugins/architecture/skills/improve/research/enforcement-ladder.md @@ -2,7 +2,7 @@ enforcement-ladder: 2.0.0 --- - # Enforcement ladder diff --git a/plugins/code-tidying/reference/pr-scope-budget.md b/plugins/code-tidying/reference/pr-scope-budget.md index 7af79f229c..8f83fdafe6 100644 --- a/plugins/code-tidying/reference/pr-scope-budget.md +++ b/plugins/code-tidying/reference/pr-scope-budget.md @@ -1,4 +1,4 @@ - # PR scope budget: how big an agent-authored improvement PR may be diff --git a/plugins/corrections/skills/codify/reference/enforcement-ladder.md b/plugins/corrections/skills/codify/reference/enforcement-ladder.md index 25b8b7b020..71249993ab 100644 --- a/plugins/corrections/skills/codify/reference/enforcement-ladder.md +++ b/plugins/corrections/skills/codify/reference/enforcement-ladder.md @@ -2,7 +2,7 @@ enforcement-ladder: 2.0.0 --- - # Enforcement ladder diff --git a/plugins/coupling/reference/pr-scope-budget.md b/plugins/coupling/reference/pr-scope-budget.md index 7af79f229c..8f83fdafe6 100644 --- a/plugins/coupling/reference/pr-scope-budget.md +++ b/plugins/coupling/reference/pr-scope-budget.md @@ -1,4 +1,4 @@ - # PR scope budget: how big an agent-authored improvement PR may be diff --git a/plugins/harness-config/skills/audit-automation-gaps/context/enforcement-ladder.md b/plugins/harness-config/skills/audit-automation-gaps/context/enforcement-ladder.md index 25b8b7b020..71249993ab 100644 --- a/plugins/harness-config/skills/audit-automation-gaps/context/enforcement-ladder.md +++ b/plugins/harness-config/skills/audit-automation-gaps/context/enforcement-ladder.md @@ -2,7 +2,7 @@ enforcement-ladder: 2.0.0 --- - # Enforcement ladder diff --git a/plugins/improvement/reference/pr-scope-budget.md b/plugins/improvement/reference/pr-scope-budget.md index 7af79f229c..8f83fdafe6 100644 --- a/plugins/improvement/reference/pr-scope-budget.md +++ b/plugins/improvement/reference/pr-scope-budget.md @@ -1,4 +1,4 @@ - # PR scope budget: how big an agent-authored improvement PR may be diff --git a/plugins/improvement/reference/standards-contract.md b/plugins/improvement/reference/standards-contract.md index 4fe1a95cc9..31c8ea7185 100644 --- a/plugins/improvement/reference/standards-contract.md +++ b/plugins/improvement/reference/standards-contract.md @@ -2,7 +2,7 @@ standards-contract: 1.1.1 --- - # Standards Convention diff --git a/plugins/planning/reference/standards-contract.md b/plugins/planning/reference/standards-contract.md index 4fe1a95cc9..31c8ea7185 100644 --- a/plugins/planning/reference/standards-contract.md +++ b/plugins/planning/reference/standards-contract.md @@ -2,7 +2,7 @@ standards-contract: 1.1.1 --- - # Standards Convention diff --git a/plugins/review/context/enforcement-ladder.md b/plugins/review/context/enforcement-ladder.md index 25b8b7b020..71249993ab 100644 --- a/plugins/review/context/enforcement-ladder.md +++ b/plugins/review/context/enforcement-ladder.md @@ -2,7 +2,7 @@ enforcement-ladder: 2.0.0 --- - # Enforcement ladder diff --git a/plugins/review/reference/standards-contract.md b/plugins/review/reference/standards-contract.md index 4fe1a95cc9..31c8ea7185 100644 --- a/plugins/review/reference/standards-contract.md +++ b/plugins/review/reference/standards-contract.md @@ -2,7 +2,7 @@ standards-contract: 1.1.1 --- - # Standards Convention diff --git a/plugins/session-flow/skills/retro/reference/enforcement-ladder.md b/plugins/session-flow/skills/retro/reference/enforcement-ladder.md index 25b8b7b020..71249993ab 100644 --- a/plugins/session-flow/skills/retro/reference/enforcement-ladder.md +++ b/plugins/session-flow/skills/retro/reference/enforcement-ladder.md @@ -2,7 +2,7 @@ enforcement-ladder: 2.0.0 --- - # Enforcement ladder diff --git a/scripts/cross-plugin-source-registry.txt b/scripts/cross-plugin-source-registry.txt index 3f72d8d63f..48acdf9732 100644 --- a/scripts/cross-plugin-source-registry.txt +++ b/scripts/cross-plugin-source-registry.txt @@ -30,20 +30,20 @@ lib/rewrite-guard.sh -> plugins/*/hooks/rewrite-guard.sh reference/artifact-protocol.md # Dedicated check: scripts/sync-shared-copies.sh --check. Canonical: -# docs/conventions/standards/README.md. +# docs/contracts/standards/README.md. reference/standards-contract.md # Dedicated check: scripts/sync-shared-copies.sh --check. Cluster line for the # duplication audit: the canonical contract and the copies. -docs/conventions/standards/README.md -> plugins/*/reference/standards-contract.md +docs/contracts/standards/README.md -> plugins/*/reference/standards-contract.md # Dedicated check: scripts/sync-shared-copies.sh --check. Canonical: -# docs/conventions/pr-scope-budget/README.md. +# docs/contracts/pr-scope-budget/README.md. reference/pr-scope-budget.md # Dedicated check: scripts/sync-shared-copies.sh --check. Cluster line for the # duplication audit: the canonical convention and the copies. -docs/conventions/pr-scope-budget/README.md -> plugins/*/reference/pr-scope-budget.md +docs/contracts/pr-scope-budget/README.md -> plugins/*/reference/pr-scope-budget.md # Dedicated check: scripts/sync-shared-copies.sh --check. Canonical: # lib/managed-scope.sh. diff --git a/scripts/em-dash-purged-paths.txt b/scripts/em-dash-purged-paths.txt index 9a59611879..697e81de4a 100644 --- a/scripts/em-dash-purged-paths.txt +++ b/scripts/em-dash-purged-paths.txt @@ -69,13 +69,13 @@ docs/contracts/config-cascade/*.md docs/contracts/consumer-config-layering/*.md docs/contracts/detector-findings/*.md docs/contracts/ecosystem-commands/*.md -docs/conventions/enforcement-ladder/*.md +docs/contracts/enforcement-ladder/*.md docs/contracts/finding-suppression/*.md docs/contracts/hook-budget/*.md docs/contracts/hook-config-delivery/*.md docs/contracts/hook-input-rewriting/*.md -docs/conventions/hook-observability/*.md -docs/conventions/hook-precision/*.md +docs/contracts/hook-observability/*.md +docs/contracts/hook-precision/*.md docs/contracts/hook-telemetry/*.md docs/conventions/instruction-exception-register/*.md docs/contracts/invocation-mode/*.md @@ -86,13 +86,13 @@ docs/contracts/permission-rule-hygiene/*.md docs/contracts/plugin-data-report-keying/*.md docs/contracts/plugin-reconfiguration/*.md docs/contracts/pr-body-convention/*.md -docs/conventions/pre-pr-ordering/*.md +docs/contracts/pre-pr-ordering/*.md docs/conventions/rendered-views/*.md docs/contracts/retired-conventions/*.md -docs/conventions/seam-phrasing/*.md +docs/contracts/seam-phrasing/*.md docs/contracts/shell-test-helpers/*.md -docs/conventions/standards/*.md -docs/conventions/standards/examples/*.md +docs/contracts/standards/*.md +docs/contracts/standards/examples/*.md docs/contracts/tracker-reference-form/*.md docs/conventions/untrusted-content/*.md docs/contracts/upstream-drift/*.md diff --git a/scripts/shared-copies.txt b/scripts/shared-copies.txt index f5efeed44e..f14661a891 100644 --- a/scripts/shared-copies.txt +++ b/scripts/shared-copies.txt @@ -86,17 +86,17 @@ lib/docs-lookup-procedure.md plugins/session-flow/reference/docs-lookup-procedur lib/managed-scope.sh plugins/harness-config/lib/managed-scope.sh lib/managed-scope.sh plugins/harness-memory/lib/managed-scope.sh lib/managed-scope.sh plugins/harness-ops/lib/managed-scope.sh -docs/conventions/standards/README.md plugins/planning/reference/standards-contract.md -docs/conventions/standards/README.md plugins/review/reference/standards-contract.md -docs/conventions/enforcement-ladder/README.md plugins/review/context/enforcement-ladder.md -docs/conventions/enforcement-ladder/README.md plugins/session-flow/skills/retro/reference/enforcement-ladder.md -docs/conventions/enforcement-ladder/README.md plugins/harness-config/skills/audit-automation-gaps/context/enforcement-ladder.md -docs/conventions/enforcement-ladder/README.md plugins/architecture/skills/improve/research/enforcement-ladder.md -docs/conventions/enforcement-ladder/README.md plugins/corrections/skills/codify/reference/enforcement-ladder.md -docs/conventions/standards/README.md plugins/improvement/reference/standards-contract.md -docs/conventions/pr-scope-budget/README.md plugins/improvement/reference/pr-scope-budget.md -docs/conventions/pr-scope-budget/README.md plugins/code-tidying/reference/pr-scope-budget.md -docs/conventions/pr-scope-budget/README.md plugins/coupling/reference/pr-scope-budget.md +docs/contracts/standards/README.md plugins/planning/reference/standards-contract.md +docs/contracts/standards/README.md plugins/review/reference/standards-contract.md +docs/contracts/enforcement-ladder/README.md plugins/review/context/enforcement-ladder.md +docs/contracts/enforcement-ladder/README.md plugins/session-flow/skills/retro/reference/enforcement-ladder.md +docs/contracts/enforcement-ladder/README.md plugins/harness-config/skills/audit-automation-gaps/context/enforcement-ladder.md +docs/contracts/enforcement-ladder/README.md plugins/architecture/skills/improve/research/enforcement-ladder.md +docs/contracts/enforcement-ladder/README.md plugins/corrections/skills/codify/reference/enforcement-ladder.md +docs/contracts/standards/README.md plugins/improvement/reference/standards-contract.md +docs/contracts/pr-scope-budget/README.md plugins/improvement/reference/pr-scope-budget.md +docs/contracts/pr-scope-budget/README.md plugins/code-tidying/reference/pr-scope-budget.md +docs/contracts/pr-scope-budget/README.md plugins/coupling/reference/pr-scope-budget.md lib/resolve-convention-home.sh plugins/harness-config/lib/resolve-convention-home.sh lib/resolve-convention-home.sh plugins/plugin-quality/lib/resolve-convention-home.sh lib/resolve-convention-home.sh plugins/architecture/lib/resolve-convention-home.sh