diff --git a/docs/CLOUD-SESSIONS.md b/docs/CLOUD-SESSIONS.md index cb6af5cd6..d50593a6d 100644 --- a/docs/CLOUD-SESSIONS.md +++ b/docs/CLOUD-SESSIONS.md @@ -9,6 +9,12 @@ other pages were last verified 2026-07-30. Per the [upstream-drift convention](conventions/upstream-drift/README.md), re-fetch a page before acting on it. +## Contents + +- [What this is](#what-this-is) +- [Set up your own (any account, machine, or repo)](#set-up-your-own-any-account-machine-or-repo) +- [How this repository is set up](#how-this-repository-is-set-up) + ## What this is - [Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web) runs each diff --git a/docs/conventions/topic-docs/README.md b/docs/conventions/topic-docs/README.md index 3233cb0a3..7b89ea0a4 100644 --- a/docs/conventions/topic-docs/README.md +++ b/docs/conventions/topic-docs/README.md @@ -23,8 +23,10 @@ content out of the working directory when it outgrows the task. This directory is the source of truth: this README (tiers, resolution order, slug spec, lifecycle), `topic-docs.schema.json` (the tracked -concern file's shape), `CHANGELOG.md` (version history), `examples/` -(one worked slice). +concern file's shape), `CHANGELOG.md` (version history), +[examples/worked-slice.md](examples/worked-slice.md) (read for one topic +slice from birth to graduation, when the lifecycle rules need a concrete +instance). ## Why this exists diff --git a/docs/topics/ai-adoption-ladder/design/design-threads.md b/docs/topics/ai-adoption-ladder/design/design-threads.md index 2f62e2317..ca51bb1dd 100644 --- a/docs/topics/ai-adoption-ladder/design/design-threads.md +++ b/docs/topics/ai-adoption-ladder/design/design-threads.md @@ -1,5 +1,15 @@ # Design threads — ai-adoption-ladder +## Contents + +- [T1: Autonomous-kickoff trigger layer (#240) — RESOLVED 2026-07-17](#t1-autonomous-kickoff-trigger-layer-240--resolved-2026-07-17) +- [T2: Runtime sandbox bar for autonomy (#245) — RESOLVED 2026-07-17](#t2-runtime-sandbox-bar-for-autonomy-245--resolved-2026-07-17) +- [T3: Per-work-class guardrail matrix (#243) — RESOLVED 2026-07-17](#t3-per-work-class-guardrail-matrix-243--resolved-2026-07-17) +- [T4: Autonomous-runner charter (#244) — RESOLVED 2026-07-17](#t4-autonomous-runner-charter-244--resolved-2026-07-17) +- [T5: Return accounting (#246) — RESOLVED 2026-07-17](#t5-return-accounting-246--resolved-2026-07-17) +- [T6: Telemetry unification (#247) — RESOLVED 2026-07-17](#t6-telemetry-unification-247--resolved-2026-07-17) +- [T7: Standing scheduled routines (#242) — RESOLVED 2026-07-17](#t7-standing-scheduled-routines-242--resolved-2026-07-17) + ## T1: Autonomous-kickoff trigger layer (#240) — RESOLVED 2026-07-17 Decision: the trigger layer is a CONTRACT, not a place — thin per-source signal adapters, each diff --git a/docs/topics/autonomy-ignition/PLAN.md b/docs/topics/autonomy-ignition/PLAN.md index 3ddc199e6..729aeebb5 100644 --- a/docs/topics/autonomy-ignition/PLAN.md +++ b/docs/topics/autonomy-ignition/PLAN.md @@ -4,6 +4,15 @@ Sub-topic of `docs/topics/ladder-climb-roadmap/PLAN.md` Phase I (on `main` since Design record: interview rulings (ledger committed in the roadmap topic) + `design/design-resolution.md`. +## Contents + +- [Brief](#brief) +- [Plan](#plan) +- [Blast radius](#blast-radius) +- [Stress-test summary](#stress-test-summary) +- [Execution shape](#execution-shape) +- [Handoff to implementation](#handoff-to-implementation) + ## Brief Ignite the 2→3 loop: the first standing routine (C2 drain — hourly at ignition, re-bound diff --git a/docs/topics/context-engineering-claude-5/PLAN.md b/docs/topics/context-engineering-claude-5/PLAN.md index 6785976ae..ac55023a7 100644 --- a/docs/topics/context-engineering-claude-5/PLAN.md +++ b/docs/topics/context-engineering-claude-5/PLAN.md @@ -1,5 +1,42 @@ # Context engineering for Claude 5 — source absorption and rightsizing pass +## Contents + +- [Brief](#brief) + - [TLDR](#tldr) + - [The design documents](#the-design-documents) + - [Goal](#goal) + - [Settled](#settled) + - [Coordination](#coordination) + - [Constraints](#constraints) + - [Shape — decided](#shape--decided) + - [Open](#open) + - [Acceptance criteria](#acceptance-criteria) +- [Plan](#plan) + - [Standards grounding](#standards-grounding) + - [Phase 1: Finish the fresh-docs sweep [DONE]](#phase-1-finish-the-fresh-docs-sweep-done) + - [Phase 2: Resolve the cross-plugin criteria seam [DONE]](#phase-2-resolve-the-cross-plugin-criteria-seam-done) + - [Phase 2.5: Proportionality gate — which detectors survive [DONE]](#phase-25-proportionality-gate--which-detectors-survive-done) + - [Phase 3: Specify the criteria edits [SPECIFIED — execution moves to Phase 8]](#phase-3-specify-the-criteria-edits-specified--execution-moves-to-phase-8) + - [Phase 4: Define the re-run contract [DONE]](#phase-4-define-the-re-run-contract-done) + - [Phase 5: Map each check to its owning plugin [DONE]](#phase-5-map-each-check-to-its-owning-plugin-done) + - [Phase 6: Design the detectors and the sweep [PARTIALLY SHIPPED]](#phase-6-design-the-detectors-and-the-sweep-partially-shipped--run-contract--suppression-landed-in-audit-pass-detector-catalog-still-open) + - [Gate — re-evaluate before implementation [TODO]](#gate--re-evaluate-before-implementation-todo) + - [Phase 7: Bring the setup-skill corpus to its owner doc [AUDITED]](#phase-7-bring-the-setup-skill-corpus-to-its-owner-doc-audited) + - [Phase 8: Implement the checks in their owning plugins [PARTIALLY SHIPPED]](#phase-8-implement-the-checks-in-their-owning-plugins-partially-shipped--audit-pass-run-contract-shipped-per-check-detectors-still-open) + - [Phase 9: Implement the sweep [PARTIALLY SHIPPED]](#phase-9-implement-the-sweep-partially-shipped--audit-pass-skill--run-contract-shipped-cross-plugin-sweep-wiring-still-open) + - [Phase 10: Reconcile, then run against this repository [TODO]](#phase-10-reconcile-then-run-against-this-repository-todo) + - [Phase 11: Acceptance gate and PR [TODO]](#phase-11-acceptance-gate-and-pr-todo) +- [Test strategy](#test-strategy) +- [Alternatives considered](#alternatives-considered) +- [Risks and mitigations](#risks-and-mitigations) +- [Blast radius](#blast-radius) +- [Open questions](#open-questions) +- [Handoff to implementation](#handoff-to-implementation) + - [User-approval gates](#user-approval-gates) + - [Execution shape](#execution-shape) + - [Mechanical work](#mechanical-work) + ## Brief Status: **in progress** — shape decided (a component, not a runbook), seam resolved, proportionality diff --git a/docs/topics/context-engineering-claude-5/design/checks-and-sweep.md b/docs/topics/context-engineering-claude-5/design/checks-and-sweep.md index 5e50d09b5..34d70b76c 100644 --- a/docs/topics/context-engineering-claude-5/design/checks-and-sweep.md +++ b/docs/topics/context-engineering-claude-5/design/checks-and-sweep.md @@ -10,6 +10,39 @@ Tasks #19 and #22–#27 (two new checks and four edits to existing ones, per the and #28 (the sweep). **The sweep is named `audit-pass`**, invoked as `/claude-config:audit-pass` — see "Naming, resolved" below for what that choice paid. +## Contents + +- [D1 — cross-surface instruction conflict](#d1--cross-surface-instruction-conflict) + - [D1 wears the tier label without the delete-and-watch loop, and that is deliberate](#d1-wears-the-tier-label-without-the-delete-and-watch-loop-and-that-is-deliberate) + - [Detect](#detect) + - [`AGENTS.md` is affirmatively excluded](#agentsmd-is-affirmatively-excluded) + - [D1 reads the expanded surface, not the file on disk](#d1-reads-the-expanded-surface-not-the-file-on-disk) + - [Type B ships, and does not ship without the allowlist](#type-b-ships-and-does-not-ship-without-the-allowlist) + - [Must NOT flag](#must-not-flag) + - [Remediate](#remediate) + - [Source](#source) + - [An incumbent exists after all, and D1 is scoped around it](#an-incumbent-exists-after-all-and-d1-is-scoped-around-it) + - [The inventory D1 depends on, and the native-first gate](#the-inventory-d1-depends-on-and-the-native-first-gate) +- [The other checks](#the-other-checks) +- [The sweep](#the-sweep) + - [Why it is a component and not a runbook](#why-it-is-a-component-and-not-a-runbook) + - [Posture](#posture) + - [The exclusion set is derived, never hardcoded](#the-exclusion-set-is-derived-never-hardcoded) + - [`/doctor` — prerequisite contract, not a hand-wave](#doctor--prerequisite-contract-not-a-hand-wave) + - [Dispatch](#dispatch) + - [Coverage disclosure — `OPINION` and `/doctor`](#coverage-disclosure--opinion-and-doctor) + - [Verification is designed in, not left to the invoker](#verification-is-designed-in-not-left-to-the-invoker) + - [D6 needs a synthetic fixture](#d6-needs-a-synthetic-fixture) +- [The report and the lanes](#the-report-and-the-lanes) +- [Threat model — prompt injection against the sweep](#threat-model--prompt-injection-against-the-sweep) + - [Sources](#sources) + - [T1 — instruction text that targets the auditor, not the model under audit](#t1--instruction-text-that-targets-the-auditor-not-the-model-under-audit) + - [T2 — the suppression record as an attack surface](#t2--the-suppression-record-as-an-attack-surface) + - [T3 — what the human gate can and cannot catch](#t3--what-the-human-gate-can-and-cannot-catch) + - [What this section newly constrains, and who owns it](#what-this-section-newly-constrains-and-who-owns-it) + - [What this section does not settle](#what-this-section-does-not-settle) +- [Open in this phase](#open-in-this-phase) + ## D1 — cross-surface instruction conflict The deliverable's entire officially-backed payload. It ships as check **I12** in diff --git a/docs/topics/context-engineering-claude-5/design/official-corroboration.md b/docs/topics/context-engineering-claude-5/design/official-corroboration.md index 2aaebed6b..6a733417e 100644 --- a/docs/topics/context-engineering-claude-5/design/official-corroboration.md +++ b/docs/topics/context-engineering-claude-5/design/official-corroboration.md @@ -6,6 +6,15 @@ reference documentation. Every rule it states is checked here against official d Where no doc confirms it, the rule is `OPINION`-tier under the authority axis already defined in `claude-config/skills/audit-instructions/reference/criteria.md`. +## Contents + +- [The authority axis, written out](#the-authority-axis-written-out) +- [Official material the source omits, relevant to this work](#official-material-the-source-omits-relevant-to-this-work) +- [Phase 1 sweep — what the eleven pages settled](#phase-1-sweep--what-the-eleven-pages-settled) +- [Path scoping — verified empirically, not just read](#path-scoping--verified-empirically-not-just-read) +- [Pages the plan's list missed](#pages-the-plans-list-missed) +- [`llms.txt` walk — falsifiability check](#llmstxt-walk--falsifiability-check) + Pages fetched this session: - — `/doctor` diff --git a/docs/topics/context-engineering-claude-5/design/proportionality-gate.md b/docs/topics/context-engineering-claude-5/design/proportionality-gate.md index 28679cdd0..6e38db32b 100644 --- a/docs/topics/context-engineering-claude-5/design/proportionality-gate.md +++ b/docs/topics/context-engineering-claude-5/design/proportionality-gate.md @@ -6,6 +6,26 @@ date: 2026-07-24 # Phase 2.5 — proportionality gate on D1–D7 +## Contents + +- [The test](#the-test) +- [Dispositions](#dispositions) + - [D5's trigger, split in two](#d5s-trigger-split-in-two) +- [Escalation](#escalation) + - [Re-derived shape](#re-derived-shape) + - [Ground-truth verification independently strengthened this](#ground-truth-verification-independently-strengthened-this) + - [Reconciling with the Brief's one-anchored-source criterion](#reconciling-with-the-briefs-one-anchored-source-criterion) +- [Homing map — Phase 5, folded in](#homing-map--phase-5-folded-in) + - [The determinism contract, re-verified against check 21](#the-determinism-contract-re-verified-against-check-21) +- [`OPINION`-tier policy](#opinion-tier-policy) +- [D1 scope questions, answered](#d1-scope-questions-answered) + - [D1's detection rule is narrower than "two instructions differ"](#d1s-detection-rule-is-narrower-than-two-instructions-differ) +- [Corrections this gate forces on upstream documents](#corrections-this-gate-forces-on-upstream-documents) +- [The design tier, actually re-derived](#the-design-tier-actually-re-derived) +- [Deferred tool loading — a remainder that is not D6's](#deferred-tool-loading--a-remainder-that-is-not-d6s) +- [What this gate does not decide](#what-this-gate-does-not-decide) +- [Independent verification](#independent-verification) + The record PLAN.md's Phase 2.5 sanity checks assert against. It carries every detector's disposition with its reason, the escalation verdict, the operator's decision on that escalation, the `OPINION`-tier policy, the D1 scope answers the corroboration document parked here, and the homing diff --git a/docs/topics/context-engineering-claude-5/design/rerun-contract.md b/docs/topics/context-engineering-claude-5/design/rerun-contract.md index 5115ac6c8..d3e3bb06c 100644 --- a/docs/topics/context-engineering-claude-5/design/rerun-contract.md +++ b/docs/topics/context-engineering-claude-5/design/rerun-contract.md @@ -6,6 +6,27 @@ date: 2026-07-24 # Phase 4 — the re-run contract +## Contents + +- [1. Finding identity](#1-finding-identity) + - [`surface` — the physical file, never the loading entry point](#surface--the-physical-file-never-the-loading-entry-point) + - [`anchor` — content-derived, versioned, and granularity-tagged](#anchor--content-derived-versioned-and-granularity-tagged) + - [Excerpt extraction, per surface class](#excerpt-extraction-per-surface-class) + - [Registered cluster copies canonicalize before identity](#registered-cluster-copies-canonicalize-before-identity) + - [`finding_id`, and why the truncations are what they are](#finding_id-and-why-the-truncations-are-what-they-are) + - [Assertions](#assertions) + - [Borrowed vocabulary, and two deliberate divergences](#borrowed-vocabulary-and-two-deliberate-divergences) + - [Matching across runs — the tiered table](#matching-across-runs--the-tiered-table) +- [2. Where the report lives](#2-where-the-report-lives) +- [3. Run state, keying, and concurrency](#3-run-state-keying-and-concurrency) +- [4. Suppression, per target class](#4-suppression-per-target-class) +- [5. Mid-run resumability](#5-mid-run-resumability) +- [6. The idempotence properties](#6-the-idempotence-properties) + - [The tiers had to be re-derived first — the two-tier split did not survive contact](#the-tiers-had-to-be-re-derived-first--the-two-tier-split-did-not-survive-contact) + - [Inputs to the derived tier that are not the tree](#inputs-to-the-derived-tier-that-are-not-the-tree) + - [The properties](#the-properties) +- [Sanity check](#sanity-check) + Task #35. Idempotence is the Brief's headline acceptance criterion, and after the proportionality gate it carries more weight than it did: the argument for the sweep existing at all is that *the checks are delegated but the run semantics are not*. If this document lands as prose intent, that diff --git a/docs/topics/fable-field-guide-audit/dispositions.md b/docs/topics/fable-field-guide-audit/dispositions.md index 76301bc7f..ecdf751b1 100644 --- a/docs/topics/fable-field-guide-audit/dispositions.md +++ b/docs/topics/fable-field-guide-audit/dispositions.md @@ -6,6 +6,45 @@ under `plugins/playbooks/skills/fable-5/**` was edited; the repo is on `main` wi Written in a clean context deliberately. Where this document contradicts a ledger, the contradiction is stated in §4 with the evidence, not merged away. +## Contents + +- [1. How to read this](#1-how-to-read-this) +- [2. The four dedup calls](#2-the-four-dedup-calls) + - [Judgment 1 — S2 Q4b, S5 C4, S13 F1](#judgment-1--s2-q4b-s5-c4-s13-f1-one-root-cause-and-the-ledgers-put-it-in-the-wrong-cell) + - [Judgment 2 — S2 Q2, S5 C8, S7 C6](#judgment-2--s2-q2-s5-c8-s7-c6-s7s-one-missing-mechanism-is-refuted-by-s7s-own-body) + - [Judgment 3 — S11 Claim 3 and S13 F4](#judgment-3--s11-claim-3-and-s13-f4-neither-of-s11s-landings-hosts-f4-and-f4-does-not-need-one) + - [Judgment 4 — S14 C14.5a](#judgment-4--s14-c145a-independent-and-a-prerequisite-for-the-rest) +- [3. Three decisions the operator owns](#3-three-decisions-the-operator-owns) + - [D1 — The `problem-framing.md:60` trigger](#d1--the-problem-framingmd60-trigger) + - [D2 — `context/opus-adaptation.md`](#d2--contextopus-adaptationmd) + - [D3 — The contradictions against the divergent-spread tactic (S6 C4)](#d3--the-contradictions-against-the-divergent-spread-tactic-s6-c4) + - [D4 — Scope-setting pass as an opener (S6 C5)](#d4--scope-setting-pass-as-an-opener-s6-c5) +- [4. Corrections to the ledgers](#4-corrections-to-the-ledgers) +- [5. The remediation set](#5-the-remediation-set) + - [Tier 0 — prerequisite](#tier-0--prerequisite) + - [Tier 1 — the operator-evaluability cluster](#tier-1--the-operator-evaluability-cluster) + - [Tier 2 — the show-moves](#tier-2--the-show-moves) + - [Tier 3 — independent, single-home](#tier-3--independent-single-home) + - [Tier 4 — low priority](#tier-4--low-priority) +- [6. The claim ledger](#6-the-claim-ledger) + - [S1 — map and territory](#s1--map-and-territory) + - [S2 — the four quadrants](#s2--the-four-quadrants) + - [S3 — unknown-reduction is the skill](#s3--unknown-reduction-is-the-skill) + - [S4 — specificity balance, discovery accelerator, starting point](#s4--specificity-balance-discovery-accelerator-starting-point) + - [S5 — blind spot pass](#s5--blind-spot-pass) + - [S6 — brainstorms and prototypes](#s6--brainstorms-and-prototypes) + - [S7 — interviews](#s7--interviews) + - [S8 — references](#s8--references) + - [S9 — implementation plans](#s9--implementation-plans) + - [S10 — fresh session and implementation notes](#s10--fresh-session-and-implementation-notes) + - [S11 — pitches and explainers](#s11--pitches-and-explainers) + - [S12 — quizzes](#s12--quizzes) + - [S13 — the launch-video worked example](#s13--the-launch-video-worked-example) + - [S14 — closing claims](#s14--closing-claims) +- [7. Audit-originated findings — not article-derived](#7-audit-originated-findings--not-article-derived) +- [8. Remediations rejected on constraint grounds](#8-remediations-rejected-on-constraint-grounds) +- [9. Sequencing, if any of this is adopted](#9-sequencing-if-any-of-this-is-adopted) + ## 1. How to read this **Verdict** (per the brief): `covered` / `partial` / `missing` / `contradicted` / diff --git a/docs/topics/fresh-eyes-checkpoint-audit/PLAN.md b/docs/topics/fresh-eyes-checkpoint-audit/PLAN.md index ec51821cc..3f6a956b4 100644 --- a/docs/topics/fresh-eyes-checkpoint-audit/PLAN.md +++ b/docs/topics/fresh-eyes-checkpoint-audit/PLAN.md @@ -1,5 +1,15 @@ # fresh-eyes-checkpoint-audit +## Contents + +- [Brief](#brief) +- [Plan](#plan) +- [Blast radius](#blast-radius) +- [Stress-test summary](#stress-test-summary) +- [Execution shape](#execution-shape) +- [Open questions](#open-questions) +- [Handoff to implementation](#handoff-to-implementation) + ## Brief ### TLDR diff --git a/docs/topics/ladder-climb-roadmap/PLAN.md b/docs/topics/ladder-climb-roadmap/PLAN.md index 29c9875ef..7842226e4 100644 --- a/docs/topics/ladder-climb-roadmap/PLAN.md +++ b/docs/topics/ladder-climb-roadmap/PLAN.md @@ -1,5 +1,15 @@ # ladder-climb-roadmap — PLAN +## Contents + +- [Brief](#brief) +- [Plan](#plan) +- [Blast radius](#blast-radius) +- [Stress-test summary](#stress-test-summary) +- [Execution shape](#execution-shape) +- [Open questions](#open-questions) +- [Handoff to implementation](#handoff-to-implementation) + ## Brief Interview complete (25/25 resolved, verification-backed — ledger committed alongside this plan: diff --git a/docs/topics/loop-engineering-codification/PLAN.md b/docs/topics/loop-engineering-codification/PLAN.md index 73f408fc5..155c01986 100644 --- a/docs/topics/loop-engineering-codification/PLAN.md +++ b/docs/topics/loop-engineering-codification/PLAN.md @@ -1,5 +1,10 @@ # PLAN — loop-engineering-codification +## Contents + +- [Brief](#brief) +- [Plan](#plan) + ## Brief ### TLDR diff --git a/docs/topics/plugin-audit-port/PLAN.md b/docs/topics/plugin-audit-port/PLAN.md index a8bb0a9c4..7e4446652 100644 --- a/docs/topics/plugin-audit-port/PLAN.md +++ b/docs/topics/plugin-audit-port/PLAN.md @@ -1,5 +1,16 @@ # plugin-audit-port +## Contents + +- [Brief](#brief) +- [Plan](#plan) +- [Blast radius](#blast-radius) +- [Stress-test summary](#stress-test-summary) +- [Execution shape](#execution-shape) +- [Decisions made (gate-passed)](#decisions-made-gate-passed) +- [Open questions](#open-questions) +- [Handoff to implementation](#handoff-to-implementation) + ## Brief ### TLDR diff --git a/plugins/autonomy/.claude-plugin/plugin.json b/plugins/autonomy/.claude-plugin/plugin.json index 60a2d559f..be3aeeedb 100644 --- a/plugins/autonomy/.claude-plugin/plugin.json +++ b/plugins/autonomy/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "autonomy", - "version": "0.22.13", + "version": "0.22.14", "description": "Governed autonomous agent operation: role-topology, binding-seam, wiring-vs-advisor, telemetry, return-accounting, trigger-dispatch, per-work-class guardrail-matrix, standing-routine-catalog, and design-only runner-charter contracts for climbing the AI-adoption ladder, plus a guided-setup skill that discovers an adopting org's state, writes its schema-versioned binding, wires standards-pinned OTLP emission with a zero-cost file-artifact default, wires human-attested return capture at the task boundary, wires signal adapters with one governed dispatch entrypoint, binds the five-class guardrail matrix to an org's isolation substrates with an in-boundary live-validation probe before recording each fail-closed binding, and stands up standing-routine-catalog classes as scheduled temporal signal adapters behind the one governed queue with free scheduling defaults wired as reviewable changes and each routine's work-class mapping homed on the security surface.", "author": { "name": "Melodic Software", diff --git a/plugins/autonomy/CHANGELOG.md b/plugins/autonomy/CHANGELOG.md index 309f8b8aa..39108e3bd 100644 --- a/plugins/autonomy/CHANGELOG.md +++ b/plugins/autonomy/CHANGELOG.md @@ -3,6 +3,18 @@ All notable changes to the `autonomy` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.22.14] + +### Changed + +- **`setup`'s hub reaches every required leaf directly.** The five template files its context + slices depend on (return-capture, isolation-probe, routine-definitions, trigger-adapters, + ack-reply) and the guardrails admission-policy/work-classes and runner lifecycle/topology leaves + gained direct conditioned pointers; the `reference/guardrails.md` and `reference/routines.md` + pointers now name those files as the indexes they are; the bare slice and template citations + were standardized to the "when `apply` reaches" conditioned form the other slices already used. + Behavior unchanged. Progressive-disclosure audit, deep-nesting and blind-pointer treatments. + ## [0.22.13] ### Changed diff --git a/plugins/autonomy/skills/setup/SKILL.md b/plugins/autonomy/skills/setup/SKILL.md index 7e9766e7d..eae65ff97 100644 --- a/plugins/autonomy/skills/setup/SKILL.md +++ b/plugins/autonomy/skills/setup/SKILL.md @@ -95,9 +95,9 @@ paid sinks are advisory + explicit opt-in with cost surfaced first. pointing at the org's endpoint. Paid/hosted stack → advisory with cost surfaced before any opt-in. 2. **No stack → the file-artifact free default** (zero paid dependencies): - - CI pipeline spans via the OTLP JSON-lines writer snippet in - [`templates/ci-otlp-artifact.md`](templates/ci-otlp-artifact.md), uploading the artifact - directory per run; + - CI pipeline spans via the OTLP JSON-lines writer snippet. Read + [`templates/ci-otlp-artifact.md`](templates/ci-otlp-artifact.md) when `apply` reaches this + step for the snippet, uploading the artifact directory per run; - agent-session signals via the ephemeral per-job collector in the same template (single static OSS collector binary + file-exporter config writing JSON-lines into the same artifact directory. Per-job, no standing infrastructure); @@ -128,12 +128,15 @@ paid sinks are advisory + explicit opt-in with cost surfaced first. Wires the capture-enabled state of [`${CLAUDE_PLUGIN_ROOT}/reference/return-accounting.md`](${CLAUDE_PLUGIN_ROOT}/reference/return-accounting.md), discovery-first: detect the tracker class and close-flow surface, WIRE the close- and -reply-triggered attestation handlers where machine-editable (the marker-keyed comment floor, or -provenance-verifiable native fields), ADVISE where GUI-only or entitlement-gated, and record the -`capture` section of the repo-local autonomy binding. The autonomous-class capture gate, the -record-integrity rule, the attestation-routing rule, and every serialized `capture` key are -specified in [`context/capture-slice.md`](context/capture-slice.md). Agents prompt and aggregate; -they never estimate the two human-attested return fields. +reply-triggered attestation handlers via the close-triggered snippet in +[`templates/return-capture.md`](templates/return-capture.md) where machine-editable (the +marker-keyed comment floor, or provenance-verifiable native fields), ADVISE where GUI-only or +entitlement-gated, and record the +`capture` section of the repo-local autonomy binding. Read +[`context/capture-slice.md`](context/capture-slice.md) when `apply` reaches the capture slice: it +owns the autonomous-class capture gate, the record-integrity rule, the attestation-routing rule, +and every serialized `capture` key. Agents prompt and aggregate; they never estimate the two +human-attested return fields. ## Trigger/dispatch slice @@ -143,10 +146,13 @@ discovery-first: discover the four signal-surface classes and their transports, (event kick + scheduled drain) as reviewable changes through the one queue-drain entrypoint, advise plan-gated integrations, and record the `triggers` section (the `surfaces` map + drain cadence) of the repo-local autonomy binding. Vendor event names and invocation flags live in this slice's -templates, never the contract. The per-surface adapter obligations, the execution-surface -attestation caveat, the admission fail-closed rule, every serialized `triggers` key, and the -[`scripts/check-signal-envelope.mjs`](scripts/check-signal-envelope.mjs) conformance step are -specified in [`context/trigger-dispatch-slice.md`](context/trigger-dispatch-slice.md). +[`templates/trigger-adapters.md`](templates/trigger-adapters.md) (adapter shapes) and +[`templates/ack-reply.md`](templates/ack-reply.md) (acknowledgment shape), never the contract. +Read [`context/trigger-dispatch-slice.md`](context/trigger-dispatch-slice.md) when `apply` +reaches the trigger/dispatch slice: it owns the per-surface adapter obligations, the +execution-surface attestation caveat, the admission fail-closed rule, every serialized `triggers` +key, and the [`scripts/check-signal-envelope.mjs`](scripts/check-signal-envelope.mjs) conformance +step. ## Guardrail binding resolution @@ -166,9 +172,15 @@ contract-owned and ships at document (schema shape + the semantic rules the schema cannot express) and, with `--evidence`, resolves each promotion cell's EFFECTIVE state against a promotion-evidence source, the bound state is a ceiling contrary evidence lowers without writing the -binding. Non-security axes remap in the additive `guardrails` section of the repo-local -binding: class→label strings (which local label means which work class) and -cost-tier→model names. Vocabulary remaps only, never policy content. +binding. Read the +[admission-policy leaf](${CLAUDE_PLUGIN_ROOT}/reference/guardrails/admission-policy.md) directly +when binding admission rules and caps: it owns the decision table, the wildcard precedence rule, +and the `override_justification` floor those caps enforce. Non-security axes remap in the +additive `guardrails` section of the repo-local binding: class→label strings (which local label +means which work class; read the +[work-classes leaf](${CLAUDE_PLUGIN_ROOT}/reference/guardrails/work-classes.md) directly when +resolving what a label maps to; it owns the risk-property bundles and promotion discipline behind +each class) and cost-tier→model names. Vocabulary remaps only, never policy content. **A third home that is not a governance surface.** Two axes of the [verification-topology leaf](${CLAUDE_PLUGIN_ROOT}/reference/guardrails/verification-topology.md) @@ -207,32 +219,38 @@ no security axis ever resolves from a documented default or a repo-local surface ## Guardrail slice -Wires the enforced state of the [guardrail contract](${CLAUDE_PLUGIN_ROOT}/reference/guardrails.md): -detect, bind, live-validate, fail-closed, always detect-diff-reconciling against the org's EXISTING +Wires the enforced state of the [guardrail contract](${CLAUDE_PLUGIN_ROOT}/reference/guardrails.md) +(open it, then the `guardrails/.md` it routes to, for whatever axis is in question): detect, +bind, live-validate, fail-closed, always detect-diff-reconciling against the org's EXISTING guardrail surfaces. The [resolution section above](#guardrail-binding-resolution) owns how bound policy resolves; this slice is the action that produces the security binding it resolves. Read [`context/guardrail-slice.md`](context/guardrail-slice.md) when `apply` reaches the guardrail -slice: it owns the per-layer wiring, the isolation-ladder probe, the security-binding schema and +slice: it owns the per-layer wiring, the isolation-ladder probe (recipe in +[`templates/isolation-probe.md`](templates/isolation-probe.md)), the security-binding schema and its validator, and the paid-SKU opt-in surface. The slice is argument-selected, so a run that does not select it never needs the file. ## Routine slice Wires the standing-routine state of the -[routine catalog](${CLAUDE_PLUGIN_ROOT}/reference/routines.md): a routine is a scheduled +[routine catalog](${CLAUDE_PLUGIN_ROOT}/reference/routines.md) (read it to pick a routine; each +recipe is a leaf under `routines/`): a routine is a scheduled `temporal`-class signal adapter behind the governed queue, never a private execution or merge path. Like the [guardrail slice](#guardrail-slice) it PREPARES the security surface and never writes it. Read [`context/routine-slice.md`](context/routine-slice.md) when `apply` reaches the routine slice: it owns the discovery-first reconciliation against the org's existing schedulers and bots, the -routine-definitions template, the CI-cron handler shape, and the signal-envelope verification. The -slice is argument-selected, so a run that does not select it never needs the file. +[`templates/routine-definitions.md`](templates/routine-definitions.md) template, the CI-cron +handler shape, and the signal-envelope verification. The slice is argument-selected, so a run +that does not select it never needs the file. ## Prerequisite-resolution slice Extends this skill per its own extension model for [routine prerequisite resolution](${CLAUDE_PLUGIN_ROOT}/reference/prerequisite-resolution.md). -Detail lives in -[`context/prerequisite-resolution-slice.md`](context/prerequisite-resolution-slice.md). +Read +[`context/prerequisite-resolution-slice.md`](context/prerequisite-resolution-slice.md) when +`apply` reaches the prerequisite-resolution slice: it owns the binding-section JSON shape and +the wrapper scripts' non-interactive flags. **Liveness.** The slice `check` is an engine health-check surface: it invokes [`scripts/resolve-prerequisites.mjs`](scripts/resolve-prerequisites.mjs) end-to-end and @@ -268,7 +286,14 @@ options through the security binding's `escalation_severity`, `escalation_severi security axis, never repo-local. The route set, its two-step severity resolution, and the per-class default severities are specified by the [runner escalation leaf](${CLAUDE_PLUGIN_ROOT}/reference/runner/escalation.md); this note points -there rather than restating them. +there rather than restating them. The full lifecycle state model and each transition's telemetry +are specified by the +[runner lifecycle leaf](${CLAUDE_PLUGIN_ROOT}/reference/runner/lifecycle.md); read it directly +when tracing how a leased item moves through its states, since this note does not restate the +state machine. The ownership-seam map assigning each part of the runner to its owning home is +specified by the [runner topology leaf](${CLAUDE_PLUGIN_ROOT}/reference/runner/topology.md); read +it directly when placing a runner obligation on its home, since this note does not re-derive the +split. ## Gotchas diff --git a/plugins/claude-config/.claude-plugin/plugin.json b/plugins/claude-config/.claude-plugin/plugin.json index c15682f6d..5c2299c58 100644 --- a/plugins/claude-config/.claude-plugin/plugin.json +++ b/plugins/claude-config/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "claude-config", - "version": "0.40.10", + "version": "0.40.11", "description": "Nine configuration-health skills (plus setup) for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), audit-permission-state (the permission rules actually in effect \u2014 every settings scope merged with per-rule provenance, what auto mode drops on entry, config written where nothing reads it, and which managed intents are enforced versus loosenable), draft-auto-mode-rules (interview and draft a paste-ready autoMode classifier block; prints only, never writes), audit-instructions (locally-owned instruction surfaces vs current model capability \u2014 proposes removals/rewrites of instructions the model no longer needs, and detects cross-surface instruction conflicts), audit-prompting-postures (the additive lane \u2014 posture guidance the prompting guide says a component's purpose needs but the component does not carry), audit-pass (one coordinated, ordered, resumable pass over a named target \u2014 three-scope inventory, run-time-derived exclusion set, stable finding identity, suppression memory, resume, one human gate \u2014 delegating every check to the plugin that owns it), and unhobble (the empirical bare-baseline experiment: reversibly strip a repo's standing instructions, log real stumbles against the current model, re-add only what evidence earns).", "author": { "name": "Melodic Software", diff --git a/plugins/claude-config/CHANGELOG.md b/plugins/claude-config/CHANGELOG.md index f53bdc7a2..eb91dda98 100644 --- a/plugins/claude-config/CHANGELOG.md +++ b/plugins/claude-config/CHANGELOG.md @@ -3,6 +3,15 @@ All notable changes to the `claude-config` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.40.11] + +### Changed + +- **Long reference files carry a `## Contents` index.** `audit-instructions`'s 1,741-line + criteria.md gained a Contents section with its per-ID catalog entries and a grep recipe for + lookup by ID; `audit-pass`'s run-state-and-resumability.md gained a Contents section. Purely + additive. Progressive-disclosure audit, missing-toc treatment. + ## [0.40.10] ### Changed diff --git a/plugins/claude-config/skills/audit-instructions/reference/criteria.md b/plugins/claude-config/skills/audit-instructions/reference/criteria.md index a0351d44b..31373341b 100644 --- a/plugins/claude-config/skills/audit-instructions/reference/criteria.md +++ b/plugins/claude-config/skills/audit-instructions/reference/criteria.md @@ -5,6 +5,45 @@ last-updated: 2026-08-09 # Instruction-Audit Criteria +## Contents + +Look up a specific check by ID: +`grep -n '^### I:' "${CLAUDE_PLUGIN_ROOT}/skills/audit-instructions/reference/criteria.md"`. + +- [Sources](#sources) +- Checks + - [I1: Line-necessity bar](#i1-line-necessity-bar) + - [I2: Length and skimmability](#i2-length-and-skimmability) + - [I3: Broad-applicability placement](#i3-broad-applicability-placement) + - [I4: Inferable or redundant content](#i4-inferable-or-redundant-content) + - [I5: Rule-to-hook or delete](#i5-rule-to-hook-or-delete) + - [I6: Bare prohibition to positive reframing](#i6-bare-prohibition-to-positive-reframing) + - [I7: Reason with the request](#i7-reason-with-the-request) + - [I8: Model-era re-audit](#i8-model-era-re-audit) + - [I9: Example hygiene](#i9-example-hygiene) + - [I10: Reasoning-echo directives](#i10-reasoning-echo-directives) + - [I11: CLI over MCP where equivalent](#i11-cli-over-mcp-where-equivalent) + - [I12: Stale or misattributed harness-capability claim](#i12-stale-or-misattributed-harness-capability-claim) + - [I13: Citation form that does not load](#i13-citation-form-that-does-not-load) + - [I14: Retrieval of an already-loaded surface](#i14-retrieval-of-an-already-loaded-surface) + - [I15: Cross-surface instruction conflict](#i15-cross-surface-instruction-conflict) + - [I16: Definition-site locality](#i16-definition-site-locality) + - [I17: Thinking disabled where the model forbids it](#i17-thinking-disabled-where-the-model-forbids-it) + - [I18: Thinking blocks altered on the way back to the model](#i18-thinking-blocks-altered-on-the-way-back-to-the-model) + - [I19: Restated external benchmark figure with no recheck trigger](#i19-restated-external-benchmark-figure-with-no-recheck-trigger) + - [I20: Prefilled assistant response](#i20-prefilled-assistant-response) + - [I21: Effort level pinned across a model change with no re-sweep](#i21-effort-level-pinned-across-a-model-change-with-no-re-sweep) + - [I22: Model-routing doctrine with no baseline named](#i22-model-routing-doctrine-with-no-baseline-named) + - [I23: Context-budget directive to stop, summarize, or hand off](#i23-context-budget-directive-to-stop-summarize-or-hand-off) + - [I24: Instruction relying on silent generalization](#i24-instruction-relying-on-silent-generalization) + - [I25: Sampling parameter prescribed where the model rejects it](#i25-sampling-parameter-prescribed-where-the-model-rejects-it) + - [I26: Generic negative steering on open-ended design briefs](#i26-generic-negative-steering-on-open-ended-design-briefs) + - [I27: Effort lowered to shorten the response](#i27-effort-lowered-to-shorten-the-response) + - [I28: Over-aggressive trigger emphasis and blanket tool defaults](#i28-over-aggressive-trigger-emphasis-and-blanket-tool-defaults) + - [I29: Body prose that restates the always-in-context description, or a sibling section](#i29-body-prose-that-restates-the-always-in-context-description-or-a-sibling-section) +- [Stopping condition](#stopping-condition) +- [Output format](#output-format) + The checks the `audit-instructions` skill runs, seeded from current official prompting doctrine. Each check carries an evidence tier, an authority tag, a default severity, its surface applicability, and one decisive source line (point-don't-copy — the full doctrine lives at the diff --git a/plugins/claude-config/skills/audit-pass/reference/run-state-and-resumability.md b/plugins/claude-config/skills/audit-pass/reference/run-state-and-resumability.md index be3b8026e..760feaf8b 100644 --- a/plugins/claude-config/skills/audit-pass/reference/run-state-and-resumability.md +++ b/plugins/claude-config/skills/audit-pass/reference/run-state-and-resumability.md @@ -1,5 +1,10 @@ # audit-pass — run state, concurrency, and resumability +## Contents + +- [3. Run state, keying, and concurrency](#3-run-state-keying-and-concurrency) +- [5. Mid-run resumability](#5-mid-run-resumability) + This file owns §3 and §5: how the run tree is keyed, the applying lock, the lease that tells a live run from an abandoned one, and what `--resume` re-runs rather than carries forward. diff --git a/plugins/claude-memory/.claude-plugin/plugin.json b/plugins/claude-memory/.claude-plugin/plugin.json index e0c9a8085..9c470a540 100644 --- a/plugins/claude-memory/.claude-plugin/plugin.json +++ b/plugins/claude-memory/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "claude-memory", - "version": "0.11.3", + "version": "0.11.4", "description": "Keeps a repo's Claude Code memory layer healthy and under your control, against criteria derived from official Claude Code documentation. The audit skill checks the instruction/memory layer (CLAUDE.md, CLAUDE.local.md, .claude/rules/, auto-memory) with a deterministic script-backed spine plus judgment-tier checks. The stateless skill inspects, disables, and (confirm-gated) purges Claude-written auto memory across all settings scopes.", "author": { "name": "Melodic Software", diff --git a/plugins/claude-memory/CHANGELOG.md b/plugins/claude-memory/CHANGELOG.md index dcf76f894..1127d572d 100644 --- a/plugins/claude-memory/CHANGELOG.md +++ b/plugins/claude-memory/CHANGELOG.md @@ -3,6 +3,15 @@ All notable changes to the `claude-memory` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.11.4] + +### Changed + +- **`audit` reaches its cross-skill dependency directly.** The hub gained a direct conditioned + pointer to `skills/stateless/context/status.md`, which reference/criteria.md names as the only + correct resolution path; the 449-line criteria.md gained a `## Contents` index. Behavior + unchanged. Progressive-disclosure audit, deep-nesting and missing-toc treatments. + ## [0.11.3] ### Changed diff --git a/plugins/claude-memory/skills/audit/SKILL.md b/plugins/claude-memory/skills/audit/SKILL.md index 489c87512..ac6e08bda 100644 --- a/plugins/claude-memory/skills/audit/SKILL.md +++ b/plugins/claude-memory/skills/audit/SKILL.md @@ -38,6 +38,10 @@ the `audit` and `automation-gaps` skills in the `claude-config` plugin). | Auto-memory | `~/.claude/projects//memory/` | First 200 lines / 25KB of MEMORY.md | Yes | | Settings, hooks, MCP, agents, skills | Various | Various | No. Use `claude-config`'s `audit` / `automation-gaps` | +Auto memory's effective enabled/disabled state must be resolved before auditing it, not assumed +from a single scope: [`${CLAUDE_PLUGIN_ROOT}/skills/stateless/context/status.md`](../stateless/context/status.md), +"Resolve the effective state". + The two user-scope rows are in scope because they load in every session regardless of where it starts. Discovery tags every file with its scope so project-scoped criteria (C9) skip personal files rather than reporting a repo-scoped finding against one. **C6 Consistency** owns instruction-content diff --git a/plugins/claude-memory/skills/audit/reference/criteria.md b/plugins/claude-memory/skills/audit/reference/criteria.md index ca1007122..5c1e2339b 100644 --- a/plugins/claude-memory/skills/audit/reference/criteria.md +++ b/plugins/claude-memory/skills/audit/reference/criteria.md @@ -1,5 +1,12 @@ # Memory Health Criteria +## Contents + +- [Checks for CLAUDE.md and CLAUDE.local.md](#checks-for-claudemd-and-claudelocalmd) +- [Checks for .claude/rules/ files](#checks-for-clauderules-files) +- [Checks for auto-memory (MEMORY.md + topic files)](#checks-for-auto-memory-memorymd--topic-files) +- [Audit output format](#audit-output-format) + Version: 1.6.0 Last updated: 2026-08-19 Source: Official Claude Code docs (code.claude.com/docs/en/memory, code.claude.com/docs/en/best-practices, code.claude.com/docs/en/sub-agents, code.claude.com/docs/en/skills) diff --git a/plugins/claude-ops/.claude-plugin/plugin.json b/plugins/claude-ops/.claude-plugin/plugin.json index 8e924bf31..f2c51f51d 100644 --- a/plugins/claude-ops/.claude-plugin/plugin.json +++ b/plugins/claude-ops/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "claude-ops", - "version": "0.38.10", + "version": "0.38.11", "description": "Claude Code operations toolkit. Twelve skills: audit-skill-visibility (audit whether each installed skill is actually VISIBLE to the model, and diagnose why most of a fleet never gets used \u2014 a skill is invisible when its description is dropped by Claude Code's skill-listing context budget, which drops descriptions least-invoked-first so an unused skill loses the keywords that would let it be matched, from skills genuinely not wanted, from skills the run cannot observe at all; computes whether the listing overflows from documented settings, and withholds every cold verdict the data cannot support rather than reporting absence of data as absence of use), inventory (read-only enumeration of the complete invocable surface \u2014 every built-in CLI command with aliases and hidden/gated status, every bundled skill, and every component of every installed plugin across all marketplaces; reads the shipped binary because upstream publishes no built-in command list, and carries an integrity verdict so a drifted build reports counts as floors rather than silently short totals), audit-install-state (read-only audit of the machine-scope ~/.claude installation directory and ~/.claude.json \u2014 full inventory split into an authored surface and rolled-up bulk trees, product-managed retention vs genuinely unmanaged state, filename-scheme resolution before any process-liveness check, and deliberate/mid-experiment detection; reports, never deletes), audit-performance (read-only slowness-diagnostic capture run at the moment the machine or a session feels slow: CLI version, retention-sweep health including the silent unparsable-settings pause, a timed census walk of the install tree as a sweep-cost proxy, active-session and plugin-fleet counts, a process census, and the fan-out layer, which covers a load-labelled no-op spawn baseline, every hook that will fire bucketed per-tool-call versus per-turn with its invocation shape, the configured statusline, subagent concurrency and spawn-depth ceilings against documented defaults, whether running sessions predate the settings file they are judged by, and orphan attribution by parent liveness rather than age; read against a bundled known-performance-issues reference that also records the causes tested and cleared; separates the four documented suspects of accumulated state, version regression, component bloat, and per-spawn fan-out cost, and routes remediation out; reports, never mutates, and never executes a discovered hook or statusline command), audit-native-overlap (map native Claude Code surfaces \u2014 built-in CLI commands, bundled skills, plugin-backed built-ins, session-provided skills \u2014 against the current repo's plugin skills and agents, so a custom component never silently duplicates what Claude Code itself ships; bare invocation is a read-only overlap report carrying the extraction's integrity floors and a shared-listing-budget exposure section, verdicts are human-gated in a committed store rendered into a generated registry whose every row carries an observable recheck trigger, and only an explicit apply step bakes presence-gated native references into descriptions and Boundary sections), observability (read locally captured telemetry \u2014 OTEL store, collector, hook-event JSONL, ccusage \u2014 with trend reports and store pruning), known-issues (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand \u2014 marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), morning-brief (read-only gh-based operator morning view \u2014 queue-label counts, merge-ready PRs, parked decisions with their RECOMMENDED lines, and loop-lane telemetry freshness), lanes (start/restart/stop/status loop lanes as named background Claude Code sessions seeded from canonical prompt files, with per-lane model/effort, a repo-pull + marketplace-refresh launch step, and a consume-restarts action \u2014 an OS-schedulable reader that relaunches stopped lanes whose telemetry carries a restart_request), and a re-runnable setup action that settles where the known-issues registry lives. Plus a family of eight advisory *-audit hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures, and unsurfaced hook failures \u2014 the last also warns the user via systemMessage, since a hook that fails to launch enforces nothing and Claude Code surfaces the failure to nobody) that emit the shared hook-telemetry envelope, and a reference sink that maps envelopes into the hook-events.jsonl the observability skill reads.", "author": { "name": "Melodic Software", diff --git a/plugins/claude-ops/CHANGELOG.md b/plugins/claude-ops/CHANGELOG.md index 31614d024..2a41424ab 100644 --- a/plugins/claude-ops/CHANGELOG.md +++ b/plugins/claude-ops/CHANGELOG.md @@ -3,6 +3,16 @@ All notable changes to the `claude-ops` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.38.11] + +### Changed + +- **`observability`'s operator-setup leaves are one hop from the hub.** The context ladder gained + direct conditioned rows for operator-setup-collector-daemon.md, operator-setup-retention.md, and + operator-setup-emission-privacy.md, previously reachable only through intermediate spokes; the + 363-line plugin README gained a `## Contents` index. Behavior unchanged. Progressive-disclosure + audit, deep-nesting and missing-toc treatments. + ## [0.38.10] ### Changed diff --git a/plugins/claude-ops/README.md b/plugins/claude-ops/README.md index c885af172..49cbc1ec8 100644 --- a/plugins/claude-ops/README.md +++ b/plugins/claude-ops/README.md @@ -1,5 +1,15 @@ # claude-ops +## Contents + +- [Skills](#skills) +- [The audit hooks](#the-audit-hooks) +- [Install](#install) +- [How the skills adapt to your repo](#how-the-skills-adapt-to-your-repo) +- [Requirements](#requirements) +- [Configuration](#configuration) +- [License](#license) + A Claude Code plugin for running Claude Code well over time. One cohesive capability across twelve skills and a family of telemetry-emitter hooks, including diagnosing why most of an installed skill fleet never gets used. diff --git a/plugins/claude-ops/skills/observability/SKILL.md b/plugins/claude-ops/skills/observability/SKILL.md index e187b082f..68504c4d9 100644 --- a/plugins/claude-ops/skills/observability/SKILL.md +++ b/plugins/claude-ops/skills/observability/SKILL.md @@ -41,6 +41,9 @@ This skill reads **your** captured telemetry and ops signals. | [context/otel-pipeline.md](context/otel-pipeline.md) | Collector/dashboard down, store empty, service health | | [context/otel-queries.md](context/otel-queries.md) | DuckDB SQL, Aspire CLI, views | | [context/operator-setup.md](context/operator-setup.md) | Install, env profile, retention scripts | +| [context/operator-setup-collector-daemon.md](context/operator-setup-collector-daemon.md) | Collector/Aspire service down or unhealthy, lifecycle repair | +| [context/operator-setup-retention.md](context/operator-setup-retention.md) | Prune mechanics, retention knobs, scheduled prune task | +| [context/operator-setup-emission-privacy.md](context/operator-setup-emission-privacy.md) | Emission tiers, content-capture keys, privacy toggle | | [context/data-sources.md](context/data-sources.md) | JSONL + ccusage jq (batch reports) | | [context/output-format.md](context/output-format.md) | Rendering scope reports | | [context/privacy.md](context/privacy.md) | Before any user-visible output | diff --git a/plugins/discipline/.claude-plugin/plugin.json b/plugins/discipline/.claude-plugin/plugin.json index 573f5eadc..7f660701b 100644 --- a/plugins/discipline/.claude-plugin/plugin.json +++ b/plugins/discipline/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "discipline", - "version": "0.12.18", + "version": "0.12.19", "description": "Discipline correctors that re-anchor a standing rule mid-session, then audit both the work in flight and the pre-existing state and choices it trusts, and correct what has drifted: do-your-research (research and no-assumptions discipline; sibling do-your-research-deep escalates to a typed full inventory of the session's claims — assumptions, asserted facts, concrete specifics, load-bearing premises — verified at a configurable depth and reported as a per-item ledger), follow-our-standards (alignment to the consuming org's engineering conventions), point-dont-copy (pointer-over-copy discipline — no copied content, internal-name coupling, or closed capability lists), reason-dont-recite (interrogate inherited content — precedent is evidence of what is, never self-justifying authority), tighten-your-output (terseness discipline — fewer words or lines with no loss of meaning or correctness), recheck-against-upstream (existing state is not evidence of its own correctness — audit config, code, and infra against current official upstream docs; sibling recheck-against-upstream-deep fans subagents doc-by-doc over a whole subsystem), pick-for-the-problem (tool, library, framework, and approach selection fitted to the problem, not reached for out of habit, availability, incumbency, or preconception), mind-your-maxims (cooperative-communication discipline per Grice plus the AI-augmented transparency maxim), script-the-deterministic-work (offload deterministic sub-work — counts, diffs, sorts, transforms, and scaffolds — to a script that runs, reserving model output for judgment over its real output; the audit runs both ways, also catching an existing script that over-reaches into judgement), use-your-skills (actually use the skills already in context — scan the listing, map the task, invoke the fitting skill instead of reinventing it, and name skills when delegating to a subagent), and reuse-or-replace (anti-fragmentation — new work reuses an established way of doing something or openly replaces it (migrate the old uses, record the decision), never silently stands up a second parallel way; divergence is allowed but owes a recorded reason proportional to blast radius), and scrutinize-dont-coast (adversarial self-scrutiny — stop coasting on your own recent output and re-examine whether it is sound, not merely confidently produced, through a fresh-context pass blind to the reasoning that made it, then remediate with the user; it stops the trajectory first and remediates collaboratively rather than autonomously). Plus further species that are not correctors (examples, not a fixed list — each skill's own description is authoritative), including setup, sweep-all, a posture-batch runbook that composes them — it fans out an audit-only subagent per in-scope corrector, then applies the corrections on the main thread in a fixed order, with batch membership and order set by each corrector's own colocated tier metadata and an optional userConfig overlay — and wait-what, a one-shot user-invoked-only communication repair: type /discipline:wait-what when the last message did not land and the model re-pitches it, backing up as far as needed, adding the missing context, in ASD-STE100 Simplified Technical English, using the project's ubiquitous language; never model-invoked and never in the batch. Firing a corrector is a re-anchor, not an accusation; the audit may return clean.", "author": { "name": "Melodic Software", diff --git a/plugins/discipline/CHANGELOG.md b/plugins/discipline/CHANGELOG.md index e705e58ed..c651b2341 100644 --- a/plugins/discipline/CHANGELOG.md +++ b/plugins/discipline/CHANGELOG.md @@ -5,6 +5,14 @@ All notable changes to the `discipline` plugin are documented here. Format follo Entries below `0.9.0` were released under the plugin's former name, `re-anchor`. +## [0.12.19] + +### Changed + +- **The plugin README carries a `## Contents` index.** The 461-line README's per-skill sections + and configuration subsections are now anchor-linked from the top. Purely additive. + Progressive-disclosure audit, missing-toc treatment. + ## [0.12.18] ### Changed diff --git a/plugins/discipline/README.md b/plugins/discipline/README.md index 5c644334b..2191d099d 100644 --- a/plugins/discipline/README.md +++ b/plugins/discipline/README.md @@ -13,6 +13,32 @@ Firing a corrector is a re-anchor, not an accusation. Reaching for one as a gentle reminder, before the work, or just to set posture, is a first-class use, and the audit may honestly return clean. +## Contents + +- [What each skill does](#what-each-skill-does) + - [do-your-research](#do-your-research) + - [do-your-research-deep](#do-your-research-deep) + - [follow-our-standards](#follow-our-standards) + - [point-dont-copy](#point-dont-copy) + - [reason-dont-recite](#reason-dont-recite) + - [tighten-your-output](#tighten-your-output) + - [recheck-against-upstream](#recheck-against-upstream) + - [recheck-against-upstream-deep](#recheck-against-upstream-deep) + - [pick-for-the-problem](#pick-for-the-problem) + - [mind-your-maxims](#mind-your-maxims) + - [script-the-deterministic-work](#script-the-deterministic-work) + - [use-your-skills](#use-your-skills) + - [reuse-or-replace](#reuse-or-replace) + - [scrutinize-dont-coast](#scrutinize-dont-coast) + - [sweep-all (composed runbook)](#sweep-all-composed-runbook) + - [wait-what (one-shot communication repair)](#wait-what-one-shot-communication-repair) +- [Consumer conventions](#consumer-conventions) +- [Install](#install) +- [Configuration](#configuration) + - [Options reference](#options-reference) + - [How to set these](#how-to-set-these) + - [Upstream documentation](#upstream-documentation) + | Skill | Discipline it re-anchors | |---|---| | `/discipline:do-your-research` | Research and no-assumptions before assertion | diff --git a/plugins/discovery/.claude-plugin/plugin.json b/plugins/discovery/.claude-plugin/plugin.json index 3b2f679ae..c2b514f16 100644 --- a/plugins/discovery/.claude-plugin/plugin.json +++ b/plugins/discovery/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "discovery", - "version": "0.16.12", + "version": "0.16.13", "description": "Structured discovery before changes: explore the local codebase, run disciplined multi-source external research, and reconstruct why a past decision was made from evidence outside the code \u2014 each dispatching a purpose-built subagent by default so the reading stays out of the main conversation, with source tiers, falsification, recency gates, an intent-evidence tier, and a corpus-coverage ledger \u2014 persisting EXPLORE.md / RESEARCH.md / INTENT.md index-plus-sidecar handoff artifacts.", "author": { "name": "Melodic Software", diff --git a/plugins/discovery/CHANGELOG.md b/plugins/discovery/CHANGELOG.md index a2869405b..7ae7d5d98 100644 --- a/plugins/discovery/CHANGELOG.md +++ b/plugins/discovery/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog — discovery plugin +## [0.16.13] + +### Changed + +- **`trace-intent` links the topic-docs binding its siblings already link.** The hub gained the + sibling-phrased conditioned pointer to `reference/topic-docs.md` at its persist step. +- **`research` and `explore` park by-value binding detail in their dispatch spokes.** The + conditions that bind the persistence-by-value exception moved verbatim into each skill's + existing dispatch spoke behind the by-value pointer; envelopes, preload tokens, and acceptance + gates stay inline. Behavior unchanged. Progressive-disclosure audit treatments. + ## [0.16.12] ### Changed diff --git a/plugins/discovery/skills/explore/SKILL.md b/plugins/discovery/skills/explore/SKILL.md index 975cbdd9c..971d402e8 100644 --- a/plugins/discovery/skills/explore/SKILL.md +++ b/plugins/discovery/skills/explore/SKILL.md @@ -64,9 +64,7 @@ A missing or mismatched token is a **hard failure: the parent discards the run** **One named exception, and it is an exception to the halt, not to the gate.** Exit 1 with `persistence: by-value` in the payload means the agent finished and its environment refused every write, the one failure the ladder previously had no rung for, and the one where a re-dispatch pays full price to reproduce the same refusal. There the parent **writes the slice itself** from the artifact bodies the payload carries verbatim, into the memory-slice path it resolved before dispatch (on that path the payload's `artifact:` value is a *destination* the agent names, never the anchor), and then **re-runs the identical gate command above**. The workflow proceeds only on a subsequent exit 0. If the second run is non-zero, the halt stands and the ladder resumes at the rung it was on. The freshness check needs nothing special: the parent writes after its own pre-dispatch `touch`, so the index is strictly newer than the baseline. -Two conditions bind that write, both spelled out in the ladder. **Filenames are checked before anything is written**. This is the only place a name the worker produced becomes a write the parent performs, at the parent's wider permission, so only `EXPLORE.md` and `EXPLORE-
.md` are accepted, as bare filenames, and anything carrying a directory separator, a `..` segment or a leading `/` is a failed dispatch rather than a name to sanitize. **And the collision rule still applies**, a slice root already holding an unrelated `EXPLORE.md` gets a parent-assigned sub-slice here exactly as it would for a worker that could write, because overwriting the index that rule protects would be a silent, unrecoverable loss arriving through the recovery path. - -Nothing in the payload is ever accepted *in place of* the gate passing. `persistence: by-value` routes the parent; it does not grade anything, and it is never a reason to believe a run. A by-value payload carrying a summary of findings rather than the artifact bodies is a **failed dispatch**, not a fallback, the whole discipline rests on the artifact being real, and a claim the gate is invited to accept on trust is the laundering this skill exists to refuse. Why the mode exists and where its boundary sits: [`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md). +Read the by-value rung before performing that write: [`${CLAUDE_PLUGIN_ROOT}/skills/explore/reference/dispatch.md`](${CLAUDE_PLUGIN_ROOT}/skills/explore/reference/dispatch.md). It carries the two conditions that bind the write (filename checking and the collision rule) and why a by-value payload of findings rather than artifact bodies is a failed dispatch rather than a fallback. **Coverage discipline** when fanning out: (1) write a numbered gap-list before any deepen pass; (2) fan out by disjoint area, never split the six dimensions across agents; (3) whoever holds the workflow writes `EXPLORE.md`. `discovery:explorer` writes its own, while built-in Explore agents cannot write one at all, so their caller does. diff --git a/plugins/discovery/skills/explore/reference/dispatch.md b/plugins/discovery/skills/explore/reference/dispatch.md index 771aeb7ba..205b42500 100644 --- a/plugins/discovery/skills/explore/reference/dispatch.md +++ b/plugins/discovery/skills/explore/reference/dispatch.md @@ -128,7 +128,8 @@ So the parent does the writing, which it can — this is the checkout-not-proces **A by-value payload that returns findings instead of artifact bodies is a failed dispatch, not a fallback.** The value of the third outcome is *routing*: it tells the parent which recovery to take. It is not an acceptance value, and treating it as one would let a run be believed on the -agent's own word — the exact thing the gate exists to refuse. +agent's own word — the exact thing the gate exists to refuse. Why the mode exists and where its +boundary sits: [`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md). **Exit 1 with the agent still live — resume it; do not re-dispatch it.** A resume costs one message; a re-dispatch pays the full six dimensions over again. Address the agent by the **agent ID**, not by diff --git a/plugins/discovery/skills/research/SKILL.md b/plugins/discovery/skills/research/SKILL.md index b872d5556..9202d47f6 100644 --- a/plugins/discovery/skills/research/SKILL.md +++ b/plugins/discovery/skills/research/SKILL.md @@ -65,9 +65,7 @@ A missing or mismatched token is a **hard failure: the parent discards the run** **One named exception, and it is an exception to the halt, not to the gate.** Exit 1 with `persistence: by-value` in the payload means the agent finished and its environment refused every write. There the parent **writes the slice itself** from the artifact bodies the payload carries verbatim, into the memory-slice path it resolved before dispatch, and then **re-runs the identical checks above, the artifact gate always, and the coverage-ledger gate whenever a ledger was owed.** The workflow proceeds only when every check that applied comes back 0; otherwise the halt stands and the ladder resumes at the rung it was on. -Two conditions bind that write and both are spelled out in the ladder. **filenames are checked before anything reaches disk** (only `RESEARCH.md`, `RESEARCH-
.md` and `research-checklist.md`, as bare filenames), and **step 3's unbounded-corpus rule is unchanged**. Read the by-value rung before performing that write: [`${CLAUDE_PLUGIN_ROOT}/skills/research/context/dispatch.md`](${CLAUDE_PLUGIN_ROOT}/skills/research/context/dispatch.md). - -Nothing in the payload is ever accepted *in place of* a gate passing. `persistence: by-value` routes the parent; it grades nothing. A by-value payload carrying a summary of findings rather than the artifact bodies is a **failed dispatch**, not a fallback: research the gate is invited to accept on the agent's word is the Tier-3 laundering this skill forbids everywhere else. Why the mode exists and where its boundary sits: [`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md). +Read the by-value rung before performing that write: [`${CLAUDE_PLUGIN_ROOT}/skills/research/context/dispatch.md`](${CLAUDE_PLUGIN_ROOT}/skills/research/context/dispatch.md). It carries the two conditions that bind the write (filename checking and the unchanged unbounded-corpus rule) and why a by-value payload of findings rather than artifact bodies is a failed dispatch rather than a fallback. ## Topic diff --git a/plugins/discovery/skills/research/context/dispatch.md b/plugins/discovery/skills/research/context/dispatch.md index cb50b008d..8c56749c1 100644 --- a/plugins/discovery/skills/research/context/dispatch.md +++ b/plugins/discovery/skills/research/context/dispatch.md @@ -211,7 +211,8 @@ already draws, finally reachable from the failure that needs it: fallback.** The value of the third outcome is *routing*: it tells the parent which recovery to take. It is not an acceptance value. Letting the gate grade a claim the agent makes about its own research, in place of the artifact and the ledger, is the Tier-3 laundering the discipline forbids — arriving -through the recovery path instead of the front door. +through the recovery path instead of the front door. Why the mode exists and where its boundary +sits: [`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md). **Exit 1 with the agent still live — resume it; do not re-dispatch it.** A resume costs one message; a re-dispatch pays all the phases over again. Address the agent by its **agent ID**, not by name, and ask diff --git a/plugins/discovery/skills/trace-intent/SKILL.md b/plugins/discovery/skills/trace-intent/SKILL.md index fe083820d..d44723707 100644 --- a/plugins/discovery/skills/trace-intent/SKILL.md +++ b/plugins/discovery/skills/trace-intent/SKILL.md @@ -174,7 +174,10 @@ When the question precedes an actual change, close with a Preserve / Change / Av constraint set the planning stage can consume. **Persist it as `INTENT.md` plus `INTENT-
.md` sidecars** in the memory slice, so a fresh -session can resume from the artifact alone. The index is the entry point at every size, and **Sources +session can resume from the artifact alone. Destination, slug, and runtime guards resolve per the +plugin's topic-docs binding +([`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md)). +The index is the entry point at every size, and **Sources consulted** lives in it rather than in a sidecar, a reader who takes the answer and stops must still meet the shape of the record behind it. Header schema, and why neither sibling family's header fits: [`context/artifact-shape.md`](context/artifact-shape.md). diff --git a/plugins/guardrails/.claude-plugin/plugin.json b/plugins/guardrails/.claude-plugin/plugin.json index 086623fea..4a2684890 100644 --- a/plugins/guardrails/.claude-plugin/plugin.json +++ b/plugins/guardrails/.claude-plugin/plugin.json @@ -147,5 +147,5 @@ "min": 1 } }, - "version": "0.29.15" + "version": "0.29.16" } diff --git a/plugins/guardrails/CHANGELOG.md b/plugins/guardrails/CHANGELOG.md index ebb6ab01c..90ff50fdf 100644 --- a/plugins/guardrails/CHANGELOG.md +++ b/plugins/guardrails/CHANGELOG.md @@ -3,6 +3,17 @@ All notable changes to the `guardrails` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.29.16] + +### Changed + +- **`setup`'s two opt-in install procedures are on-demand spokes.** `apply install-commit-msg` and + `apply install-pre-commit-content` moved verbatim to `context/install-commit-msg.md` and + `context/install-pre-commit-content.md`; the hub keeps each procedure's summary, its + never-from-bare-`apply` guard, and a conditioned pointer. The 451-line plugin README gained a + `## Contents` index. Behavior unchanged. Progressive-disclosure audit, mixed-concerns and + missing-toc treatments. + ## [0.29.15] ### Changed diff --git a/plugins/guardrails/README.md b/plugins/guardrails/README.md index 7e3bf9888..f6f9e5962 100644 --- a/plugins/guardrails/README.md +++ b/plugins/guardrails/README.md @@ -4,6 +4,22 @@ A Claude Code plugin bundling fourteen **safety guards** that catch risky agent actions the moment they happen, before a write lands or a bash command runs. Each guard is independently toggleable, so you run exactly the subset you want. +## Contents + +- [The guards](#the-guards) + - [Enforceability tiers](#enforceability-tiers) + - [Scope notes](#scope-notes) +- [Per-hook kill switches](#per-hook-kill-switches) +- [Consumer seams](#consumer-seams) +- [Telemetry (opt-in)](#telemetry-opt-in) +- [Requirements](#requirements) +- [Install](#install) +- [Configuration](#configuration) + - [Options reference](#options-reference) + - [How to set these](#how-to-set-these) + - [Upstream documentation](#upstream-documentation) +- [License](#license) + ## The guards | Guard | Event / matcher | Behavior | What it catches | diff --git a/plugins/guardrails/skills/setup/SKILL.md b/plugins/guardrails/skills/setup/SKILL.md index 2e216347c..de70aec82 100644 --- a/plugins/guardrails/skills/setup/SKILL.md +++ b/plugins/guardrails/skills/setup/SKILL.md @@ -80,112 +80,28 @@ Re-running `apply` after everything passes changes nothing and reports "already ## `apply install-commit-msg` (opt-in, explicit argument only) The DEPTH layer of commit-convention enforcement: a git `commit-msg` hook validating every -commit on this machine in this repo: editor commits, `git commit -F `, IDE -integrations, humans outside Claude, against the same team-tracked pattern the CC-layer -`block-convention-violation` guard reads, through a copy of the same resolver. Never runs -from bare `apply`; only the explicit `install-commit-msg` argument installs anything. - -**Lane: personal `.git/hooks/` only.** This writes the CURRENT OPERATOR's repo-local hooks -directory, invisible to teammates, uncommitted, removable by deleting two files. A -committed team lane (`core.hooksPath` pointing at a tracked directory) is deliberately NOT -scaffolded: `core.hooksPath` changes are exactly what the `block-no-verify` guard refuses -as a hook-bypass shape, and pointing every teammate's git at a tracked hooks dir is a team -decision made by a human in a PR, not by this skill. When the team wants shared -enforcement, say so and point at a commit-msg entry in the repo's own hook manager -(lefthook/husky/CI) instead. - -**Preflight: refuse rather than surprise (run all, report, stop on any REFUSE):** - -1. **Managed-repo detection.** `git config --get core.hooksPath` non-empty, or - `lefthook.yml`/`.lefthook.yml`, `.husky/`, or a `pre-commit` config managing hooks → - REFUSE: the repo's hook manager owns this surface; installing behind its back invites - silent shadowing. Remediation: add the convention check to the manager's own - `commit-msg` entry. -2. **Existing `commit-msg` hook.** Present and NOT sentinel-marked → offer exactly two - paths and default to refusing: **chain** (rename the existing hook to - `commit-msg.pre-guardrails`; the installed hook runs it first and its rejection is - final) or **refuse** (leave everything untouched). Never overwrite. This includes an - operator's machine-local commit-msg gate. Chaining preserves it. -3. **Sentinel-marked hook already installed** → idempotent re-install: overwrite the two - guardrails-owned files in place (template may have updated), report "refreshed". - -**Install (on a clean preflight):** copy `${CLAUDE_PLUGIN_ROOT}/lib/git-hooks/commit-msg-convention.sh` -to `/hooks/commit-msg` and `${CLAUDE_PLUGIN_ROOT}/hooks/resolve-convention-pattern.sh` -to `/hooks/guardrails-resolve-convention.sh` (resolve `` via -`git rev-parse --absolute-git-dir`; in a worktree `.git` is a file), `chmod +x` both. - -**Verify + report:** run the installed hook against a throwaway conforming and violating -message file and show both outcomes; state the removal path (delete the two files; restore -`commit-msg.pre-guardrails` to `commit-msg` if chaining renamed one) and that -**unresolved = no enforcement**. With no team-tracked `subject_pattern` the hook -passes everything, so installing before `/source-control:setup apply` writes a convention -is inert, not harmful. - -**Known interactions (state them in the report):** - -- `--no-verify` skips commit-msg hooks, and the guardrails `block-no-verify` guard blocks - that flag in Claude sessions. By design the only exit from a rejection is a compliant - subject (the hook's message says exactly that and never suggests bypass). -- The CC-layer `block-convention-violation` guard usually blocks a violating subject - before git ever runs, so this hook firing in a Claude session means the CC layer was - bypassed or disabled. It is the backstop, not the primary UX. -- Convention-inference tooling must skip sentinel-marked hooks (the - `guardrails-commit-msg-convention` marker). The hook is derived FROM the tracked - config and is not an independent convention signal. +commit on this machine in this repo (editor commits, `git commit -F `, IDE +integrations, humans outside Claude) against the same team-tracked pattern the CC-layer +`block-convention-violation` guard reads. Never runs from bare `apply`; only the explicit +`install-commit-msg` argument installs anything. + +Read [context/install-commit-msg.md](context/install-commit-msg.md) when invoked with +`apply install-commit-msg`: the personal-lane contract, the refuse-rather-than-surprise +preflight, the install and verify steps, and the known interactions to state in the report. ## `apply install-pre-commit-content` (opt-in, explicit argument only) -The DEPTH layer for content invariants that Write|Edit-matched guards alone cannot -close: a git `pre-commit` hook scanning every staged blob for the same high-confidence -secret patterns and hardcoded machine-path patterns the CC-layer -`secret-pattern-detection` / `hardcoded-path-check` guards use, via copies of the same -libs (`lib/secret-detection/`, `lib/path-detection/`). Catches the damage class a Bash -staged write (`jq … > /tmp/x && mv /tmp/x dest`) can introduce while skipping those +The DEPTH layer for content invariants that Write|Edit-matched guards alone cannot close: a +git `pre-commit` hook scanning every staged blob for the same secret and hardcoded-path +patterns the CC-layer `secret-pattern-detection` / `hardcoded-path-check` guards use. +Catches the damage class a Bash staged write can introduce while skipping those tool-matched gates. Never runs from bare `apply`; only the explicit `install-pre-commit-content` argument installs anything. -**Lane: personal `.git/hooks/` only.** Same personal-lane contract as -`install-commit-msg`: invisible to teammates, uncommitted, removable by deleting the -hook and its `guardrails-content-lib/` directory. A committed team lane is deliberately -NOT scaffolded; when the team wants shared enforcement, add the same checks to the -repo's hook manager or CI instead. - -**Preflight: refuse rather than surprise (run all, report, stop on any REFUSE):** - -1. **Managed-repo detection.** `git config --get core.hooksPath` non-empty, or - `lefthook.yml`/`.lefthook.yml`, `.husky/`, or a `pre-commit` config managing hooks → - REFUSE: the repo's hook manager owns this surface. Remediation: add the content scan - to the manager's own `pre-commit` entry (point it at the shipped template + libs, or - an equivalent CI job). -2. **Existing `pre-commit` hook.** Present and NOT sentinel-marked → offer exactly two - paths and default to refusing: **chain** (rename the existing hook to - `pre-commit.pre-guardrails`; the installed hook runs it first and its rejection is - final) or **refuse** (leave everything untouched). Never overwrite. -3. **Sentinel-marked hook already installed** → idempotent re-install: overwrite the - guardrails-owned hook and refresh `guardrails-content-lib/` in place, report - "refreshed". - -**Install (on a clean preflight):** copy -`${CLAUDE_PLUGIN_ROOT}/lib/git-hooks/pre-commit-content-invariants.sh` to -`/hooks/pre-commit`, and copy `${CLAUDE_PLUGIN_ROOT}/lib/secret-detection/` plus -`${CLAUDE_PLUGIN_ROOT}/lib/path-detection/` to -`/hooks/guardrails-content-lib/{secret,path}-detection/` (resolve `` via -`git rev-parse --absolute-git-dir`), `chmod +x` the hook. - -**Verify + report:** stage a throwaway clean file and a throwaway file containing a -synthetic high-confidence secret pattern (e.g. a `ghp_` + 36-char fixture, never a live -token); show both hook outcomes; state the removal path (delete `pre-commit` and -`guardrails-content-lib/`; restore `pre-commit.pre-guardrails` if chaining renamed one). - -**Known interactions (state them in the report):** - -- `--no-verify` skips pre-commit hooks; `block-no-verify` refuses that flag in Claude - sessions. The designed exit is fixing the staged content. -- The CC-layer Write|Edit guards usually block first in a Claude session; this hook is - the backstop for write paths those guards never see (Bash staged moves, editor - saves, IDE commits, humans outside Claude). -- `block-hook-bypass`'s same-command staged-move detector narrows one spelling; this - hook closes the damage class regardless of write path. +Read [context/install-pre-commit-content.md](context/install-pre-commit-content.md) when +invoked with `apply install-pre-commit-content`: the personal-lane contract, the +refuse-rather-than-surprise preflight, the install and verify steps, and the known +interactions to state in the report. ## What this skill does NOT do diff --git a/plugins/guardrails/skills/setup/context/install-commit-msg.md b/plugins/guardrails/skills/setup/context/install-commit-msg.md new file mode 100644 index 000000000..96538d1c8 --- /dev/null +++ b/plugins/guardrails/skills/setup/context/install-commit-msg.md @@ -0,0 +1,55 @@ +# `apply install-commit-msg` (opt-in, explicit argument only) + +The DEPTH layer of commit-convention enforcement: a git `commit-msg` hook validating every +commit on this machine in this repo: editor commits, `git commit -F `, IDE +integrations, humans outside Claude, against the same team-tracked pattern the CC-layer +`block-convention-violation` guard reads, through a copy of the same resolver. Never runs +from bare `apply`; only the explicit `install-commit-msg` argument installs anything. + +**Lane: personal `.git/hooks/` only.** This writes the CURRENT OPERATOR's repo-local hooks +directory, invisible to teammates, uncommitted, removable by deleting two files. A +committed team lane (`core.hooksPath` pointing at a tracked directory) is deliberately NOT +scaffolded: `core.hooksPath` changes are exactly what the `block-no-verify` guard refuses +as a hook-bypass shape, and pointing every teammate's git at a tracked hooks dir is a team +decision made by a human in a PR, not by this skill. When the team wants shared +enforcement, say so and point at a commit-msg entry in the repo's own hook manager +(lefthook/husky/CI) instead. + +**Preflight: refuse rather than surprise (run all, report, stop on any REFUSE):** + +1. **Managed-repo detection.** `git config --get core.hooksPath` non-empty, or + `lefthook.yml`/`.lefthook.yml`, `.husky/`, or a `pre-commit` config managing hooks → + REFUSE: the repo's hook manager owns this surface; installing behind its back invites + silent shadowing. Remediation: add the convention check to the manager's own + `commit-msg` entry. +2. **Existing `commit-msg` hook.** Present and NOT sentinel-marked → offer exactly two + paths and default to refusing: **chain** (rename the existing hook to + `commit-msg.pre-guardrails`; the installed hook runs it first and its rejection is + final) or **refuse** (leave everything untouched). Never overwrite. This includes an + operator's machine-local commit-msg gate. Chaining preserves it. +3. **Sentinel-marked hook already installed** → idempotent re-install: overwrite the two + guardrails-owned files in place (template may have updated), report "refreshed". + +**Install (on a clean preflight):** copy `${CLAUDE_PLUGIN_ROOT}/lib/git-hooks/commit-msg-convention.sh` +to `/hooks/commit-msg` and `${CLAUDE_PLUGIN_ROOT}/hooks/resolve-convention-pattern.sh` +to `/hooks/guardrails-resolve-convention.sh` (resolve `` via +`git rev-parse --absolute-git-dir`; in a worktree `.git` is a file), `chmod +x` both. + +**Verify + report:** run the installed hook against a throwaway conforming and violating +message file and show both outcomes; state the removal path (delete the two files; restore +`commit-msg.pre-guardrails` to `commit-msg` if chaining renamed one) and that +**unresolved = no enforcement**. With no team-tracked `subject_pattern` the hook +passes everything, so installing before `/source-control:setup apply` writes a convention +is inert, not harmful. + +**Known interactions (state them in the report):** + +- `--no-verify` skips commit-msg hooks, and the guardrails `block-no-verify` guard blocks + that flag in Claude sessions. By design the only exit from a rejection is a compliant + subject (the hook's message says exactly that and never suggests bypass). +- The CC-layer `block-convention-violation` guard usually blocks a violating subject + before git ever runs, so this hook firing in a Claude session means the CC layer was + bypassed or disabled. It is the backstop, not the primary UX. +- Convention-inference tooling must skip sentinel-marked hooks (the + `guardrails-commit-msg-convention` marker). The hook is derived FROM the tracked + config and is not an independent convention signal. diff --git a/plugins/guardrails/skills/setup/context/install-pre-commit-content.md b/plugins/guardrails/skills/setup/context/install-pre-commit-content.md new file mode 100644 index 000000000..651a2516c --- /dev/null +++ b/plugins/guardrails/skills/setup/context/install-pre-commit-content.md @@ -0,0 +1,53 @@ +# `apply install-pre-commit-content` (opt-in, explicit argument only) + +The DEPTH layer for content invariants that Write|Edit-matched guards alone cannot +close: a git `pre-commit` hook scanning every staged blob for the same high-confidence +secret patterns and hardcoded machine-path patterns the CC-layer +`secret-pattern-detection` / `hardcoded-path-check` guards use, via copies of the same +libs (`lib/secret-detection/`, `lib/path-detection/`). Catches the damage class a Bash +staged write (`jq … > /tmp/x && mv /tmp/x dest`) can introduce while skipping those +tool-matched gates. Never runs from bare `apply`; only the explicit +`install-pre-commit-content` argument installs anything. + +**Lane: personal `.git/hooks/` only.** Same personal-lane contract as +`install-commit-msg`: invisible to teammates, uncommitted, removable by deleting the +hook and its `guardrails-content-lib/` directory. A committed team lane is deliberately +NOT scaffolded; when the team wants shared enforcement, add the same checks to the +repo's hook manager or CI instead. + +**Preflight: refuse rather than surprise (run all, report, stop on any REFUSE):** + +1. **Managed-repo detection.** `git config --get core.hooksPath` non-empty, or + `lefthook.yml`/`.lefthook.yml`, `.husky/`, or a `pre-commit` config managing hooks → + REFUSE: the repo's hook manager owns this surface. Remediation: add the content scan + to the manager's own `pre-commit` entry (point it at the shipped template + libs, or + an equivalent CI job). +2. **Existing `pre-commit` hook.** Present and NOT sentinel-marked → offer exactly two + paths and default to refusing: **chain** (rename the existing hook to + `pre-commit.pre-guardrails`; the installed hook runs it first and its rejection is + final) or **refuse** (leave everything untouched). Never overwrite. +3. **Sentinel-marked hook already installed** → idempotent re-install: overwrite the + guardrails-owned hook and refresh `guardrails-content-lib/` in place, report + "refreshed". + +**Install (on a clean preflight):** copy +`${CLAUDE_PLUGIN_ROOT}/lib/git-hooks/pre-commit-content-invariants.sh` to +`/hooks/pre-commit`, and copy `${CLAUDE_PLUGIN_ROOT}/lib/secret-detection/` plus +`${CLAUDE_PLUGIN_ROOT}/lib/path-detection/` to +`/hooks/guardrails-content-lib/{secret,path}-detection/` (resolve `` via +`git rev-parse --absolute-git-dir`), `chmod +x` the hook. + +**Verify + report:** stage a throwaway clean file and a throwaway file containing a +synthetic high-confidence secret pattern (e.g. a `ghp_` + 36-char fixture, never a live +token); show both hook outcomes; state the removal path (delete `pre-commit` and +`guardrails-content-lib/`; restore `pre-commit.pre-guardrails` if chaining renamed one). + +**Known interactions (state them in the report):** + +- `--no-verify` skips pre-commit hooks; `block-no-verify` refuses that flag in Claude + sessions. The designed exit is fixing the staged content. +- The CC-layer Write|Edit guards usually block first in a Claude session; this hook is + the backstop for write paths those guards never see (Bash staged moves, editor + saves, IDE commits, humans outside Claude). +- `block-hook-bypass`'s same-command staged-move detector narrows one spelling; this + hook closes the damage class regardless of write path. diff --git a/plugins/machine-health/.claude-plugin/plugin.json b/plugins/machine-health/.claude-plugin/plugin.json index 2195f1f0b..db480f041 100644 --- a/plugins/machine-health/.claude-plugin/plugin.json +++ b/plugins/machine-health/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "machine-health", - "version": "0.11.8", + "version": "0.11.9", "description": "Workstation health audit: OS-specific checks (disk, OS updates, security posture, CISA KEV correlation) run from a versioned catalog with trend-aware severity, approval-gated remediations, and dated markdown reports. Windows fully implemented; macOS/Linux scaffolded (report UNKNOWN and stop). Machine state persists in the plugin data directory; the report directory and check catalog are configurable.", "author": { "name": "Melodic Software", diff --git a/plugins/machine-health/CHANGELOG.md b/plugins/machine-health/CHANGELOG.md index 4b66b48ec..2c4508ad0 100644 --- a/plugins/machine-health/CHANGELOG.md +++ b/plugins/machine-health/CHANGELOG.md @@ -3,6 +3,15 @@ All notable changes to the `machine-health` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.11.9] + +### Changed + +- **The orphaned shared references are reachable from the audit README.** The maintainer README + gained pointers to `references/shared/correlation-rules.md` (how the orchestrator applies + correlation rules) and `references/shared/testing.md` (Pester test conventions). Purely + additive. Progressive-disclosure audit, orphan-spoke treatment. + ## [0.11.8] ### Added diff --git a/plugins/machine-health/skills/audit/README.md b/plugins/machine-health/skills/audit/README.md index 6823999e1..49f453d4e 100644 --- a/plugins/machine-health/skills/audit/README.md +++ b/plugins/machine-health/skills/audit/README.md @@ -72,6 +72,12 @@ environment variable is set). A single check can run in isolation: 3. New remediation: write `scripts/windows/remediations/-.ps1`, add it to the authorization list in `references/windows/remediation-policy.md`, and wire dispatch in the orchestrator. Remediations always default to not approved. 4. New OS: replace the matching `NOT_IMPLEMENTED.md` with a populated folder. Consult `references/shared/discovery-guide.md` for the porting checklist. +How the orchestrator applies cross-finding correlation rules after check dispatch: `references/shared/correlation-rules.md`. + +## Testing + +Pester test conventions (directory layout, fixtures, prerequisites): `references/shared/testing.md`. + ## Guardrails codified in the skill See `SKILL.md` § Guardrails. Briefly: 15m total, 90s per check, no interactive prompts, no retries, first-run dry mode, admin never assumed, egress allowlist, no `Invoke-Expression` on external data, never write into the plugin install directory. diff --git a/plugins/planning/.claude-plugin/plugin.json b/plugins/planning/.claude-plugin/plugin.json index d902ab57b..d78288648 100644 --- a/plugins/planning/.claude-plugin/plugin.json +++ b/plugins/planning/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "planning", - "version": "0.34.10", + "version": "0.34.11", "userConfig": { "use_ask_user_question": { "type": "boolean", diff --git a/plugins/planning/CHANGELOG.md b/plugins/planning/CHANGELOG.md index fce61e098..e73e5f5b3 100644 --- a/plugins/planning/CHANGELOG.md +++ b/plugins/planning/CHANGELOG.md @@ -3,6 +3,18 @@ All notable changes to the `planning` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.34.11] + +### Changed + +- **`plan`'s argument-gated sections are on-demand spokes.** Plan Review Mode and the close-out + procedure (including the ADR admission test and spec-container ritual) moved verbatim to + `context/review-mode.md` and `context/close-out.md` behind their existing router rows. +- **`interview`'s relentless-only framing is an on-demand spoke.** The two exclusively-`me` + paragraphs moved to `context/relentless-mode.md`; the per-question template stays inline because + every questioning mode uses it. Behavior unchanged. Progressive-disclosure audit, oversize-hub + treatments. + ## [0.34.10] ### Changed diff --git a/plugins/planning/skills/interview/SKILL.md b/plugins/planning/skills/interview/SKILL.md index bcad9efe1..68e5d4d18 100644 --- a/plugins/planning/skills/interview/SKILL.md +++ b/plugins/planning/skills/interview/SKILL.md @@ -86,9 +86,7 @@ Tone is collaborative but opinionated. You are not interrogating; you are helpin ### Relentless mode (`me`) -`me` is the **relentless interview**. Drive EVERY *consequential* branch of the decision tree to a *decision*. No question cap (some plans need three, some fifty; the escape hatch is the user saying "wrap up", never a counter). Relentless is not exhausting: every question leads with a recommendation, so most answers are a one-tap "correct". - -**Canonical framing** (what `me` means, in one breath): *interview relentlessly about every aspect of the task until you reach a shared understanding; map the decision tree and work it in rounds. Each round asks every frontier question (prerequisites settled) as one numbered set, each with your recommended answer, and the answers recompute the frontier; finding facts is your job, never the user's. Resolve them from the environment (filesystem, tools, sub-agents) instead of asking; the decisions are the user's. Put each one to them and wait.* +Read [`context/relentless-mode.md`](context/relentless-mode.md) before the first round when the action resolves to `me`. It holds what relentless mode means and its canonical framing. The round mechanics below apply to every mode that asks questions. **Ask each round inline as one numbered set.** Per-question shape within the round: diff --git a/plugins/planning/skills/interview/context/relentless-mode.md b/plugins/planning/skills/interview/context/relentless-mode.md new file mode 100644 index 000000000..21d026622 --- /dev/null +++ b/plugins/planning/skills/interview/context/relentless-mode.md @@ -0,0 +1,9 @@ +# Relentless mode (`me`) + +What the `me` action means and how it is framed. Read this before the first round when the action +resolves to `me`. The per-question ask shape, the round mechanics, recommended answers, and the +domain-aware behaviors are shared by every mode that asks questions and stay in SKILL.md. + +`me` is the **relentless interview**. Drive EVERY *consequential* branch of the decision tree to a *decision*. No question cap (some plans need three, some fifty; the escape hatch is the user saying "wrap up", never a counter). Relentless is not exhausting: every question leads with a recommendation, so most answers are a one-tap "correct". + +**Canonical framing** (what `me` means, in one breath): *interview relentlessly about every aspect of the task until you reach a shared understanding; map the decision tree and work it in rounds. Each round asks every frontier question (prerequisites settled) as one numbered set, each with your recommended answer, and the answers recompute the frontier; finding facts is your job, never the user's. Resolve them from the environment (filesystem, tools, sub-agents) instead of asking; the decisions are the user's. Put each one to them and wait.* diff --git a/plugins/planning/skills/plan/SKILL.md b/plugins/planning/skills/plan/SKILL.md index 36ea04cf6..ff94561bf 100644 --- a/plugins/planning/skills/plan/SKILL.md +++ b/plugins/planning/skills/plan/SKILL.md @@ -254,15 +254,7 @@ Plan mode is also a natural moment for a **scoping confirm**. If you're entering ## Plan Review Mode -When invoked with `review`: - -1. Identify the plan in the current conversation (most recent plan, proposal, or design) -2. Evaluate against the [plan template](context/plan-template.md). Is anything missing? -3. Check alignment with the consuming project's conventions (its `CLAUDE.md` and rules) -4. Assess whether the blast radius was properly evaluated -5. Present findings: what's strong, what's missing, what needs revision - -This is complementary to `/planning:devils-advocate`. Review checks completeness and convention alignment; stress-test checks assumptions and failure modes. +Read [context/review-mode.md](context/review-mode.md) when invoked with `review`. It holds the review procedure and how it differs from `/planning:devils-advocate`. ## Final step: persist the approved plan for handoff @@ -278,30 +270,7 @@ PLAN.md is a multi-turn shared artifact: re-read it from disk before every write Write the plan even for small changes. Future you or a fresh-session agent will thank you. -**Close-out (PR time).** The contract slice is branch-lived; `/planning:plan` owns describing its close-out. Invoke with the `close-out` argument once the plan is approved: - -1. Paste the approved PLAN.md into the PR description inside a `
` block. The review-surface publication (PR bodies cap near 64 KB; paste the contract, reference the rest). -2. Graduate durable outcomes through the knowledge-vault seam. Resolve the concern file's `vault_backend`: `docs` (default) → a history-preserving `git mv` of the promoted doc into `docs/adr/` or `docs/specs/` (guard the command. Create the target directory first); `gitbook` → report that writes are deferred and use the `docs` path without invoking GitBook API/MCP or Git Sync; any other enabled value → the backend the consuming repo documents, degrading to `docs` when its tools are absent (binding: [`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md)). Actionable follow-ups go through the work-item tracker seam. - - **ADR admission test**. A decision earns an ADR only when ALL three hold: **hard to reverse** (changing course later carries real cost), **surprising without context** (a future reader of the code would wonder why it was done this way), and **the result of a real trade-off** (genuine alternatives existed and one was picked for specific reasons). Any one missing → no ADR: an easily reversed decision just gets reversed, an unsurprising one raises no questions, and a no-alternative decision has nothing worth recording. Keep each ADR minimal. A title plus a few sentences covering context, decision, and why; optional sections (status, considered options, consequences) only when they earn their place. Prefer writing the ADR the moment the decision crystallizes during planning over batching candidates at graduation. This step then just moves the already-written file. -3. Prune with pointer: a final commit before merge deletes the contract slice `//` (default `docs/topics/`), leaving context pointers (the PR body, the promoted-doc and tracker locations) in its place. -4. Spec-container ship ritual (presence-gated. Only when the `work-items` plugin is installed - AND the topic's decomposition published a spec container). **Detect the container - mechanically, never from in-session memory** (close-out often runs in a fresh session): - first read the topic's PLAN.md for the `**Spec container:** ` line - `/work-items:decompose` records under `## Brief` at publish time; absent that line, query - the tracker for an open item carrying the binding-resolved container label (default - `work-map`) whose body cites the topic slug. Found → run the container's close-at-ship - ritual through the path that owns it. `/work-items:decompose` "Container lifecycle - (spec-on-tracker)". That section owns the mechanics (verify every sub-item closed, close-out - review against the container body, close with a comment linking the shipping PRs. Archival - by closure); this step only sequences it into close-out and never redefines it. When the - shipped work covers only part of the container's sub-items, the container stays open. Close - it only when the whole spec has shipped. Neither detection path yields a container, or no - `work-items` plugin: skip silently. Publishing a container is `/work-items:decompose`'s - approval-time offer, never a close-out side effect. - -Lifecycle detail and the redaction bar for committed evidence: [`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md). +**Close-out (PR time).** The contract slice is branch-lived; `/planning:plan` owns describing its close-out. Read [context/close-out.md](context/close-out.md) when invoked with `close-out`. It holds the four-step procedure, the ADR admission test, and the spec-container ship ritual. **Mid-flight pivots:** when scope changes after approval, append a dated scope-change note to the affected PLAN.md section capturing the rationale, and strikethrough+link the obsolete content. Carry the pivot rationale in the commit message as well. The contract is branch-tracked, so git log is the history. Do not silently rewrite history. diff --git a/plugins/planning/skills/plan/context/close-out.md b/plugins/planning/skills/plan/context/close-out.md new file mode 100644 index 000000000..a421b496c --- /dev/null +++ b/plugins/planning/skills/plan/context/close-out.md @@ -0,0 +1,28 @@ +# Close-out (PR time) + +Spoke for `/planning:plan`. Read this file when the skill is invoked with the `close-out` argument. + +**Close-out (PR time).** The contract slice is branch-lived; `/planning:plan` owns describing its close-out. Invoke with the `close-out` argument once the plan is approved: + +1. Paste the approved PLAN.md into the PR description inside a `
` block. The review-surface publication (PR bodies cap near 64 KB; paste the contract, reference the rest). +2. Graduate durable outcomes through the knowledge-vault seam. Resolve the concern file's `vault_backend`: `docs` (default) → a history-preserving `git mv` of the promoted doc into `docs/adr/` or `docs/specs/` (guard the command. Create the target directory first); `gitbook` → report that writes are deferred and use the `docs` path without invoking GitBook API/MCP or Git Sync; any other enabled value → the backend the consuming repo documents, degrading to `docs` when its tools are absent (binding: [`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md)). Actionable follow-ups go through the work-item tracker seam. + + **ADR admission test**. A decision earns an ADR only when ALL three hold: **hard to reverse** (changing course later carries real cost), **surprising without context** (a future reader of the code would wonder why it was done this way), and **the result of a real trade-off** (genuine alternatives existed and one was picked for specific reasons). Any one missing → no ADR: an easily reversed decision just gets reversed, an unsurprising one raises no questions, and a no-alternative decision has nothing worth recording. Keep each ADR minimal. A title plus a few sentences covering context, decision, and why; optional sections (status, considered options, consequences) only when they earn their place. Prefer writing the ADR the moment the decision crystallizes during planning over batching candidates at graduation. This step then just moves the already-written file. +3. Prune with pointer: a final commit before merge deletes the contract slice `//` (default `docs/topics/`), leaving context pointers (the PR body, the promoted-doc and tracker locations) in its place. +4. Spec-container ship ritual (presence-gated. Only when the `work-items` plugin is installed + AND the topic's decomposition published a spec container). **Detect the container + mechanically, never from in-session memory** (close-out often runs in a fresh session): + first read the topic's PLAN.md for the `**Spec container:** ` line + `/work-items:decompose` records under `## Brief` at publish time; absent that line, query + the tracker for an open item carrying the binding-resolved container label (default + `work-map`) whose body cites the topic slug. Found → run the container's close-at-ship + ritual through the path that owns it. `/work-items:decompose` "Container lifecycle + (spec-on-tracker)". That section owns the mechanics (verify every sub-item closed, close-out + review against the container body, close with a comment linking the shipping PRs. Archival + by closure); this step only sequences it into close-out and never redefines it. When the + shipped work covers only part of the container's sub-items, the container stays open. Close + it only when the whole spec has shipped. Neither detection path yields a container, or no + `work-items` plugin: skip silently. Publishing a container is `/work-items:decompose`'s + approval-time offer, never a close-out side effect. + +Lifecycle detail and the redaction bar for committed evidence: [`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md). diff --git a/plugins/planning/skills/plan/context/review-mode.md b/plugins/planning/skills/plan/context/review-mode.md new file mode 100644 index 000000000..b49017c2e --- /dev/null +++ b/plugins/planning/skills/plan/context/review-mode.md @@ -0,0 +1,13 @@ +# Plan Review Mode + +Spoke for `/planning:plan`. Read this file when the skill is invoked with the `review` argument. + +When invoked with `review`: + +1. Identify the plan in the current conversation (most recent plan, proposal, or design) +2. Evaluate against the [plan template](plan-template.md). Is anything missing? +3. Check alignment with the consuming project's conventions (its `CLAUDE.md` and rules) +4. Assess whether the blast radius was properly evaluated +5. Present findings: what's strong, what's missing, what needs revision + +This is complementary to `/planning:devils-advocate`. Review checks completeness and convention alignment; stress-test checks assumptions and failure modes. diff --git a/plugins/planning/tests/interview-defenses.test.sh b/plugins/planning/tests/interview-defenses.test.sh index 14575ec43..ac1efe470 100755 --- a/plugins/planning/tests/interview-defenses.test.sh +++ b/plugins/planning/tests/interview-defenses.test.sh @@ -473,7 +473,7 @@ pin_section "SKILL.md Stance section is unchanged (the in-round no-silent-resolv "$SKILL" \ "## Stance: supportive, depth-first, opinionated" \ "## The interview loop" \ - "8e74bcacaf33d19e69847eed0bb3096bedb4130cfbc729ab3c1362a6eea0420c" + "e627a2702a4ab924a8b681e9d6279d3d9f53e8039b4fbb30fdcf1f503fada711" pin_section "SKILL.md interview-loop preamble is unchanged (it governs every step below it)" \ "$SKILL" \ "## The interview loop" \ diff --git a/plugins/session-flow/.claude-plugin/plugin.json b/plugins/session-flow/.claude-plugin/plugin.json index 877e13d05..260a23f0e 100644 --- a/plugins/session-flow/.claude-plugin/plugin.json +++ b/plugins/session-flow/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "session-flow", - "version": "0.34.7", + "version": "0.34.8", "description": "Session-lifecycle toolkit of fourteen skills: workflow (navigate a staged dev workflow and suggest the next stage), handoff (write a save-point and resume prompt for /clear-and-resume), continue-in-background (delegate the task to a fresh background agent that continues it now \u2014 same save-point engine as handoff, delivered by launching a detached claude --bg session seeded with the resume prompt; launches only on explicit user request), keep-going (recover and continue after any interruption OR when live off-thread work looks stalled \u2014 inventory off-thread work, inspect its real output, act only on evidence, then continue; after a usage limit lifts it continues rather than summarizing-and-stalling), find-handoff (recover a lost handoff after /clear \u2014 when the resume prompt was written but never copied \u2014 via a read-only detection ladder: known-location glob of the handoffs dir, then a bounded, recency-ranked transcript scan for the handoff directive and dashed-rail markers, then a confirm-before-resume gate; surfaces only the resume prompt + metadata, never raw transcript content), clean-stop (get to a durable, linked stopping point before the machine may go away \u2014 sweep every repo/worktree for uncommitted, unpushed, or PR-less work, push it durable, put breadcrumbs in PR/issue bodies, then give a free-and-clear verdict), retro (structured end-of-session retrospective with transcript metrics and learning codification), running-retro (in-flight retrospective checkpoints that spawn a subagent to analyze the transcript so far and append classified findings to a cumulative running ledger \u2014 capture and route only, the live counterpart to retro; also owns a detached-observer substrate that can watch a session out-of-band and run the checkpoint autonomously after the session ends), orient (read-only session orientation \u2014 synthesize where we stand, what we are doing, and why, from durable + off-thread state the built-in /recap never sees: ledgers, handoffs, workflow checklists, running-retro ledgers, open PRs and work-items, and git), orchestrate (arm a session or worker with proactive-orchestration imperatives), reanchor (verify a session's working assumptions are still true against live reality \u2014 referenced PRs/issues/branches, base-branch drift, renamed/version-drifted surfaces, stale memory-tier files, and the goal a handoff records, compared across the chain so a re-derived goal reports as drift \u2014 before building on them), reconcile (retire finished off-thread work and reconcile this session's task ledger with reality \u2014 the prune-and-reconcile counterpart to keep-going's resume: inventory the work this session spawned, inspect its real state, retire the finished and close proven-done tasks, auto-settling the finished and gating any kill of still-running work; sibling sessions in the project are reported read-only), setup (check-centric verification of the observer's runtime prerequisites and configuration), and show-options (lay out which skills fit this moment as a ranked, nothing-hidden menu \u2014 a shortlist per bucket plus the complete remainder by name, resolved from the full installed catalog rather than the truncated in-context listing, so the human decides and no option is withheld for looking already-done).", "author": { "name": "Melodic Software", diff --git a/plugins/session-flow/CHANGELOG.md b/plugins/session-flow/CHANGELOG.md index 9c5ba4b18..14b4c1d6c 100644 --- a/plugins/session-flow/CHANGELOG.md +++ b/plugins/session-flow/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog — session-flow plugin +## [0.34.8] + +### Changed + +- **Long files carry a `## Contents` index.** The 438-line plugin README and the 442-line + reference/structure.md gained Contents sections, including the handoff document's own body + sections as lookup targets. Purely additive. Progressive-disclosure audit, missing-toc + treatment. + ## [0.34.7] ### Changed diff --git a/plugins/session-flow/README.md b/plugins/session-flow/README.md index 1a3d9d5b8..ca29b5123 100644 --- a/plugins/session-flow/README.md +++ b/plugins/session-flow/README.md @@ -24,6 +24,31 @@ arm it for delegation-heavy tasks. | `/session-flow:setup` | Are the observer's runtime prerequisites and configuration right on this machine? | | `/session-flow:show-options` | Which skills fit this moment, and what am I forgetting I could run? | +## Contents + +- [Output styles](#output-styles) +- [What each skill does](#what-each-skill-does) + - [workflow](#workflow) + - [handoff](#handoff) + - [continue-in-background](#continue-in-background) + - [keep-going](#keep-going) + - [find-handoff](#find-handoff) + - [clean-stop](#clean-stop) + - [retro](#retro) + - [running-retro](#running-retro) + - [orient](#orient) + - [orchestrate](#orchestrate) + - [reanchor](#reanchor) + - [reconcile](#reconcile) + - [show-options](#show-options) + - [setup](#setup) +- [Consumer conventions](#consumer-conventions) +- [Install](#install) +- [Configuration](#configuration) + - [Options reference](#options-reference) + - [How to set these](#how-to-set-these) + - [Upstream documentation](#upstream-documentation) + ## Output styles - **`Brain fried`**. Opt-in simplified register for cognitively depleted sessions (short words, diff --git a/plugins/session-flow/reference/structure.md b/plugins/session-flow/reference/structure.md index f7246366f..d382a7ee8 100644 --- a/plugins/session-flow/reference/structure.md +++ b/plugins/session-flow/reference/structure.md @@ -7,6 +7,26 @@ resolution live in the sibling `save-point.md` engine doc). Reader is a session with NO prior context. It will act on this file. Be specific — vague handoffs cost the next session a re-investigation, which is the cost this document exists to avoid. +## Contents + +- [Body sections](#body-sections) + - [Original goal](#original-goal) + - [Resumption brief](#resumption-brief) + - [Completion criteria](#completion-criteria) + - [Constraints that must hold](#constraints-that-must-hold) + - [Environment to re-establish](#environment-to-re-establish) + - [Side effects already applied](#side-effects-already-applied) + - [File roles in this work](#file-roles-in-this-work) + - [Decisions already settled](#decisions-already-settled) + - [Approaches tried and abandoned](#approaches-tried-and-abandoned) + - [Findings that cost effort to discover](#findings-that-cost-effort-to-discover) + - [Remaining actions, in order](#remaining-actions-in-order) + - [Open questions to investigate](#open-questions-to-investigate) + - [Blockers needing an outside decision](#blockers-needing-an-outside-decision) + - [Suggested skills](#suggested-skills) +- [How this document is referenced elsewhere](#how-this-document-is-referenced-elsewhere) +- [Full-path write procedure](#full-path-write-procedure) + ## Body sections Ordered so the cheapest useful layer comes first. A reader can stop after **Original goal** plus diff --git a/plugins/songwriting/.claude-plugin/plugin.json b/plugins/songwriting/.claude-plugin/plugin.json index 073b88c43..dc3e5c2c9 100644 --- a/plugins/songwriting/.claude-plugin/plugin.json +++ b/plugins/songwriting/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "songwriting", - "version": "1.4.13", + "version": "1.4.14", "description": "Songwriting craft companion — nine concern-scoped lyric-craft skills (workflow router, rhyme, object-writing, metaphor, meter-prosody, song-form, co-write, diagnose, practice) applying Pat Pattison's methods, with an object-writing agent that performs the sensory exercise itself and per-skill emission boundaries that route generation to the skill that owns it, plus Suno v5.5 prompt engineering (style prompts, tagged lyrics, genre templates, troubleshooting).", "author": { "name": "Melodic Software", diff --git a/plugins/songwriting/CHANGELOG.md b/plugins/songwriting/CHANGELOG.md index 4e13d2981..a02985343 100644 --- a/plugins/songwriting/CHANGELOG.md +++ b/plugins/songwriting/CHANGELOG.md @@ -3,6 +3,16 @@ All notable changes to the `songwriting` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [1.4.14] + +### Changed + +- **`suno`'s claim-audit history lives in the drift ledger.** The Confidence flags section keeps + the rung definitions, each item's current label with a one-line basis, and the generation rule; + the dated search records and revision narratives merged into + `reference/suno-drift-audit-ledger.md` (S11 updated, S19 and S20 added) behind a hub pointer. + No content lost. Progressive-disclosure audit, tier-mismatch treatment. + ## [1.4.13] ### Changed diff --git a/plugins/songwriting/skills/suno/SKILL.md b/plugins/songwriting/skills/suno/SKILL.md index 6caaa4be3..21fbd5938 100644 --- a/plugins/songwriting/skills/suno/SKILL.md +++ b/plugins/songwriting/skills/suno/SKILL.md @@ -215,17 +215,13 @@ If `` is ambiguous (could be template OR research OR suggest), ask user wh - **HIGH confidence**: claims confirmed by Suno's official help center (`help.suno.com`) or `suno.com/blog`. The 6-layer formula, structural and vocal tag names, Custom mode requirements, Voices/Custom Models/My Taste mechanics, and Creative Slider names and qualitative endpoints, all HIGH. Character budgets are NOT officially published, third-party tester consensus only (MEDIUM-HIGH). - **MEDIUM confidence**: community-validated techniques across multiple guides + Reddit consensus, but no official Suno doc. Capitalization weighting magnitude, vowel-stretching letter counts, hyphenation staccato, `(x2)` failure mode, and **every numeric Creative Slider setting or range in this skill except the Audio Influence entry value** are community-empirical. Treat exact magnitudes and slider numbers as starting points for A/B tests, not official values. - - **Reaching the Reddit half.** Web search and direct fetch of `reddit.com` both fail from this environment; **a browser session reaches it**, and that is the documented route (`context/workflow-recipes.md`). Three releases in a row recorded a claim as "Reddit untried" when the route was already written down here, so before rating anything below MEDIUM for want of Reddit, use the browser route rather than concluding the corpus is closed. -- **LOW-MEDIUM confidence**: below MEDIUM because the multi-source consensus is missing. At most a single community post plus its own comment thread, and no official Suno doc. **One item at this rung was verified locally** (Duration range, corroborated by one community post. See [context/advanced.md](context/advanced.md#duration-slider-create-form)). Three live uses: - - the Duration slider range (10s–6min, 5-second increments) in [context/advanced.md](context/advanced.md#duration-slider-create-form), read from the UI and independently stated by one community post; no `help.suno.com` range article; - - the two-stage voice bootstrap for non-singers and the "make this voice public" toggle warning, both in [context/voices.md](context/voices.md), both resting on the same single r/SunoAI post plus its comments (untested here); - - the timing-cue nudge in [context/tips.md](context/tips.md), **whose basis is recorded nowhere in this repo and could not be sourced externally either.** The `~70%` adherence figure it carried through 1.1.1 was **removed in 1.1.2** after an in-repo search (2026-08-11, re-run 2026-08-12) and an external pass (2026-08-12: two `help.suno.com` articles read verbatim, two large community meta-tag references grepped, both yielding zero hits for the cue form and for `70%`) found nothing behind it. The *technique* is kept and stays flagged low; the number is gone, and `tips.md` records the corpus searched. Offer these as untested leads carrying their own caveat, never as procedure, and never in place of a better-supported route when one exists. -- **OFF the ladder. First-hand writer observation.** Every rung above grades **second-hand** sourcing: official docs, multiple community guides, a single community post. A finding the writer produced by driving Suno directly is a different evidentiary axis, not a rung of that one, so it is labeled in place with `writer-observed, single session (2026-08-12), n=1 — not externally corroborated` (dated per finding) and **no new rung is invented for it**, the gap is named instead. Two things follow. First-hand does **not** outrank MEDIUM: one unreproduced session is not consensus, and where the reading is flow-scoped or setup-scoped the label must carry that scope with it. But an observed **failure** is existence evidence in a way a claimed success is not. It shows the failure *can* happen, which is enough to document a fix, and never enough to assert that it always happens or to state a mechanism. Surface these with the label and scope attached, and prefer the cheap safe default over the clever shape whenever one exists. Three live uses carry the label: the Audio Influence entry value ([context/advanced.md](context/advanced.md)), and tag-only section absorption plus short-line over-separation (both [context/troubleshoot.md](context/troubleshoot.md)). **The Duration slider's range is deliberately NOT one of them**, the writer read it first-hand *and* one community post states the same figures independently, so it is corroborated, the label's closing clause would be false of it, and it is rated **LOW-MEDIUM** on the ladder instead. A first-hand observation that finds external support graduates onto the ladder; it does not keep the off-ladder label as a badge. -- **Re-verified 2026-07-18. Position flipped since the 2026-05-10 pass**: current third-party testers agree the lyrics **hard cap is 5,000 chars on v4.5/v5/v5.5**; 3,000 was the v4-and-earlier cap. The earlier "3,000 consensus" conflated the old cap with the quality threshold. **~3,000 remains the practical budget**. Past it Suno rushes, skips sections, or shortens output. Sources: [hookgenius character limits](https://hookgenius.app/learn/suno-character-limits/), [aimusicapi cheat sheet, 2026-07-03](https://aimusicapi.ai/en/blog/suno-ai-prompt-character-limits). No official Suno page states field limits. +- **LOW-MEDIUM confidence**: below MEDIUM because the multi-source consensus is missing. At most a single community post plus its own comment thread, and no official Suno doc. Current items: the Duration slider range, read from the UI and corroborated by one community post ([context/advanced.md](context/advanced.md#duration-slider-create-form)); the two-stage voice bootstrap for non-singers and the "make this voice public" toggle warning, both resting on a single r/SunoAI post ([context/voices.md](context/voices.md)); and the timing-cue nudge, whose basis is unsourced both in-repo and externally ([context/tips.md](context/tips.md)). Offer these as untested leads carrying their own caveat, never as procedure, and never in place of a better-supported route when one exists. +- **OFF the ladder. First-hand writer observation.** Every rung above grades **second-hand** sourcing: official docs, multiple community guides, a single community post. A finding the writer produced by driving Suno directly is a different evidentiary axis, not a rung of that one, so it is labeled in place with `writer-observed, single session (date), n=1 — not externally corroborated` (dated per finding) and **no new rung is invented for it**, the gap is named instead. First-hand does **not** outrank MEDIUM: one unreproduced session is not consensus, and where the reading is flow-scoped or setup-scoped the label must carry that scope with it. But an observed **failure** is existence evidence in a way a claimed success is not: it shows the failure *can* happen, which is enough to document a fix, and never enough to assert that it always happens or to state a mechanism. Surface these with the label and scope attached, and prefer the cheap safe default over the clever shape whenever one exists. Current items: the Audio Influence entry value ([context/advanced.md](context/advanced.md)), and tag-only section absorption plus short-line over-separation (both [context/troubleshoot.md](context/troubleshoot.md)). The Duration slider's range is **not** one of them: an independent community post corroborates the writer's reading, so it graduates onto the ladder at LOW-MEDIUM instead of staying off-ladder. A first-hand observation that finds external support graduates onto the ladder; it does not keep the off-ladder label as a badge. When generating prompts, default to HIGH-confidence techniques. Surface MEDIUM-confidence tricks as opt-in suggestions, not commands. Surface LOW-MEDIUM items only with their caveat attached, and only after naming the better-supported route. Surface off-ladder writer observations with their label and their scope attached, and when one records a failure, give the safe default as the fix rather than a prohibition. +For dated search records and per-claim audit history behind every label above, see [reference/suno-drift-audit-ledger.md](reference/suno-drift-audit-ledger.md). + --- ## Maintenance. Load on demand diff --git a/plugins/songwriting/skills/suno/reference/suno-drift-audit-ledger.md b/plugins/songwriting/skills/suno/reference/suno-drift-audit-ledger.md index b8626e8a7..ed25b92ad 100644 --- a/plugins/songwriting/skills/suno/reference/suno-drift-audit-ledger.md +++ b/plugins/songwriting/skills/suno/reference/suno-drift-audit-ledger.md @@ -14,7 +14,7 @@ false. | S8 | `lyrics.md:187` | (per #2233 item 4) | **Not yet audited** — cited by #2233 before any ledger existed | — | | S9 | `advanced.md:99` | (per #2233 item 4) | **Not yet audited** | — | | S10 | `power-tips.md:29` | Genre-fusion order encodes priority | **Audited** — demoted; anchor/accent hierarchy is attested, position-as-mechanism is not (#2351, 1.1.2) | 1.1.2 | -| S11 | `tips.md` timing cue | `~70%` effectiveness figure | **Unsourced** — basis recorded nowhere; flagged LOW-MEDIUM (#2266) | 1.1.1 | +| S11 | `tips.md` timing cue | `~70%` effectiveness figure | **Removed in 1.1.2** — no basis found in-repo (searched 2026-08-11, re-run 2026-08-12) or externally (2026-08-12: two `help.suno.com` articles read verbatim, two large community meta-tag references grepped; zero hits for the cue form or `70%`); technique retained, flagged LOW-MEDIUM; full search record kept in `tips.md` (#2266) | 1.1.2 | | S12 | `[Section]` tag rows | (per #2233 item 4) | **Not yet audited** | — | | S13 | `advanced.md` Duration slider | Control exists, is named "Duration slider", lives in the Create form, scoped to Web + V5.5 | **Audited — first-party** (, Jul 20 2026, fetched 2026-08-12) | 1.3.0 | | S14 | `advanced.md` Duration slider | Range 10s-6min, 5-second increments, Auto/Custom default pair | **LOW-MEDIUM** — writer-observed 2026-08-12 and independently stated by one community post; `help.suno.com` has no slider article as of 2026-08-12, and the Jack Righteous duration-slider guide declines to state a range | 1.3.0 | @@ -22,6 +22,8 @@ false. | S16 | `advanced.md` Creative Sliders — Audio Influence row + note | Audio Influence entry value is 25% in the cover-from-upload flow | **Writer-observed, off-ladder** — `writer-observed, single session (2026-08-12), n=1 — not externally corroborated`; no external corroboration attempted; the Extend and upload-as-seed entry values are unobserved | 1.3.0 | | S17 | `troubleshoot.md` "My bridge is missing / another section sang its lyrics" | Tag-only repeat section adjacent to a lyric-bearing section can be absorbed — the adjacent section's lyrics sing in the empty slot and that section is dropped | **Observed failure, off-ladder** — `writer-observed, single session (2026-08-12), n=1 — not externally corroborated`; adjacency is a candidate cause, not a demonstrated mechanism; tag-only before `[Outro]`/`[End]` untested | 1.3.0 | | S18 | `lyrics.md` "Line breaks cut both ways"; `tips.md` line-breaks entry | Short-line stacks over-separate (excess pauses, choppy delivery); prompt-layer join fixes it | **Split** — the line-break mechanism stays MEDIUM, unchanged; the failure edge and the join fix are `writer-observed, single session (2026-08-12), n=1 — not externally corroborated`, off-ladder | 1.3.0 | +| S19 | `voices.md` two-stage bootstrap (non-singers) + "make this voice public" toggle-default warning | Reported route: clone from speech, then reclone from the Suno-generated singing; the visibility toggle defaults on for every voice created | **LOW-MEDIUM** — single r/SunoAI post (u/Physical-Dress8460, posted 2026-06-30) plus its comment thread, read 2026-08-11; not multi-source consensus; untested here | 1.3.0 | +| S20 | `SKILL.md` Character budgets — lyrics field | Hard cap 5,000 chars (v4.5/v5/v5.5); ~3,000 remains the practical quality budget | **Re-verified 2026-07-18, position flipped since the 2026-05-10 pass** — the earlier "3,000" consensus conflated the v4-era hard cap with the quality threshold; third-party tester consensus only (hookgenius, aimusicapi 2026-07-03), no official Suno page states field limits | 0.4.1 | When a row moves, update this table and the plugin CHANGELOG in the same PR. @@ -32,3 +34,12 @@ Prior issues (#2233, #2266) cited `.work/songwriting-plugin-pilot/suno-drift/RESEARCH.md` as this ledger; that memory-tier path was never created, so absence claims were unfalsifiable until this file shipped (#2354). + +**The Reddit corpus was never closed; the note saying so was never read.** +1.1.2 and 1.1.3 both recorded r/SunoAI as unreachable ("the search tool +refuses `reddit.com`") and rated claims down accordingly, even though +`context/workflow-recipes.md` has said since 1.1.0 that a browser session +reaches it where search and direct fetch both fail. Three releases in a +row missed the route already on record here; 1.2.0 ran the pass on the +first try. Before rating anything below MEDIUM for want of Reddit, use +the browser route rather than concluding the corpus is closed. diff --git a/plugins/source-control/.claude-plugin/plugin.json b/plugins/source-control/.claude-plugin/plugin.json index e710d9399..35c347a56 100644 --- a/plugins/source-control/.claude-plugin/plugin.json +++ b/plugins/source-control/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "source-control", - "version": "0.55.21", + "version": "0.55.22", "description": "Git and GitHub delivery workflow: /commit (Conventional Commits + Co-authored-by trailer via safe heredoc mechanics), /pull-request (prep, create, CI monitoring, review-comment triage, merge, CI-log fetch), /babysit-prs (self-pacing fleet loop \u2014 safe by default; opt-in worker/autopilot tiers add gate-checked merge and thread resolution behind a deterministic Python engine), /babysit-loop (the loop-lane merge lane: a standing or drain loop that invokes babysit-prs per cycle, configured through repo-scoped babysit_loop_* keys on the layered source-control.md seam, with merge authority human-only until the target repo's tracked config adopts the lane, a gate-proven C2-mechanical baseline once adopted, and standing merge-rung raises binding from the team-tracked layer only \u2014 with one named exception, where an invocation line explicitly typing both the autopilot tier keyword and the dedicated raise argument --merge c3-this-run widens that single invocation's merge authority up to C3 behind a fresh independent frontier-tier resolver, while C4-structural and C5-untrusted-provenance stay unconditionally human-merge), /worktree (create, status, cleanup, audit for parallel-session isolation), /setup (check the effective commit-subject / PR-title convention merged across its config layers and the babysit-prs config, or apply \u2014 interview the repo and write the convention config to a chosen layer), and /resolve-conflicts (intent-first merge/rebase conflict resolution with a semantic-conflict sweep \u2014 never --abort). The commit-subject / PR-title convention is configurable via a source-control.md config written by a re-runnable setup skill, layered across a ~/.claude user-global file, the tracked team file, and a gitignored .claude/source-control.local.md personal overlay merged per key; Conventional Commits is the default when no convention is declared.", "author": { "name": "Melodic Software", diff --git a/plugins/source-control/CHANGELOG.md b/plugins/source-control/CHANGELOG.md index 8610feda6..8e7c450bf 100644 --- a/plugins/source-control/CHANGELOG.md +++ b/plugins/source-control/CHANGELOG.md @@ -3,6 +3,20 @@ All notable changes to the `source-control` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.55.22] + +### Changed + +- **`babysit-prs`'s flag documentation has one home.** The Guarded mutations section keeps the + operative invariants and per-tier mode selection plus one conditioned pointer; exact wrapper + flag documentation deduped into `skills/babysit-prs/reference/safety.md`, which first gained the + semantics it was missing (merge-form self-logins composition, the `--admin` capability bound, + the merge-gate evaluation set, the per-thread action vocabulary). No semantics changed. +- **Long files carry a `## Contents` index.** The 401-line README and 337-line + reference/review-discipline.md gained Contents sections; the heading-less 394-line + skills/setup/reference/apply-convention.md gained an orientation block with a grep recipe. + Progressive-disclosure audit, tier-mismatch and missing-toc treatments. + ## [0.55.21] ### Changed diff --git a/plugins/source-control/README.md b/plugins/source-control/README.md index 2dcecdb0e..15718e0f2 100644 --- a/plugins/source-control/README.md +++ b/plugins/source-control/README.md @@ -5,6 +5,27 @@ composable skills. Commit mechanics, the single-PR lifecycle, the tiered babysit fleet loop, worktree lifecycle management, convention setup, and merge-conflict resolution. +## Contents + +- [Skills](#skills) + - [`/source-control:commit`](#source-controlcommit) + - [`/source-control:pull-request`](#source-controlpull-request) + - [`/source-control:babysit-prs`](#source-controlbabysit-prs) + - [`/source-control:worktree`](#source-controlworktree) + - [`/source-control:setup`](#source-controlsetup) + - [`/source-control:resolve-conflicts`](#source-controlresolve-conflicts) +- [Hooks](#hooks) + - [`pr-body-linkage-gate`](#pr-body-linkage-gate) + - [`pr-linkage-mcp-gate`](#pr-linkage-mcp-gate) + - [`worktree-add-claim-gate`](#worktree-add-claim-gate) +- [Works in any repo](#works-in-any-repo) +- [Install](#install) +- [Configuration](#configuration) + - [Options reference](#options-reference) + - [How to set these](#how-to-set-these) + - [Upstream documentation](#upstream-documentation) +- [Security](#security) + ## Skills ### `/source-control:commit` diff --git a/plugins/source-control/reference/review-discipline.md b/plugins/source-control/reference/review-discipline.md index a85d70e6f..c3ecca26d 100644 --- a/plugins/source-control/reference/review-discipline.md +++ b/plugins/source-control/reference/review-discipline.md @@ -26,6 +26,12 @@ The deterministic companion scripts live beside this file: - `${CLAUDE_PLUGIN_ROOT}/scripts/babysit-readiness-gate.sh ` — mechanical under-decomposition gate (§2). +## Contents + +- [1. Evidence-based comment state](#1-evidence-based-comment-state) +- [2. Structured finding extraction](#2-structured-finding-extraction) +- [3. Per-finding D1–D7 verification gates](#3-per-finding-d1d7-verification-gates) + ## 1. Evidence-based comment state GitHub is the source of truth — not model memory, not prior-iteration state, not comment counts. diff --git a/plugins/source-control/skills/babysit-prs/SKILL.md b/plugins/source-control/skills/babysit-prs/SKILL.md index 840a57cea..53120e06d 100644 --- a/plugins/source-control/skills/babysit-prs/SKILL.md +++ b/plugins/source-control/skills/babysit-prs/SKILL.md @@ -149,34 +149,25 @@ That gate merges **only when every criterion holds**, the criteria and the safet ## Guarded mutations: deterministic gates, agent judgment The two mutation gates are invoked ONLY through their wrapper scripts, by the bundled `bin/`-path form, -never the bare command name nor the raw Python behind them. Each `source-control-babysit- …` spelled in the bullets below is that wrapper launched by its `bin/`-path form; the exact form is the single +never the bare command name nor the raw Python behind them. Each `source-control-babysit-` named in the bullets below is that wrapper launched by its `bin/`-path form; the exact form is the single home in [reference/safety.md](reference/safety.md). Both fail closed without `--allowed-owners`. -- **Merge readiness**. `source-control-babysit-merge owner/repo#N --allowed-owners - --self-logins @me,` (read-only; add `--merge --expected-head - ` to merge, and `--method ` when configured). `--self-logins` - exempts your own PRs from the unprotected-base hold **on the default branch only**: `@me` resolves to your gh login, plus any - `babysit_self_logins` extras (drop the trailing `,` when that value is empty). It gates on GitHub's own - `mergeStateStatus == CLEAN` plus explicit cross-checks (branch rules, review decision, - unresolved threads, check rollup keyed by check type and name, head match) and reports the - exact `blockers`. When `babysit_review_bot_logins` and `babysit_review_settle_minutes` are both - set, append `--review-bot-logins "" --review-settle-minutes ""` on every form: the - gate then holds a head that reviewer has not reviewed yet until the window elapses, because - `CLEAN` is reported throughout a re-review's latency and merging inside it merges past findings - that have not landed (safety.md, §Review-Settle Hold). Supply both or neither, either alone is - a usage error, never a silently inert flag. If the expected-head pin is missing or no longer matches the live head, the - gate refuses the merge; re-snapshot and reassess the new head instead of using - `--allow-unpinned-head`, the wrapper rejects that flag outright, so no unattended unpinned - merge exists. The pin is carried to GitHub's server-side match-head-commit guard. It refuses - a dependency-manager-authored PR absent `--allow-dependency` (held set: built-in dependabot/renovate - plus any `babysit_extra_dependency_manager_logins`, which you MUST append via - `--extra-dependency-manager-logins ""` when set, see safety.md's merge command forms, or - those extra bots are silently not held), refuses merge on an unprotected - base (zero required reviews and zero required contexts) for a non-self author, and for a self - author whenever that base is not the repository's default branch, a stack layer or any other - feature-onto-feature merge, where the default branch's required checks never governed the merge, - absent `--allow-unprotected`, never uses `--admin`, and cannot resolve threads, reply, or - force-push. React to `blockers`; do not bypass the gate. A `ready:false` immediately following a `ready:true` on the same expected head is often GitHub's own mergeability recompute lag. Re-run the read-only check once before treating it as a real block. **This gate's `ready` field is the sole authority for calling a PR merge-ready**, never the finding-classification gate's `READINESS_OK` ([reference/safety.md](reference/safety.md) "Two Gates, One Merge-Ready Authority"). +**Before composing either wrapper command, read [reference/safety.md](reference/safety.md), +"Guarded Mutation Wrappers", for the exact flag set.** That section is the single home for the +`bin/`-path form, every configured flag that must ride on a given form (self logins, extra bot +logins, the review-settle pair, extra dependency-manager logins), the pins and the refusals they +produce, the override flags that are never passed autonomously, and the per-thread `action` +vocabulary. Never reconstruct one of these commands from memory; a silently dropped flag is a +silently dropped guard. + +- **Merge readiness**. `source-control-babysit-merge` is the gate. Safe tier runs it read-only and + reports; `worker` and `autopilot` add `--merge --expected-head ` only on a + vetted head, and an enabled autopilot merge tier layers its own flags on + ([reference/safety.md](reference/safety.md)). When the expected-head pin is missing, or the + pinned sha no longer matches the live head, the wrapper refuses: re-snapshot and reassess the new + head instead of using `--allow-unpinned-head`. React + to the reported `blockers`; do not bypass the gate, and never reach for one of its override flags + on an unattended path. **This gate's `ready` field is the sole authority for calling a PR merge-ready**, never the finding-classification gate's `READINESS_OK` ([reference/safety.md](reference/safety.md) "Two Gates, One Merge-Ready Authority"). - **Once ready, stop.** When the gate proves a PR ready (safe mode) or its merge is deferred to a human (Pinned-Command Degradation, [reference/safety.md](reference/safety.md)), report that @@ -184,43 +175,27 @@ home in [reference/safety.md](reference/safety.md). Both fail closed without `-- [reference/orchestration.md](reference/orchestration.md)) governs this gate-completion step exactly as it governs a worker's turn. Proving readiness is never a license to arm a watch. -- **Thread resolution**. `source-control-babysit-resolve-thread owner/repo#N --allowed-owners - --extra-bot-logins --self-logins @me,` (lists by - default; add `--resolve`). By default it touches only bot-authored threads (structural - `__typename == "Bot"` or the `[bot]` login suffix, no hardcoded identity list) and never a human - thread; `--extra-bot-logins` extends that set with the configured non-structural bot accounts (dropping it silently reclassifies their threads as human), and `--self-logins` rides on every form too, omitting it lets the worker's OWN bot-thread reply flip `botOnly` false and strand the thread outside every resolution scope (safety.md). In worker tier pass `--autonomous`, which - resolves only threads GitHub marks `isOutdated`, each pinned via `--expected-comment-count` and - `--expected-last-updated`. Those pins enforce comment-state only. They block a thread whose - comment count or latest comment-edit timestamp drifted after vetting. The worker must additionally - confine resolves to threads already outdated in the PRE-push snapshot - ([reference/orchestration.md](reference/orchestration.md)); that pre-push-outdated rule is agent - discipline, not machine-enforced, so a thread a worker's own push merely displaced (`isOutdated` - flipped while both comment pins still match) is still resolvable, the machine-enforced fix for - that displacement bypass is tracked in #571. In autopilot pass `--resolve --include-human` for - threads the agent has addressed; the script still cannot merge, reply, or dismiss reviews. Never - treat exit code 0 alone as proof a specific thread was resolved. Always parse the per-thread JSON - `action` field (`resolved` vs `skipped-*` / `refused-stale-pin` / `resolve-failed`) and the - `resolvedCount`/`eligibleCount` summary before reporting or re-checking the merge gate. `--resolve - --thread-id` without matching `--expected-comment-count` and `--expected-last-updated` (or an - explicit `--allow-unpinned-thread` override) is refused before anything is fetched or resolved. +- **Thread resolution**. `source-control-babysit-resolve-thread` is the gate, and the mode is the + tier's: safe lists only and never resolves; worker resolves `--autonomous`, confined further to + threads already outdated in the PRE-push snapshot + ([reference/orchestration.md](reference/orchestration.md)), a rule that is agent discipline rather + than machine-enforced; autopilot widens to threads it has addressed, human threads included. The + wrapper touches only bot-authored threads unless that widening is in play, and it can never merge, + reply, or dismiss reviews. Never treat exit code 0 alone as proof a specific thread was resolved. + Always parse the per-thread JSON `action` field and the run summary before reporting or + re-checking the merge gate. - **Independent resolution**. `--independent-resolver` is a THIRD mode, parallel to `--autonomous` and never a relaxation of it. `isOutdated` means the referenced code moved, so on a prose or documentation PR a genuinely addressed finding never becomes outdated and the worker guard refuses forever. This mode is dispatched to a FRESH context that is not the merging worker and did not author the fix, that independence is what replaces `isOutdated` as the anti-self-certification - property, and the script cannot verify it, which is why the other half is machine-checked. Pass - one `--thread-id` (bulk refused in every mode here, list included), both pins, and - `--disposition fixed|deferred|incorrect` with its own evidence flag: `--fix-commit ` must be - reachable from the PR head, `--tracker-item ` must exist and be open, `--counter-evidence - ` must already appear in a reply on the thread posted by someone OTHER than the thread's - opener. The script validates evidence against the world, not against the claim, in list mode too - anything missing, unparsable, or unverifiable refuses with its own `refused-*` action rather - than warning, and only a confirmed HTTP 404 is read as the world saying no. A thread carrying - more than one finding is refused outright (`skipped-multi-finding-thread`) and escalates: one - disposition cannot clear a thread whose other findings nothing validated. Bot-only and the - security/P1 bright line still hold, and `--autonomous`, `--include-human`, and - `--allow-unpinned-thread` are all refused alongside it. Who dispatches this mode, the per-finding + property, and the script cannot verify it, which is why the other half is machine-checked: one + pinned thread per call, and a disposition whose evidence the script validates against the world + rather than against the claim. A thread carrying more than one finding is refused outright + (`skipped-multi-finding-thread`) and escalates: one disposition cannot clear a thread whose other + findings nothing validated. Bot-only and the security/P1 bright line still hold. Who dispatches + this mode, the per-finding D7.5 ledger owed before the wrapper is called, the fresh-pin rule, and the fail-closed fallback for every bound it cannot cross are the single home in [reference/independent-resolution.md](reference/independent-resolution.md). diff --git a/plugins/source-control/skills/babysit-prs/reference/safety.md b/plugins/source-control/skills/babysit-prs/reference/safety.md index b6258a446..c65ec224d 100644 --- a/plugins/source-control/skills/babysit-prs/reference/safety.md +++ b/plugins/source-control/skills/babysit-prs/reference/safety.md @@ -439,9 +439,22 @@ auto-mode safety classifier and blocks the call before the wrapper runs. - Both wrappers **fail closed**: invoked without `--allowed-owners`, they exit `3` and refuse to act. The read-only forms are `source-control-babysit-merge owner/repo#42 --allowed-owners - ` (merge-readiness gate) and `source-control-babysit-resolve-thread + --self-logins @me,` (merge-readiness gate) and + `source-control-babysit-resolve-thread owner/repo#42 --allowed-owners --extra-bot-logins --self-logins @me,` (thread list). +- **What the merge gate actually evaluates.** It gates on GitHub's own `mergeStateStatus == CLEAN` + plus explicit cross-checks of its own: branch rules, review decision, unresolved threads, the + check rollup keyed by check type and name, and head match. It reports the exact `blockers` list. + React to those blockers; never bypass the gate. One reading caveat: a `ready: false` immediately + following a `ready: true` on the same expected head is often GitHub's own mergeability recompute + lag, so re-run the read-only check once before treating it as a real block. +- **`--self-logins @me,` rides on every merge form too**, read-only and mutating + alike. `@me` resolves to your own `gh` login and the `babysit_self_logins` extras follow it; drop + the trailing `,` when that value is empty. On the merge gate this flag is what + exempts your own PRs from the unprotected-base hold, and only **on the default branch** (see the + unprotected-base bullet below). Without it your own PR is classified as a non-self author and + held. - **`--extra-bot-logins ` rides on every resolve-thread form**, listing and mutating alike, whenever `babysit_extra_bot_logins` is configured. Bot classification is what decides which threads the resolver may touch at all, and structural detection cannot see a @@ -475,14 +488,20 @@ auto-mode safety classifier and blocks the call before the wrapper runs. worker itself opened stays out of scope even after a bot replies to it (`review-discipline.md` D7.5 forbids resolving your own threads). Omit the flag only when `babysit_self_logins` is unset. - The merge wrapper mutates only with `--merge --expected-head --method - `, and rejects `--allow-unpinned-head` outright — there is no unpinned merge. The - expected-head pin semantics live in `SKILL.md`; do not re-derive them here. + `, and rejects `--allow-unpinned-head` outright — there is no unpinned merge. A + missing pin, or a pin that no longer matches the live head, refuses the merge: re-snapshot and + reassess the new head rather than reaching for an override, so no unattended unpinned merge + exists. The pin is carried through to GitHub's own server-side match-head-commit guard, so the + refusal holds on GitHub's side as well as in the wrapper. +- The merge wrapper never uses `--admin`, and it cannot resolve threads, post replies, or + force-push. It merges or it refuses. - The merge CLI refuses a dependency-manager-authored PR absent `--allow-dependency`, and refuses to merge on an unprotected base — zero required reviews AND zero required status contexts — when the PR author is not one of ``, or when a `` author's base is not the repository's default branch, absent `--allow-unprotected`. The self exemption covers the solo-owner repository whose default branch carries no rules; it does not cover a merge onto - another branch, where the default branch's required checks never ran. Both + another branch (a stack layer, or any other feature-onto-feature merge), where the default + branch's required checks never governed the merge. Both overrides are human decisions, never passed autonomously. The held dependency-manager set is the built-in dependabot/renovate bots plus, when `babysit_extra_dependency_manager_logins` is configured (non-empty, not a literal unexpanded token), the logins appended via @@ -498,7 +517,12 @@ auto-mode safety classifier and blocks the call before the wrapper runs. - The resolve wrapper's mutating forms are `--autonomous --resolve` (worker tier, constrained by the pre-push-outdated rule in `orchestration.md`), `--resolve --include-human` (autopilot's addressed-thread widening), and `--independent-resolver --resolve` (the evidence-gated third - mode below). + mode below). `--autonomous` admits only threads GitHub marks `isOutdated`. The worker must + additionally confine its resolves to threads already outdated in the PRE-push snapshot; that + pre-push-outdated rule is agent discipline, not machine-enforced, so a thread a worker's own push + merely displaced (`isOutdated` flipped while both comment pins still match) is still resolvable by + the script. The machine-enforced fix for that displacement bypass is tracked in #571. Under + `--resolve --include-human` the script still cannot merge, post replies, or dismiss reviews. - **`--independent-resolver` is a third mode, not a widening of `--autonomous`.** `--autonomous` admits only `isOutdated` threads, and `isOutdated` means the referenced code MOVED — so on a prose or documentation PR, where a finding is normally addressed by rewriting elsewhere in the @@ -567,14 +591,21 @@ auto-mode safety classifier and blocks the call before the wrapper runs. either pin, so a reply added or a comment edited after vetting blocks that thread instead of being silently swept in. A thread id alone is never enough (the live thread is re-fetched at execution time), and a comment count alone is never enough (an edit leaves the count - unchanged). + unchanged). The pins enforce **comment state only**: drift in the comment count or the latest + comment-edit timestamp blocks the thread, and nothing else about the thread is pinned. A + `--resolve --thread-id` missing either pin is refused before anything is fetched or resolved, + unless the caller supplies the explicit `--allow-unpinned-thread` override, which belongs to no + unattended path (`--independent-resolver` refuses it outright). - **Parse JSON, never trust exit codes alone.** Both wrappers emit structured JSON; confirm what actually happened from each target's `action` field. For a resolve, exit `10` is a reliable "nothing was resolved" signal (a stale pin refused, the thread was skipped, or the mutation failed), but exit `0` is not by itself proof of success for a given thread — it also covers list mode and a multi-thread run where some other thread resolved while this one did not. Treat a thread as cleared only when its own entry shows `"action": "resolved"`, and a merge as - performed only when the merge output's `action` field says so. + performed only when the merge output's `action` field says so. The resolve action vocabulary is + `resolved` against `skipped-*`, the `refused-*` family (`refused-stale-pin` and the evidence + refusals above), and `resolve-failed`; read the run's `resolvedCount`/`eligibleCount` summary + alongside the per-thread entries before reporting or re-checking the merge gate. ### Lane-pinned merge authorization: report, don't re-pin diff --git a/plugins/source-control/skills/setup/reference/apply-convention.md b/plugins/source-control/skills/setup/reference/apply-convention.md index 4591ec304..d8447fe3d 100644 --- a/plugins/source-control/skills/setup/reference/apply-convention.md +++ b/plugins/source-control/skills/setup/reference/apply-convention.md @@ -5,6 +5,29 @@ The full write path for the convention config: target-layer selection, the non-i post-write verification, and the effective-merge report. Loaded from [SKILL.md](../SKILL.md) "`apply` (idempotent)" — the hub owns *when* this runs; this spoke owns *how*. +## Contents + +This reference carries one heading break in the body: +[Neutral convention SSOT](#neutral-convention-ssot-convention_source) at the end. Everything +above it is the linear `apply` interview, walked as bolded numbered steps (0 through 7) rather +than headings. Find a step directly with: + +```shell +grep -n '^[0-9]\. \*\*' "${CLAUDE_PLUGIN_ROOT}/skills/setup/reference/apply-convention.md" +``` + +- Layer selection (`layer=`) and the non-interactive `subject_pattern=` write: immediately below, + before the interview starts +- Step 0, anchor at the repo root +- Step 1, read the current config first +- Step 2, infer before asking +- Step 3, interview, one decision at a time +- Step 4, settle the remaining fields +- Step 5, write the config +- Step 6, verify the write, per layer +- Step 7, report the new effective merge +- [Neutral convention SSOT (`convention_source`)](#neutral-convention-ssot-convention_source) + **Pick the target layer first.** `layer=` selects it; `team` is the default when the argument is absent, since a convention is a team artifact until someone says otherwise. diff --git a/plugins/work-items/.claude-plugin/plugin.json b/plugins/work-items/.claude-plugin/plugin.json index fe76281e2..776f71cfa 100644 --- a/plugins/work-items/.claude-plugin/plugin.json +++ b/plugins/work-items/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "work-items", - "version": "0.39.31", + "version": "0.39.32", "description": "Manages development work items through a provider-neutral tracker seam that ships with the plugin (bundled dispatcher plus github, local-markdown, jira, gitea, and linear adapters; seam plugin-dir canonical, adapters consumer-local-first): dashboard, taxonomy-labeled creation, a race-safe assignee-plus-lease claim protocol, recurring-schedule checks, TODO scanning, stale-lease auditing, plan decomposition into vertical-slice items, a macro-journey router over spec containers (rollup, per-container execution shape, next-step routing), raw-intake triage (issues and unsolicited PRs through raw, verified, briefed, autonomous-eligible states), plus the two work-items loop lanes of the loop-lane convention: a self-paced autonomous work-loop drain (work-class admission gate, adaptive item cap, PR-only) and an attended attend-queue escalation lane. The re-runnable setup skill binds the provider (.work-item-tracker.json), seeds the recurring-schedule seam (.github/recurring-schedule.json), and remaps canonical role labels.", "author": { "name": "Melodic Software", diff --git a/plugins/work-items/CHANGELOG.md b/plugins/work-items/CHANGELOG.md index a81dce6a4..239f8bd75 100644 --- a/plugins/work-items/CHANGELOG.md +++ b/plugins/work-items/CHANGELOG.md @@ -3,6 +3,18 @@ All notable changes to the `work-items` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.39.32] + +### Changed + +- **Every hub reaches its shared reference files directly.** The setup, track, triage, and work + hubs gained direct conditioned pointers to the reference files their spokes require + (tracker-seam, capability-tier-labels, label-taxonomy, issue-conventions, agent-brief, + standing-item-preconditions, work-class-labels), removing the audited 2-hop required-reading + chains; track's label-taxonomy condition also names `list --category`. The 769-line tracker + CONTRACT.md and 422-line github adapter README gained `## Contents` indexes. Behavior unchanged. + Progressive-disclosure audit, deep-nesting and missing-toc treatments. + ## [0.39.31] ### Changed diff --git a/plugins/work-items/skills/setup/SKILL.md b/plugins/work-items/skills/setup/SKILL.md index a6c9f196b..903e49bca 100644 --- a/plugins/work-items/skills/setup/SKILL.md +++ b/plugins/work-items/skills/setup/SKILL.md @@ -124,7 +124,10 @@ Example (`github`; `local-markdown` adds `"storage_dir": ".work-items"`): `check` inspects and reports; it writes nothing. Read [reference/check.md](reference/check.md) when invoked with `check` or with no action, and again at the start of `apply`, which runs the same probes first: it owns the probe order, every PASS/FAIL/INFO row, and the remediation line each FAIL -prints. `apply` below consumes those probe results and never re-derives them. +prints. `apply` below consumes those probe results and never re-derives them. The `jq` and +tracker-binding entry gates that check.md's probe 1 tests are defined in +[`${CLAUDE_PLUGIN_ROOT}/reference/tracker-seam.md`](${CLAUDE_PLUGIN_ROOT}/reference/tracker-seam.md) +"entry-point presence checks"; read it for what each gate enforces and its remediation. ## `apply` (idempotent) @@ -183,9 +186,11 @@ unambiguous; ask only where an item genuinely needs the user. It discovers missing canonical members and provisions them when authorized. When any member is still missing after this pass, stop. Triage and the work-loop admission gate cannot operate correctly. 4. **Migrate the capability-tier label axis.** Run the procedure in - [reference/capability-tier-axis-migration.md](reference/capability-tier-axis-migration.md). When the - canonical member is still missing after this pass, stop. Triage cannot stamp frontier-tier quota - guard and the work-loop reader fails closed to general tier. + [reference/capability-tier-axis-migration.md](reference/capability-tier-axis-migration.md), which + provisions the canonical `capability-tier: frontier` member defined in + [`${CLAUDE_PLUGIN_ROOT}/reference/capability-tier-labels.md`](${CLAUDE_PLUGIN_ROOT}/reference/capability-tier-labels.md). + When the canonical member is still missing after this pass, stop. Triage cannot stamp frontier-tier + quota guard and the work-loop reader fails closed to general tier. 5. **Backfill legacy frontier-tier body stamps.** Run the procedure in [reference/capability-tier-backfill.md](reference/capability-tier-backfill.md). This pass is load-bearing on upgrade (#1716): items already triaged with only a body prose frontier-tier stamp diff --git a/plugins/work-items/skills/track/SKILL.md b/plugins/work-items/skills/track/SKILL.md index 32e28e307..3f3a3cc85 100644 --- a/plugins/work-items/skills/track/SKILL.md +++ b/plugins/work-items/skills/track/SKILL.md @@ -30,6 +30,17 @@ actions below in particular: every query. When a role defaults because the file or entry is absent, warn loudly rather than substituting silently; a present malformed/empty/non-string value is a hard stop. +`add` and `recheck` also draw on reference files the seam doc above does not itself carry: + +- [`${CLAUDE_PLUGIN_ROOT}/reference/label-taxonomy.md`](${CLAUDE_PLUGIN_ROOT}/reference/label-taxonomy.md): + the 8-group label structure `add` validates against and `list --category` filters by. +- [`${CLAUDE_PLUGIN_ROOT}/reference/issue-conventions.md`](${CLAUDE_PLUGIN_ROOT}/reference/issue-conventions.md): + the title convention `add` applies. +- [`${CLAUDE_PLUGIN_ROOT}/reference/agent-brief.md`](${CLAUDE_PLUGIN_ROOT}/reference/agent-brief.md): + the brief template `add --agent-ready` uses instead of the default body. +- [`${CLAUDE_PLUGIN_ROOT}/reference/standing-item-preconditions.md`](${CLAUDE_PLUGIN_ROOT}/reference/standing-item-preconditions.md): + the precondition `recheck` evaluates before advancing dates or closing the associated item. + ## Scope `track` is the centralized, concurrent-safe backlog-CRUD surface: create, claim, close, list, diff --git a/plugins/work-items/skills/triage/SKILL.md b/plugins/work-items/skills/triage/SKILL.md index 0dd0369a7..4a621b469 100644 --- a/plugins/work-items/skills/triage/SKILL.md +++ b/plugins/work-items/skills/triage/SKILL.md @@ -43,9 +43,15 @@ Evaluate **raw intake**, any untriaged item carrying the raw marker, whoever aut **Classification vocabulary.** Autonomous routing uses the `work-class:` label axis (`read-only`, `mechanical`, `scoped`, `structural`, `untrusted-provenance`). Human-readable aliases of the -autonomy plugin's `C1`–`C5` contract. Retired scaffolding: `T1`/`T2`/`T3` and +autonomy plugin's `C1`–`C5` contract. Canonical members and migration status: +[`${CLAUDE_PLUGIN_ROOT}/reference/work-class-labels.md`](${CLAUDE_PLUGIN_ROOT}/reference/work-class-labels.md); +read it before the work-class pairing step below applies a member. Retired scaffolding: `T1`/`T2`/`T3` and `simple`/`medium`/`complex` are not classification metadata here; loop-lane status lines may -still report simple/medium/complex counts as lane-local telemetry only. +still report simple/medium/complex counts as lane-local telemetry only. The separate frontier +capability-tier stamp (`capability-tier: frontier`) has its own canonical member and migration +status in +[`${CLAUDE_PLUGIN_ROOT}/reference/capability-tier-labels.md`](${CLAUDE_PLUGIN_ROOT}/reference/capability-tier-labels.md); +read it before applying that stamp in step 5. **Raw intake is defined by triage state, not authorship.** An item is raw intake when it is untriaged. Unlabeled, or carrying the raw marker (`status:needs-triage` / `priority:needs-triage`, whichever axis the repo files it under). Regardless of who authored it. External bug reports, incoming feature requests, and unsolicited PRs are the common sources, but a **team-authored self-observation / dogfood issue** filed with only the raw marker ([`${CLAUDE_PLUGIN_ROOT}/reference/dogfood-filing.md`](${CLAUDE_PLUGIN_ROOT}/reference/dogfood-filing.md)) is raw intake too: it carries no routing decision yet, surfaces in the same attention view, and needs the same evaluation (priority normalization, tier routing, brief drafting). The boundary is *untriaged vs. already-triaged*, never *external vs. team-authored*. diff --git a/plugins/work-items/skills/work/SKILL.md b/plugins/work-items/skills/work/SKILL.md index f6091cb5c..101cae1d8 100644 --- a/plugins/work-items/skills/work/SKILL.md +++ b/plugins/work-items/skills/work/SKILL.md @@ -131,7 +131,11 @@ preflight has resolved and before the first tracker query: it owns the query for ladder above, the in-flight exclusion that keeps a candidate with an open linked PR out of the frontier tiers, the recurring-issue cross-reference, and the standing-item precondition gate that decides whether a recurring candidate is eligible at all. Step 3 below assumes one surviving -candidate from it. +candidate from it. That precondition gate reads a schedule row's `precondition` field per +[`${CLAUDE_PLUGIN_ROOT}/reference/standing-item-preconditions.md`](${CLAUDE_PLUGIN_ROOT}/reference/standing-item-preconditions.md), +and the frontier-tier query excludes items by the resolved human-gated role label per +[`${CLAUDE_PLUGIN_ROOT}/reference/label-taxonomy.md`](${CLAUDE_PLUGIN_ROOT}/reference/label-taxonomy.md) +"Canonical roles"; read both before relying on either exclusion. ### Step 3: Present and confirm diff --git a/plugins/work-items/tools/work-item-tracker/CONTRACT.md b/plugins/work-items/tools/work-item-tracker/CONTRACT.md index 7d91c5c38..135c8c82f 100644 --- a/plugins/work-items/tools/work-item-tracker/CONTRACT.md +++ b/plugins/work-items/tools/work-item-tracker/CONTRACT.md @@ -1,5 +1,29 @@ # Work-item tracker seam — contract +## Contents + +- [Prerequisites](#prerequisites) + - [Degradation without `gh` (cloud / MCP-only sessions)](#degradation-without-gh-cloud--mcp-only-sessions) +- [Setup (binding file)](#setup-binding-file) +- [Verbs (core public surface)](#verbs-core-public-surface) +- [Adapter contract](#adapter-contract) +- [Adapter resolution](#adapter-resolution) +- [JSON output contract](#json-output-contract) +- [ID grammar](#id-grammar) +- [Exit codes](#exit-codes) +- [Lease protocol](#lease-protocol) +- [Containers and state](#containers-and-state) + - [Multi-provider topology — the role-split model (recorded decision, not yet built)](#multi-provider-topology--the-role-split-model-recorded-decision-not-yet-built) +- [Capabilities manifest](#capabilities-manifest) + - [Contract-version handshake](#contract-version-handshake) +- [Identity routing (GitHub adapter)](#identity-routing-github-adapter) +- [local-markdown adapter](#local-markdown-adapter) + - [Branch, worktree, and lease confinement](#branch-worktree-and-lease-confinement) +- [jira adapter](#jira-adapter) +- [linear adapter](#linear-adapter) +- [gitea adapter](#gitea-adapter) +- [Conformance](#conformance) + Provider-neutral CLI contract for work-item tracker operations. Skills and scripts call the core dispatcher (`work-item-tracker.sh`) only; the bound provider adapter executes the operation. The seam ships bundled with the `work-items` plugin and resolves plugin-dir diff --git a/plugins/work-items/tools/work-item-tracker/adapters/github/README.md b/plugins/work-items/tools/work-item-tracker/adapters/github/README.md index 7e2ba14ac..6c0b7ae7d 100644 --- a/plugins/work-items/tools/work-item-tracker/adapters/github/README.md +++ b/plugins/work-items/tools/work-item-tracker/adapters/github/README.md @@ -1,5 +1,21 @@ # GitHub adapter — operations reference +## Contents + +- [Available `--json` fields](#available---json-fields) +- [Resolve item ID](#resolve-item-id) +- [List items](#list-items) +- [Search items](#search-items) +- [View item](#view-item) +- [List item comments](#list-item-comments) +- [Close item](#close-item) +- [Edit labels / assignees](#edit-labels--assignees) +- [Comment on item / edit a comment](#comment-on-item--edit-a-comment) +- [PR closing-keyword mechanics](#pr-closing-keyword-mechanics) +- [Open linked PRs](#open-linked-prs) +- [Aggregate / count (dashboard + hygiene)](#aggregate--count-dashboard--hygiene) +- [Gotchas](#gotchas) + Concrete `gh` mechanics for the `/work-items` skill's **non-coordination** operations against the GitHub provider. Coordination (create / claim / lease / link / frontier) runs through the seam verbs (`work-item-tracker.sh `, see `../../CONTRACT.md`); the operations below — diff --git a/prompts/loops/loop-lane-profile-claude-code-plugins.md b/prompts/loops/loop-lane-profile-claude-code-plugins.md index 58d05d905..30997cf33 100644 --- a/prompts/loops/loop-lane-profile-claude-code-plugins.md +++ b/prompts/loops/loop-lane-profile-claude-code-plugins.md @@ -8,7 +8,12 @@ worked example of what a completed profile looks like. ## Contents - [Variable values](#variable-values) + - [Tier is not the rung](#tier-is-not-the-rung) - [Ready to paste](#ready-to-paste) + - [Worker lane — launch from a checkout of the repo](#worker-lane--launch-from-a-checkout-of-the-repo) + - [Merge lane — any machine except the attended one](#merge-lane--any-machine-except-the-attended-one) + - [Attended queue — melo-desk-001](#attended-queue--melo-desk-001) + - [Parked-decision burn-down — melo-desk-001, after the queue drains](#parked-decision-burn-down--melo-desk-001-after-the-queue-drains) ## Variable values diff --git a/prompts/loops/loop-lane-prompts.md b/prompts/loops/loop-lane-prompts.md index 28d338a0c..a252679cc 100644 --- a/prompts/loops/loop-lane-prompts.md +++ b/prompts/loops/loop-lane-prompts.md @@ -29,6 +29,22 @@ claims it, that is a gap to fix here, not a population to ignore. | Expired claims / leases | `/work-items:track audit`, run manually — **no scheduled sweep exists** | | Lane telemetry issues | Lane infrastructure — excluded from every population by construction | +## Contents + +- [Variables](#variables) +- [Per-repository profile](#per-repository-profile) +- [Adopting a new repository](#adopting-a-new-repository) +- [How to inject these](#how-to-inject-these) +- [Topology rules](#topology-rules) +- [Models](#models) +- [Concurrent workers on one repository](#concurrent-workers-on-one-repository) +- [1 — Worker lane](#1--worker-lane) +- [2 — Merge lane](#2--merge-lane) +- [3 — Attended queue](#3--attended-queue) +- [3b — Parked-decision burn-down (attended, on demand)](#3b--parked-decision-burn-down-attended-on-demand) +- [Known gaps that outlive any one repository](#known-gaps-that-outlive-any-one-repository) +- [Filled profiles](#filled-profiles) + ## Variables Replace every `{{...}}` occurrence in the block you are pasting.