diff --git a/.agents/skills/clue-analysis/skill.md b/.agents/skills/clue-analysis/skill.md index b3e664d..eeb3485 100644 --- a/.agents/skills/clue-analysis/skill.md +++ b/.agents/skills/clue-analysis/skill.md @@ -1,6 +1,6 @@ --- cliewen-skill: true -version: 0.24.1 +version: 0.26.0 --- diff --git a/.agents/skills/clue-delta/references/challenge-commitments.md b/.agents/skills/clue-delta/references/challenge-commitments.md new file mode 100644 index 0000000..24b1f3d --- /dev/null +++ b/.agents/skills/clue-delta/references/challenge-commitments.md @@ -0,0 +1,7 @@ +## Challenge a consequential commitment + +Before a consequential commitment, challenge it where the reviewer will read it: in the plan's prose for a plan, in `proposal.md` for a change. Name the assumption most likely to undermine the work, a credible alternative course, the cheapest useful test of that assumption, and the result that would stop or revise the work. Then ask what an implementation could look like that met every criterion and still failed the person the work is for — that is the failure a criterion-to-test thread cannot catch, because one author usually writes the criterion, its implementation, and its test in one sitting. + +A commitment is consequential when being wrong would cost more than finding out first: adopting or revising a plan's promise, starting a milestone whose approach is unsettled, choosing between credible courses in a decision, or a change to what adopters receive. Route first: simple work is never consequential, even when it touches a shipped surface. Work carrying out a course already challenged and understood, and work that can be undone within the same change at no more cost than the challenge, also proceed without a challenge and without a note explaining its absence. + +The proportionality limit is part of the rule, not an exemption from it: a challenge demanded of everything is written by habit, and a challenge written by habit is the confident, unexamined text this rule exists to interrupt. No prototype is ever universally required; a small path across the consequential boundaries is warranted only where the architecture is materially uncertain, and a milestone may deliver decision-changing evidence instead of a feature. Cite applicable repository experience when challenging assumptions, and treat it as evidence to reassess against the case in hand rather than as settled authority. diff --git a/.agents/skills/clue-delta/references/change-loop.md b/.agents/skills/clue-delta/references/change-loop.md index 76b1bb4..8d2af75 100644 --- a/.agents/skills/clue-delta/references/change-loop.md +++ b/.agents/skills/clue-delta/references/change-loop.md @@ -2,12 +2,20 @@ Use when the user chooses the full Cliewen loop recommended for accepted-contract change. Simple work is recommended before this skill and does not invoke it. Apply [Decision records](decision-records.md), [Repository-local conventions](repository-local-conventions.md), and [Durable work state](durable-work-state.md) throughout the loop. -1. **Branch:** Follow the review boundary, get the next CH identity with `clue id next CH`, and name the branch `ch-xxx-slug` with that identity. The command follows the ledger's tracked coordination mode. When it warns that allocation is local and contributors may work in parallel clones or worktrees, stop and either serialize allocation on the integration branch or have a maintainer enable Git coordination with `clue id coordinate` before contributors branch. A contributor given a preallocated identity runs `clue id sync`, uses that reservation, and never allocates independently from a stale local ledger. If remote allocation fails, do not guess, reuse, or edit the number by hand; retry or sync the allocator's permanent claims. Coordination settings live in `.clue/id-coordination.yaml`, not in the ledger; commit both after `clue id coordinate`, and treat a merge conflict in that file as the user's decision about which remote the team meant, never yours to resolve. Never re-point an established repository at a different remote. When a command reports that Git's union merge combined the ledger, the identities are intact: run `clue id repair`, or let the next command that saves the ledger rewrite it, and never hand-edit an append-only log. If two artifacts hold one identity, allocate a fresh one for the later artifact and update its references rather than renumbering either by hand. +1. **Branch:** Follow the review boundary, get the next CH identity with `clue id next CH`, and name the branch `ch-xxx-slug` with that identity. + - The command follows the ledger's tracked coordination mode. When it warns that allocation is local and contributors may work in parallel clones or worktrees, stop and either serialize allocation on the integration branch or have a maintainer enable Git coordination with `clue id coordinate` before contributors branch. A contributor given a preallocated identity runs `clue id sync`, uses that reservation, and never allocates independently from a stale local ledger. If remote allocation fails, do not guess, reuse, or edit the number by hand; retry or sync the allocator's permanent claims. + - Coordination settings live in `.clue/id-coordination.yaml`, not in the ledger; commit both after `clue id coordinate`, and treat a merge conflict in that file as the user's decision about which remote the team meant, never yours to resolve. Never re-point an established repository at a different remote. + - When a command reports that Git's union merge combined the ledger, the identities are intact: run `clue id repair`, or let the next command that saves the ledger rewrite it, and never hand-edit an append-only log. If two artifacts hold one identity, allocate a fresh one for the later artifact and update its references rather than renumbering either by hand. 2. **Propose:** Create `/changes/CH-xxx-slug/`, commit and push it before implementation, and open the draft PR under the review boundary: - `proposal.md` states what and why; its frontmatter `links` names the real plan item it serves or explicitly declares the change plan-less. - `tasks.md` is an ordered `- [ ]` checklist with dependencies first and at most one nested level. Mark an infeasible task `[-]` with its reason on the same line, whenever it is marked. A behavior-changing task names the acceptance-criterion IDs it serves; if none exists, add the criterion before implementation. Tests trace to criteria, never transient tasks. - - `open-questions.md` records blocking questions. When one appears, write it and stop; the human answer becomes a decision record. + - `open-questions.md` records blocking questions. When one appears, write it and stop; record the human answer as a decision only when it is future-shaping. - A human may opt into a spec-first pause after Propose. Record the pause in `tasks.md`, report briefly what the proposal says and what implementation involves, and ask whether implementation should begin — the proposal is already committed, pushed, and visible on the draft PR. Stop until the human directs work to continue; otherwise proceed directly to Implement. -3. **Implement:** Update the permanent corpus. Before and after implementation, assess documentation impact: keep the required architecture and design overviews current when their structure or cross-cutting behaviour changes, update the relevant capability design or general design document when it answers a reader's question, and link rather than duplicate. State in the change or pull-request handoff which durable documentation changed, or why none was needed; do not create a permanent change-history document. Architecture owns actors, boundaries, and durable technology choices; `docs/design/README.md` owns cross-cutting flows and patterns; a capability's `design.md` owns local detail. Draft a missing overview from repository evidence, and ask the human only when a material boundary or intent remains unclear. Use Mermaid when a diagram materially clarifies a relationship, boundary, or flow; retain SVG only when Mermaid is inadequate. A relevant new or materially revised ADR or IDR links to the affected overview. Capabilities own README, criteria, and design files. Write criteria as Gherkin tagged with their canonical `-[lowercase-suffix]` identity; every new or materially revised criterion declares `Test-type: Unit|Integration|E2E|Performance|Human` on the first line of its scenario body and gets focused positive and negative evidence in that class (or records `(single-direction)` when only one direction exists). `Human` needs no code evidence — the acceptance brief's criteria line is its proof; use it for a criterion deliberately verified by human judgment, never as a placeholder for a test not written. A criterion genuinely not yet proven carries `@draft` on its tag line instead, exempting only that criterion from the active-file test requirement — the capability itself does not need to stay `draft` because one criterion is unproven. Every test declares exactly one purpose: the criterion ID, `Unit`, `Sanity`, or `Arch`, using framework tags where available and the normalized test-name prefix in Go; AC evidence also carries its declared test type and direction. On the JVM, all three evidence parts attach to the same Java or Kotlin executable through literal JUnit method tags or the stable `test[lowercase-suffix]__` name; class tags, comments, and unrelated methods cannot supply missing parts. When a criterion's meaning changes, retire it with `@retired`, keep the tombstone, mint a new ID, and remove or retag its tests. +3. **Implement:** + - Before starting or resuming work for a milestone, assess whether its plan still serves the goal, the milestone remains wanted and achievable, and the remaining dependencies and order still hold. Repeat the assessment when new evidence challenges the campaign. A passing assessment needs no record. When it fails, write the mismatch and options in `open-questions.md` and pause affected work for human direction. After direction, declare the selected revision in the plan; record it only when the selected course is future-shaping. + - Update the permanent corpus. Before and after implementation, assess documentation impact: keep the required architecture and design overviews current when their structure or cross-cutting behaviour changes, update the relevant capability design or general design document when it answers a reader's question, and link rather than duplicate. State in the change or pull-request handoff which durable documentation changed, or why none was needed; do not create a permanent change-history document. Architecture owns actors, boundaries, and durable technology choices; `docs/design/README.md` owns cross-cutting flows and patterns; a capability's `design.md` owns local detail. Draft a missing overview from repository evidence, and ask the human only when a material boundary or intent remains unclear. Use Mermaid when a diagram materially clarifies a relationship, boundary, or flow; retain SVG only when Mermaid is inadequate. A relevant new or materially revised ADR or IDR links to the affected overview. + - Capabilities own README, criteria, and design files. Write criteria as Gherkin tagged with their canonical `-[lowercase-suffix]` identity; every new or materially revised criterion declares `Test-type: Unit|Integration|E2E|Performance|Human` on the first line of its scenario body and gets focused positive and negative evidence in that class (or records `(single-direction)` when only one direction exists). `Human` needs no code evidence — the acceptance brief's criteria line is its proof; use it for a criterion deliberately verified by human judgment, never as a placeholder for a test not written. A criterion genuinely not yet proven carries `@draft` on its tag line instead, exempting only that criterion from the active-file test requirement — the capability itself does not need to stay `draft` because one criterion is unproven. + - Every test declares exactly one purpose: the criterion ID, `Unit`, `Sanity`, or `Arch`, using framework tags where available and the normalized test-name prefix in Go; AC evidence also carries its declared test type and direction. On the JVM, all three evidence parts attach to the same Java or Kotlin executable through literal JUnit method tags or the stable `test[lowercase-suffix]__` name; class tags, comments, and unrelated methods cannot supply missing parts. + - When a criterion's meaning changes, retire it with `@retired`, keep the tombstone, mint a new ID, and remove or retag its tests. 4. **Digest:** After every task is `[x]` or `[-]` with a reason, update permanent `/docs`, regenerate README indexes, apply repository-local digest conventions, record decisions, and update plan bookkeeping. Retiring a non-criterion artifact means deleting its file in this same digest — never leaving a `status: retired` file behind — and naming the dead ID in a `supersedes:` field on its successor or best live next stop; criteria tombstones (`@retired`, file kept so the test tag keeps failing) and completed plans (frozen, never deleted) are the named exceptions. Delete the change workspace. The digest is never a task in `tasks.md`; deletion is the digest, so a self-referential digest task cannot be completed honestly. 5. **Verify, review, and propose for acceptance:** Run `clue-verify`, including its automatic agentic review loop on the verified committed candidate, then mark the draft PR ready under the [Review boundary](review-boundary.md). For a full change, fill the acceptance brief at the top of the PR body with the plan item and whether it remains wanted, every added or changed criterion and its scenario-resolution verdict — naming any newly or materially declared `Human`-class criterion there as its proof — and what merge binds or supersedes, including any authorized unmerged base and the meaning accepting this change would bind before that base is accepted; keep it to one screen and never leave template placeholders. Never ask the human to initiate the review. Merging accepts the change; decision provenance follows [Decision records](decision-records.md). diff --git a/.agents/skills/clue-delta/references/change-scope-and-tiers.md b/.agents/skills/clue-delta/references/change-scope-and-tiers.md index adeb5e2..38f84fc 100644 --- a/.agents/skills/clue-delta/references/change-scope-and-tiers.md +++ b/.agents/skills/clue-delta/references/change-scope-and-tiers.md @@ -7,4 +7,4 @@ Before editing, inspect the smallest relevant context and tell the user `Recomme Paths, file counts, and changed-line counts may warn but never decide meaning. Reassess when a discovery expands semantic scope and against the complete diff before integration. If simple work grows into full work, pause and recommend the full loop. If the user explicitly declines, proceed as simple without making code, tests, or durable documentation untruthful, and add all three trailers to the final authored commit: `Cliewen-Route: simple`, `Cliewen-Recommendation: full`, and `Cliewen-Override: user chose simple; `. This records one integration authorization in Git history, not a corpus decision. -A route does not authorize a push. Push directly to an integration branch only with explicit user authorization and repository permission; otherwise follow the repository's requested workflow. A human may integrate by any mechanism the repository permits, and repository-local conventions may be stricter. A release is not a Cliewen route: each adopter defines or omits its own release process, whose work is classified by accepted-contract impact. +A route does not authorize a push; the [Review boundary](review-boundary.md) states when an agent may push to an integration branch. A human may integrate by any mechanism the repository permits, and repository-local conventions may be stricter. A release is not a Cliewen route: each adopter defines or omits its own release process, whose work is classified by accepted-contract impact. diff --git a/.agents/skills/clue-delta/references/durable-work-state.md b/.agents/skills/clue-delta/references/durable-work-state.md index db7e1d4..bf6cba8 100644 --- a/.agents/skills/clue-delta/references/durable-work-state.md +++ b/.agents/skills/clue-delta/references/durable-work-state.md @@ -4,6 +4,16 @@ An agent's private memory is never where work lives. Anything needed to implemen A suggestion raised mid-change is triaged immediately, into one of two carriers, never into memory. If the change is wrong or incomplete without it, it becomes a task in `tasks.md`, handled before merge. Otherwise it becomes a goal with `status: proposed`, written in the digest so it survives the workspace's deletion. Neither carrier is optional, and "I will remember" is not a third: a suggestion that is neither actioned nor recorded has been declined without anyone deciding to decline it. State which carrier a suggestion went to, and why, when the triage happens. +A reusable discovery earns capture only past an eligibility bar: it cost something to find — a wrong first attempt, an undocumented flag, a nonobvious recovery — and is plausibly recurring, so a fresh agent doing the same class of task would hit it again. Restating already-documented behaviour, or something observed once with no reason to expect recurrence, is not eligible; documenting an ineligible discovery is how a workaround hardens into policy. + +An eligible discovery is captured under these rules: + +- **Fix before documenting.** Ask whether the confusing step can instead be removed or automated; only what cannot yet be fixed gets written down. +- **Home.** A capability-specific discovery goes into that capability's own `design.md`; a discovery about running the repository's own tooling, tied to no single capability, goes into the repository's own contributor or operational guidance (for example `CONTRIBUTING.md`), where one exists. Correct an existing home in preference to writing beside it. +- **Shape and reach.** State the discovery's trigger, prerequisites, procedure, expected result, and recovery, and reach it from where the matching work already begins so finding it does not require reading every guide. +- **Scope.** One observation in one session supports only a claim scoped to what was actually seen — the platform, the command form, the version — never a general claim from a single trial. +- **Retirement.** Correct or retire guidance in the same change that finds it stale, the same way any other design-document content is kept current; it carries no separate lifecycle or tombstone. + A durable record never states a figure a command computes — an artifact count, a coverage percentage, a reported population size. Name the command instead. A number written into prose becomes a hand-maintained obligation that goes stale on the next change and that every later reviewer re-derives, and repairing one writes new prose carrying new numbers, so the finding regenerates instead of converging. Measurements that are the point of a record — an analysis's own results, a milestone's observed evidence — are stated with what produced them and when. -After a human reports a Cliewen change's merge, orient before starting anything else: describe the plan's next unfinished step in plain language and ask whether to start it, or say that the plan has nothing left and ask what comes next. +When a user asks what is next, run `clue next` before proposing work. It reports the first unfinished milestone in an active plan, gives alternatives with `--all`, and names unfinished rows in draft plans as proposed rather than actionable. Read the selected plan context, check that the plan still holds, and ask before starting. After a human reports a Cliewen change's merge, use the same orientation path before beginning anything else. diff --git a/.agents/skills/clue-delta/references/intent-model.md b/.agents/skills/clue-delta/references/intent-model.md index 9d3debd..f712092 100644 --- a/.agents/skills/clue-delta/references/intent-model.md +++ b/.agents/skills/clue-delta/references/intent-model.md @@ -36,6 +36,6 @@ Recommend for or against one, say why, and let the human decide. A use case is c ### Marking what is not yet confirmed -Agent-drafted intent is `status: draft` with `provenance: inferred` and a stated `reversal-cost`, and its assumptions and open questions stay visible in the artifact. Promotion is a human act. Never present an inference as a fact, and never resolve a contradiction between sources by picking the convenient reading — record it and ask. +Agent-drafted intent is `status: draft` with `provenance: inferred` and `reversal-cost: low|high`; low explicitly permits deferral, while high can block an active capability that directly depends on the artifact. Once a human verifies the meaning, remove `reversal-cost`; it is no longer used. Assumptions and open questions stay visible in the artifact. Promotion is a human act. Never present an inference as a fact, and never resolve a contradiction between sources by picking the convenient reading — record it and ask. **A full change's acceptance brief states the vision it proceeds under**, or states that the repository has none and that the change proceeds without one. When unresolved meaning would materially change what the system is for, stop and ask rather than deciding it inside an implementation. diff --git a/.agents/skills/clue-delta/references/review-boundary.md b/.agents/skills/clue-delta/references/review-boundary.md index dddbc96..32e0307 100644 --- a/.agents/skills/clue-delta/references/review-boundary.md +++ b/.agents/skills/clue-delta/references/review-boundary.md @@ -6,16 +6,22 @@ Every full change branches from the current tip of `main`, never from unaccepted For a full Cliewen change, the human accepts the ready pull request with a merge commit. Configure the protected default branch to allow merge commits and disable squash and rebase-and-merge: the merge commit keeps the proposal, implementation, digest, and durable corpus commits reachable from `main`, while the other modes can discard or rewrite that reviewed chain. Because publication begins with the first commit, there is no unpublished branch to rebase: hosted history is never rewritten. A forge that cannot enforce the merge-commit boundary is outside the supported full-change adoption path. -Inside the full loop, this rule applies. Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. +Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. The PR exists from first publication and starts as a draft: a full change opens it right after the proposal commit. The draft is where unfinished work lives and is visible; it claims nothing and cannot be merged. Marking the PR ready for review is the explicit act that claims a candidate, taken only when local verification and the automatic agentic review loop have passed on the current commit and the hosted head equals it. The PR is the completed proposal's authorization and protected-integration boundary, not a demand for duplicate human code review: the agent may prepare and publish the candidate, but only a human-controlled PR merge accepts it. A substantive edit to a ready PR returns it to draft until its new head has earned the same binding. Inside this boundary, an agent never merges its own PR, creates a local merge commit into `main`, or pushes to `main`. A PR alone displays hosted CI but does not enforce it. Where hosting supports enforcement, the PR triggers CI, branch protection makes its required status check a merge precondition, and the agent cannot silently skip the gate. On a draft, the checks that judge a completed candidate — the digest gate and the acceptance-brief requirement — do not yet apply; they bind when the PR is marked ready and on `main`, and because the forge cannot merge a draft, the merge gate stays whole. Never weaken the workflow or required-check policy to make a change pass. -Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding; this fail-safe applies to blocking findings, while advisories stay in the handoff; never claim a chat-only finding has equivalent protection. +Because that enforcement lives at the Git host rather than in the repository, no check that reads files can see it: a clone does not carry it, no file records it, and `git log` never shows it changing. So before marking a pull request ready for the first time in a repository, find out whether the branch being relied on enforces anything, and report what was actually observed. On a host with a command for it, ask the host; on GitHub, `gh ruleset check --default` and the branch-protection endpoint both answer read-only. Where there is no way to ask, say that the state is unknown rather than assuming either answer — silence is not a pass, and a boundary reported as verified without being observed is worse than one reported as unknown. + +When the host reports that the branch enforces what the boundary needs, record what was observed and mark the pull request ready without interrupting the human. The question is asked once in a repository, not turned into a ritual at every candidate, and an adequate answer is the end of it. + +When enforcement is missing, inadequate, or unknown, stop and tell the human plainly what is absent — force-push and deletion blocked, the validation check required, pull requests required, an empty bypass list — and offer to configure what the host allows. Propose the exact commands and apply them only on explicit authorization in that exchange; repository configuration is the human's decision, and an agent that changed it unasked would be acting exactly where nobody can see. A human who declines or defers has answered: mark the pull request ready as usual and state in the readiness handoff that the boundary is unenforced, with the reason given. The decline is recorded because it is evidence about the method, not because it is a failure. + +Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding. This fail-safe covers blocking findings only; never claim a chat-only finding has equivalent protection. Any agent that edits an existing PR becomes the updater for that turn. Before editing, fetch the PR and record its hosted head; push only normal fast-forward updates, never force. If the head changed underneath the turn or a push is rejected as non-fast-forward, fetch and reconcile without overwriting remote work, then rerun verification and review on the resulting commit. A repair pushed to a ready PR returns it to draft until the repaired head has its own verification and clean review pass. If the PR merged or closed, stop without pushing — the one case where a turn ends unpushed — report the work and where it stands, and never create a follow-up change without explicit human scope. -Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above, rerun verification and review on the resulting commit, and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. +Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. -After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change; simple work may still proceed under explicit user authority, and the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. +After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change, though the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. diff --git a/.agents/skills/clue-delta/skill.md b/.agents/skills/clue-delta/skill.md index 2af6c46..84233b7 100644 --- a/.agents/skills/clue-delta/skill.md +++ b/.agents/skills/clue-delta/skill.md @@ -1,6 +1,6 @@ --- cliewen-skill: true -version: 0.24.1 +version: 0.26.0 --- @@ -16,6 +16,7 @@ Read each reference when its condition is reached, before taking action governed - Before recommending a route or starting a full change, read [Change routing](references/change-scope-and-tiers.md). - Before branching, publishing, updating a hosted PR, or handing work to a human, read [Review boundary](references/review-boundary.md). - After the user chooses the recommended full loop, read [Change loop](references/change-loop.md). +- Before writing the proposal for a consequential change, read [Challenge a consequential commitment](references/challenge-commitments.md). - When the change touches what the product means, or the acceptance brief must state the vision it proceeds under, read [Intent model](references/intent-model.md). - When the change makes, rejects, or carries a decision, read [Decision records](references/decision-records.md). - Before applying repository-specific implementation or digest rules, read [Repository-local conventions](references/repository-local-conventions.md). diff --git a/.agents/skills/clue-extract/references/durable-work-state.md b/.agents/skills/clue-extract/references/durable-work-state.md index db7e1d4..bf6cba8 100644 --- a/.agents/skills/clue-extract/references/durable-work-state.md +++ b/.agents/skills/clue-extract/references/durable-work-state.md @@ -4,6 +4,16 @@ An agent's private memory is never where work lives. Anything needed to implemen A suggestion raised mid-change is triaged immediately, into one of two carriers, never into memory. If the change is wrong or incomplete without it, it becomes a task in `tasks.md`, handled before merge. Otherwise it becomes a goal with `status: proposed`, written in the digest so it survives the workspace's deletion. Neither carrier is optional, and "I will remember" is not a third: a suggestion that is neither actioned nor recorded has been declined without anyone deciding to decline it. State which carrier a suggestion went to, and why, when the triage happens. +A reusable discovery earns capture only past an eligibility bar: it cost something to find — a wrong first attempt, an undocumented flag, a nonobvious recovery — and is plausibly recurring, so a fresh agent doing the same class of task would hit it again. Restating already-documented behaviour, or something observed once with no reason to expect recurrence, is not eligible; documenting an ineligible discovery is how a workaround hardens into policy. + +An eligible discovery is captured under these rules: + +- **Fix before documenting.** Ask whether the confusing step can instead be removed or automated; only what cannot yet be fixed gets written down. +- **Home.** A capability-specific discovery goes into that capability's own `design.md`; a discovery about running the repository's own tooling, tied to no single capability, goes into the repository's own contributor or operational guidance (for example `CONTRIBUTING.md`), where one exists. Correct an existing home in preference to writing beside it. +- **Shape and reach.** State the discovery's trigger, prerequisites, procedure, expected result, and recovery, and reach it from where the matching work already begins so finding it does not require reading every guide. +- **Scope.** One observation in one session supports only a claim scoped to what was actually seen — the platform, the command form, the version — never a general claim from a single trial. +- **Retirement.** Correct or retire guidance in the same change that finds it stale, the same way any other design-document content is kept current; it carries no separate lifecycle or tombstone. + A durable record never states a figure a command computes — an artifact count, a coverage percentage, a reported population size. Name the command instead. A number written into prose becomes a hand-maintained obligation that goes stale on the next change and that every later reviewer re-derives, and repairing one writes new prose carrying new numbers, so the finding regenerates instead of converging. Measurements that are the point of a record — an analysis's own results, a milestone's observed evidence — are stated with what produced them and when. -After a human reports a Cliewen change's merge, orient before starting anything else: describe the plan's next unfinished step in plain language and ask whether to start it, or say that the plan has nothing left and ask what comes next. +When a user asks what is next, run `clue next` before proposing work. It reports the first unfinished milestone in an active plan, gives alternatives with `--all`, and names unfinished rows in draft plans as proposed rather than actionable. Read the selected plan context, check that the plan still holds, and ask before starting. After a human reports a Cliewen change's merge, use the same orientation path before beginning anything else. diff --git a/.agents/skills/clue-extract/references/intent-model.md b/.agents/skills/clue-extract/references/intent-model.md index 9d3debd..f712092 100644 --- a/.agents/skills/clue-extract/references/intent-model.md +++ b/.agents/skills/clue-extract/references/intent-model.md @@ -36,6 +36,6 @@ Recommend for or against one, say why, and let the human decide. A use case is c ### Marking what is not yet confirmed -Agent-drafted intent is `status: draft` with `provenance: inferred` and a stated `reversal-cost`, and its assumptions and open questions stay visible in the artifact. Promotion is a human act. Never present an inference as a fact, and never resolve a contradiction between sources by picking the convenient reading — record it and ask. +Agent-drafted intent is `status: draft` with `provenance: inferred` and `reversal-cost: low|high`; low explicitly permits deferral, while high can block an active capability that directly depends on the artifact. Once a human verifies the meaning, remove `reversal-cost`; it is no longer used. Assumptions and open questions stay visible in the artifact. Promotion is a human act. Never present an inference as a fact, and never resolve a contradiction between sources by picking the convenient reading — record it and ask. **A full change's acceptance brief states the vision it proceeds under**, or states that the repository has none and that the change proceeds without one. When unresolved meaning would materially change what the system is for, stop and ask rather than deciding it inside an implementation. diff --git a/.agents/skills/clue-extract/references/rehearsal-before-mutation.md b/.agents/skills/clue-extract/references/rehearsal-before-mutation.md index cdd3523..8b1a8cb 100644 --- a/.agents/skills/clue-extract/references/rehearsal-before-mutation.md +++ b/.agents/skills/clue-extract/references/rehearsal-before-mutation.md @@ -4,8 +4,8 @@ After the extraction's full change is proposed, begin with a mandatory report-on The rehearsal report inventories source formats and entry points, proposed artifact mappings, preserved and minted IDs, confidence and reversal cost, test-purpose work, instruction conflicts, planned deletions, and named plan doors. An unresolved conflict becomes an `open-questions.md` entry and stops before mutation. -The rehearsal also writes a pinned source manifest under the change workspace: the exact source revision and location read, and one proof-class, direction, and evidence-location row for every classified reference a criterion has, or one declared exclusion with reason, or one `draft`/`human`/`retired` disposition with a readable justification, its particular `disposition-source-location`, and its own existing target milestone as `plan-door`. This is the same manifest `clue parity` compares against the corpus it derives — write it once here rather than reconstructing it afterward. +The rehearsal also writes a pinned source manifest under the change workspace: the exact source revision and location read, and one proof-class, direction, and evidence-location row for every classified reference a criterion has, or one declared exclusion with reason, or one `draft`/`human`/`retired` disposition with a readable justification, its particular `disposition-source-location`, and its own existing target milestone as `plan-door`. `clue parity` compares the derived corpus against this manifest. -The rehearsal also writes a pinned carrier inventory under the change workspace: the same source revision and location, every source-repository path the migration will delete (`deleted-paths`), and one row per operational carrier found — an `instruction`, `workflow`, `freshness-input`, `registry`, `link`, or `diagram-asset` — naming its `id`, `kind`, and `source-path`, plus either its mapped `target-path` and content `fingerprint`, or an explicit `blocked: true` with a `reason` when no target exists yet. This is the same inventory `clue carriers` reconciles against the corpus it derives — write it once here rather than reconstructing it afterward. +The rehearsal also writes a pinned carrier inventory under the change workspace: the same source revision and location, every source-repository path the migration will delete (`deleted-paths`), and one row per operational carrier found — an `instruction`, `workflow`, `freshness-input`, `registry`, `link`, or `diagram-asset` — naming its `id`, `kind`, and `source-path`, plus either its mapped `target-path` and content `fingerprint`, or an explicit `blocked: true` with a `reason` when no target exists yet. `clue carriers` reconciles the derived corpus against this inventory. Write both once here rather than reconstructing them afterward. Only explicit human direction begins the existing full extraction change's mutate phase. That phase digests the rehearsal into the durable extraction report under `/docs/analysis`, then performs the accepted conversion; the ready PR deletes both the transient change workspace and the parallel source corpus. diff --git a/.agents/skills/clue-extract/references/review-boundary.md b/.agents/skills/clue-extract/references/review-boundary.md index dddbc96..32e0307 100644 --- a/.agents/skills/clue-extract/references/review-boundary.md +++ b/.agents/skills/clue-extract/references/review-boundary.md @@ -6,16 +6,22 @@ Every full change branches from the current tip of `main`, never from unaccepted For a full Cliewen change, the human accepts the ready pull request with a merge commit. Configure the protected default branch to allow merge commits and disable squash and rebase-and-merge: the merge commit keeps the proposal, implementation, digest, and durable corpus commits reachable from `main`, while the other modes can discard or rewrite that reviewed chain. Because publication begins with the first commit, there is no unpublished branch to rebase: hosted history is never rewritten. A forge that cannot enforce the merge-commit boundary is outside the supported full-change adoption path. -Inside the full loop, this rule applies. Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. +Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. The PR exists from first publication and starts as a draft: a full change opens it right after the proposal commit. The draft is where unfinished work lives and is visible; it claims nothing and cannot be merged. Marking the PR ready for review is the explicit act that claims a candidate, taken only when local verification and the automatic agentic review loop have passed on the current commit and the hosted head equals it. The PR is the completed proposal's authorization and protected-integration boundary, not a demand for duplicate human code review: the agent may prepare and publish the candidate, but only a human-controlled PR merge accepts it. A substantive edit to a ready PR returns it to draft until its new head has earned the same binding. Inside this boundary, an agent never merges its own PR, creates a local merge commit into `main`, or pushes to `main`. A PR alone displays hosted CI but does not enforce it. Where hosting supports enforcement, the PR triggers CI, branch protection makes its required status check a merge precondition, and the agent cannot silently skip the gate. On a draft, the checks that judge a completed candidate — the digest gate and the acceptance-brief requirement — do not yet apply; they bind when the PR is marked ready and on `main`, and because the forge cannot merge a draft, the merge gate stays whole. Never weaken the workflow or required-check policy to make a change pass. -Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding; this fail-safe applies to blocking findings, while advisories stay in the handoff; never claim a chat-only finding has equivalent protection. +Because that enforcement lives at the Git host rather than in the repository, no check that reads files can see it: a clone does not carry it, no file records it, and `git log` never shows it changing. So before marking a pull request ready for the first time in a repository, find out whether the branch being relied on enforces anything, and report what was actually observed. On a host with a command for it, ask the host; on GitHub, `gh ruleset check --default` and the branch-protection endpoint both answer read-only. Where there is no way to ask, say that the state is unknown rather than assuming either answer — silence is not a pass, and a boundary reported as verified without being observed is worse than one reported as unknown. + +When the host reports that the branch enforces what the boundary needs, record what was observed and mark the pull request ready without interrupting the human. The question is asked once in a repository, not turned into a ritual at every candidate, and an adequate answer is the end of it. + +When enforcement is missing, inadequate, or unknown, stop and tell the human plainly what is absent — force-push and deletion blocked, the validation check required, pull requests required, an empty bypass list — and offer to configure what the host allows. Propose the exact commands and apply them only on explicit authorization in that exchange; repository configuration is the human's decision, and an agent that changed it unasked would be acting exactly where nobody can see. A human who declines or defers has answered: mark the pull request ready as usual and state in the readiness handoff that the boundary is unenforced, with the reason given. The decline is recorded because it is evidence about the method, not because it is a failure. + +Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding. This fail-safe covers blocking findings only; never claim a chat-only finding has equivalent protection. Any agent that edits an existing PR becomes the updater for that turn. Before editing, fetch the PR and record its hosted head; push only normal fast-forward updates, never force. If the head changed underneath the turn or a push is rejected as non-fast-forward, fetch and reconcile without overwriting remote work, then rerun verification and review on the resulting commit. A repair pushed to a ready PR returns it to draft until the repaired head has its own verification and clean review pass. If the PR merged or closed, stop without pushing — the one case where a turn ends unpushed — report the work and where it stands, and never create a follow-up change without explicit human scope. -Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above, rerun verification and review on the resulting commit, and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. +Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. -After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change; simple work may still proceed under explicit user authority, and the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. +After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change, though the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. diff --git a/.agents/skills/clue-extract/references/target-contract.md b/.agents/skills/clue-extract/references/target-contract.md index a37b9ab..d3a21d0 100644 --- a/.agents/skills/clue-extract/references/target-contract.md +++ b/.agents/skills/clue-extract/references/target-contract.md @@ -3,13 +3,13 @@ The extraction PR is complete only when all of these hold: 1. **The full taxonomy and system overviews exist:** `/docs` has goals, plans, capabilities, decisions, constraints, analysis, architecture, and design, with an indexed README in every folder and README, criteria, and design files in each capability folder. `docs/architecture/README.md` is a concise evidence-based overview of actors, boundaries, components, and durable technology choices; `docs/design/README.md` is a concise overview of cross-cutting flows, interactions, and patterns. Extract the big picture, not every local detail: capability `design.md` remains the local home. Survey the source for suitable existing overview documents and visual assets. Before moving any found overview into the canonical path, present one grouped source-to-target mapping and link rewrites to the human; move only after explicit consent. If consent is declined, keep the source and write a concise canonical pointer rather than duplicate it. Where evidence cannot establish a material boundary or intent, ask the human; otherwise draft the overview as inferred repository truth. Use Mermaid when it materially clarifies a relationship or flow, retaining SVG when Mermaid is inadequate. A folder with nothing real to hold stays empty but indexed. An index row states its record and says what the artifact is about; index generation seeds that sentence from the artifact's own body, and you correct it rather than leaving a seed that reads as a summary but states a problem. -2. **Everything extracted is born inferred and decisions route by subject:** Use `provenance: inferred` plus `reversal-cost: low|high` on every non-decision artifact, classifying whether its meaning is cheap and local or expensive to reverse. A future-shaping decision instead uses `status: inferred` and `author: agent`, routing to ADR for architecture, PDR for project/process, or IDR for implementation; routine facts and history do not become records. Human review may promote records to `verified`, file by file or in bulk. An active capability cannot depend by one `links:` edge on high-cost inferred meaning, while low-cost inferred findings may remain legitimately deferred. Extracted decisions also follow [Decision records](decision-records.md). A legacy decision log is inventoried row by row in the rehearsal and remains until a reviewed full change classifies every future-shaping choice and explicitly accounts for discarded narrative; extraction never guesses or silently drops a row. +2. **Everything extracted is born inferred and decisions route by subject:** Use `provenance: inferred` plus `reversal-cost: low|high` on every non-decision artifact, classifying whether its meaning is cheap and local or expensive to reverse. Low explicitly permits deferral; high-cost inferred meaning blocks an active capability joined to it by one links edge. When a human promotes the artifact to `verified`, remove `reversal-cost` because the classification has been consumed. A future-shaping decision instead uses `status: inferred` and `author: agent`, routing to ADR for architecture, PDR for project/process, or IDR for implementation; routine facts and history do not become records. Extracted decisions also follow [Decision records](decision-records.md). A legacy decision log is inventoried row by row in the rehearsal and remains until a reviewed full change classifies every future-shaping choice and explicitly accounts for discarded narrative; extraction never guesses or silently drops a row. 3. **Existing criterion IDs survive; a criterion with none is minted deterministically:** Declare each capability's namespace with `ac-prefix:` and keep source IDs verbatim — never renumber, since IDs are meaning-immutable and existing test tags must keep resolving. A namespace may contain one or more uppercase alphanumeric segments joined by single hyphens, and a canonical criterion ID may carry a lowercase letter suffix after its numeric portion; case and punctuation are exact in the corpus. When a source requirement carries no stable ID of its own, mint one in its capability's `ac-prefix:` namespace: take the requirements without IDs in the source's own stated or file order and assign the next numeric slot after the maximum numeric component already declared in that namespace, ignoring letter suffixes for the maximum; an empty namespace starts at one. The corpus is the registry, a minted ID never collides with one kept verbatim, and the same source state always mints the same IDs. Record the preserved and minted mapping in the extraction report below. 4. **Every test keeps or gains exactly one purpose without losing source evidence:** Existing criterion tags remain. Untagged tests get `Unit`, `Sanity`, or `Arch` according to intent. On the JVM, normalize each supported Java or Kotlin executable so its canonical AC identity, proof type, and direction attach together through literal JUnit method tags or the stable `test[lowercase-suffix]__` name; remove hyphens from segmented prefixes only in the named form and use underscores for hyphens in literal JUnit tags. A multi-criterion executable or class-level criterion tag is a semantic conflict: the rehearsal inventories its location, identities, behavior or structural scope, and proposed resolution, while a normalizer reports it but never deletes, selects, or relocates a tag. After explicit human direction, split a multi-criterion test into one-criterion executables that retain the relevant assertions, or keep one reviewed primary identity and record every other one as needing dedicated proof or an explicit `@draft` criterion. Move a class-level identity only to the executable that actually proves it or to a scoped new test; if that work is explicitly out of scope, record its source location and named plan door with an explicit `@draft` criterion. Comments, dynamic or multi-line tag expressions, and metadata split across methods are unsupported evidence; record and resolve the gap instead of installing an external rule or letting `clue` guess. 5. **Evidence status is explicit at the narrowest honest level:** Whole-file draft phasing remains available: a capability whose extracted criteria are not ready for active use stays `status: draft`, and the extraction report names the gap and plan door. An active criteria file may also phase individual promises: tag each genuinely not-yet-proven criterion `@draft`, exempting only that criterion while evidence-backed siblings remain active. A genuine `Test-type: Human` criterion is already proven by naming it in the pull request acceptance brief and needs no code reference; it is not a placeholder for a missing test. Machine-proven criteria use supported Go, per-executable JVM, or Cucumber evidence classified by their declared `Unit`, `Integration`, `E2E`, or `Performance` type and positive/negative direction, with `(single-direction)` only when one direction is honest; legacy criteria without a declared proof type retain the one-supported-reference rule. A capability is therefore not the smallest activation unit. Extraction is never partial by silent omission: every draft file or criterion states why it is draft and names the change that will prove it. 6. **`clue validate` is green before the PR is marked ready:** The extracted corpus is judged by the same rules as a greenfield corpus. -7. **`clue parity` is clean before the source corpus is deleted:** Run it against the rehearsal's source manifest and fix every missing criterion, orphaned tag, changed direction or evidence location, stale source fingerprint, and unjustified `draft`/`human`/`retired` disposition it reports; a migration workflow uploads a failing or passing report as a CI artifact. A clean run is what makes the source deletion in the next item honest — coverage the manifest cannot account for stays in the source until it can. -8. **`clue carriers` is clean before the source corpus is deleted:** Run it against the rehearsal's carrier inventory and fix every stale deleted-path reference, lost fingerprint, and missing asset it reports; a migration workflow uploads a failing or passing report as a CI artifact the same way `clue parity`'s does. Every operational carrier the rehearsal found — instruction, workflow, freshness-input, registry, link, or diagram-asset — maps to a retained target or carries an explicit `blocked` marker with a reason; a clean run is what makes the source deletion in the next item honest for carriers, the same way a clean `clue parity` run makes it honest for criteria. +7. **`clue parity` is clean before the source corpus is deleted:** Run it against the rehearsal's source manifest and fix every missing criterion, orphaned tag, changed direction or evidence location, stale source fingerprint, and unjustified `draft`/`human`/`retired` disposition it reports; a migration workflow uploads a failing or passing report as a CI artifact. A clean run is what makes the source deletion in item 9 honest — coverage the manifest cannot account for stays in the source until it can. +8. **`clue carriers` is clean before the source corpus is deleted:** Run it against the rehearsal's carrier inventory and fix every stale deleted-path reference, lost fingerprint, and missing asset it reports, uploading the report as `clue parity`'s is. Every operational carrier the rehearsal found maps to a retained target or carries an explicit `blocked` marker with a reason; a clean run makes the source deletion in item 9 honest for carriers, as a clean `clue parity` run does for criteria. 9. **The source corpus dies in the same PR without losing its links:** Delete parallel specification trees, registries, and source-format skills only after every retained link and asset is preserved. A deterministic source-to-Cliewen mapping rewrites a source target to its converted target; an unmapped target is a finding that stops destructive source deletion, never a reason to remove the link or asset. Git history is the archive once the mapping is complete. Two systems of record is zero systems of record. A hand-maintained per-folder index file is one of these, whatever it is called: absorb what it says into that folder's README index rows first — its description column becomes the row's sentence, and any column that only restates a `links:` edge is dropped rather than carried, because `clue context` already walks those edges — then delete the file. Two indexes in one folder is the same failure as two corpora, and the generated block will otherwise list the hand-maintained one among its own entries. Adopters carrying several such files rarely agree on their columns; map each one on what it says, not on its heading. A source repository's still-open pending change is a distinct case: do not delete its in-flight work until its `imported-change` record's status reaches `complete` — `clue` cannot check this itself, since it never reads the source repository, so the refusal is this rehearsal's own judgment, not a validator rule. 10. **Routing is rewritten and reconciled:** Point every assistant entry point the repository carries — `AGENTS.md` and any other assistant-specific entry file, such as `CLAUDE.md` or `.cursor/rules` — to `/docs/README.md` and the installed `clue-*` skills; `AGENTS.md` is the flagship instance of this class, not its only member. Absorb compatible pre-existing instructions as repository-local conventions; record conflicts as open questions. 11. **An extraction report lands in `/docs/analysis`, and its figures are rendered rather than typed:** The mutate phase digests the rehearsal into the report, recording what was found, what mapped where, and what was dropped and why. The report's criterion counts and mapping table live in one region opened by `` and closed by ``, rendered by `clue report ` from the same pinned source manifest `clue parity` compares; `clue validate` re-renders the region and fails on any difference, so a report cannot state a population or a mapping the manifest never held. The report summarizes the mapping; the pinned manifest remains the per-criterion detail, and no second committed per-criterion registry is created. Prose outside the region is yours, and a figure that belongs to the manifest belongs inside it; a marker written in a code span or a fenced block is an example, so a document may describe the contract without becoming a report. diff --git a/.agents/skills/clue-extract/skill.md b/.agents/skills/clue-extract/skill.md index 957f346..9a1d493 100644 --- a/.agents/skills/clue-extract/skill.md +++ b/.agents/skills/clue-extract/skill.md @@ -1,6 +1,6 @@ --- cliewen-skill: true -version: 0.24.1 +version: 0.26.0 --- diff --git a/.agents/skills/clue-plan/references/challenge-commitments.md b/.agents/skills/clue-plan/references/challenge-commitments.md new file mode 100644 index 0000000..24b1f3d --- /dev/null +++ b/.agents/skills/clue-plan/references/challenge-commitments.md @@ -0,0 +1,7 @@ +## Challenge a consequential commitment + +Before a consequential commitment, challenge it where the reviewer will read it: in the plan's prose for a plan, in `proposal.md` for a change. Name the assumption most likely to undermine the work, a credible alternative course, the cheapest useful test of that assumption, and the result that would stop or revise the work. Then ask what an implementation could look like that met every criterion and still failed the person the work is for — that is the failure a criterion-to-test thread cannot catch, because one author usually writes the criterion, its implementation, and its test in one sitting. + +A commitment is consequential when being wrong would cost more than finding out first: adopting or revising a plan's promise, starting a milestone whose approach is unsettled, choosing between credible courses in a decision, or a change to what adopters receive. Route first: simple work is never consequential, even when it touches a shipped surface. Work carrying out a course already challenged and understood, and work that can be undone within the same change at no more cost than the challenge, also proceed without a challenge and without a note explaining its absence. + +The proportionality limit is part of the rule, not an exemption from it: a challenge demanded of everything is written by habit, and a challenge written by habit is the confident, unexamined text this rule exists to interrupt. No prototype is ever universally required; a small path across the consequential boundaries is warranted only where the architecture is materially uncertain, and a milestone may deliver decision-changing evidence instead of a feature. Cite applicable repository experience when challenging assumptions, and treat it as evidence to reassess against the case in hand rather than as settled authority. diff --git a/.agents/skills/clue-plan/references/intent-model.md b/.agents/skills/clue-plan/references/intent-model.md index 9d3debd..f712092 100644 --- a/.agents/skills/clue-plan/references/intent-model.md +++ b/.agents/skills/clue-plan/references/intent-model.md @@ -36,6 +36,6 @@ Recommend for or against one, say why, and let the human decide. A use case is c ### Marking what is not yet confirmed -Agent-drafted intent is `status: draft` with `provenance: inferred` and a stated `reversal-cost`, and its assumptions and open questions stay visible in the artifact. Promotion is a human act. Never present an inference as a fact, and never resolve a contradiction between sources by picking the convenient reading — record it and ask. +Agent-drafted intent is `status: draft` with `provenance: inferred` and `reversal-cost: low|high`; low explicitly permits deferral, while high can block an active capability that directly depends on the artifact. Once a human verifies the meaning, remove `reversal-cost`; it is no longer used. Assumptions and open questions stay visible in the artifact. Promotion is a human act. Never present an inference as a fact, and never resolve a contradiction between sources by picking the convenient reading — record it and ask. **A full change's acceptance brief states the vision it proceeds under**, or states that the repository has none and that the change proceeds without one. When unresolved meaning would materially change what the system is for, stop and ask rather than deciding it inside an implementation. diff --git a/.agents/skills/clue-plan/references/planning-workflow.md b/.agents/skills/clue-plan/references/planning-workflow.md index 21efe49..88f9e09 100644 --- a/.agents/skills/clue-plan/references/planning-workflow.md +++ b/.agents/skills/clue-plan/references/planning-workflow.md @@ -6,6 +6,6 @@ Use when creating a plan or changing what a plan promises. 2. Create or revise a plan through `clue-delta`; a plan mutation is itself a branch and PR. The digest is the plan file in `/docs/plans/`. 3. Keep plans as flat `P-xxx-slug.md` files with status in frontmatter (`draft` → `active` → `completed`). Milestones (`M-xxx`) are rows in the plan's milestone table, each with a verifiable exit criterion. 4. Treat semantic mutation and bookkeeping differently: - - **Semantic:** Direction, scope, milestone addition/removal, or anything else that changes the plan's promise requires human acceptance and a decision record under [Decision records](decision-records.md). Agents may propose; only humans accept. The default vehicle is a dedicated plan change and PR. A revision discovered during implementation may ride with that implementing change only when the PR declares the plan revision, a correctly typed decision record backs it, the PR calls it out for deliberate approval, and an explicit objection can revert the revision while leaving the milestone open without blocking the rest of the change. + - **Semantic:** Direction, scope, milestone addition/removal, or anything else that changes the plan's promise requires a declared revision and human direction. A revision may ride with the implementing change that uncovered it; use a plan-only change when no implementation is active or it makes the review clearer. A revision is not automatically a decision record: record one under [Decision records](decision-records.md) only when the selected course is a future-shaping choice. - **Bookkeeping:** Marking a milestone done belongs in the implementing change's merge digest, never a separate PR. Closing the plan is the same bookkeeping: the change completing the last milestone also sets it `completed`, in that digest. A campaign is over the moment its last milestone is evidenced, so leaving it `active` publishes an index claiming work is in flight that is not. Designate the successor plan there too when one is decided; not having decided one never holds the closure open. Every milestone's evidence must be in the table before that digest lands, because the closed plan is immutable afterwards. 5. Treat `status: completed` as immutable and never delete a completed plan. diff --git a/.agents/skills/clue-plan/skill.md b/.agents/skills/clue-plan/skill.md index d527151..8958df3 100644 --- a/.agents/skills/clue-plan/skill.md +++ b/.agents/skills/clue-plan/skill.md @@ -1,6 +1,6 @@ --- cliewen-skill: true -version: 0.24.1 +version: 0.26.0 --- @@ -16,4 +16,5 @@ Read each reference when its condition is reached, before taking action governed - Before creating or revising a plan, read [Planning workflow](references/planning-workflow.md). - Before deciding which goals a plan serves, and whether any journey needs a use case, read [Intent model](references/intent-model.md). - When the repository states no usable vision, read [Intent discovery](references/intent-discovery.md). +- Before adopting or revising a plan's promise, read [Challenge a consequential commitment](references/challenge-commitments.md). - When plan meaning or another consequential choice is recorded, read [Decision records](references/decision-records.md). diff --git a/.agents/skills/clue-upgrade/references/change-scope-and-tiers.md b/.agents/skills/clue-upgrade/references/change-scope-and-tiers.md index adeb5e2..38f84fc 100644 --- a/.agents/skills/clue-upgrade/references/change-scope-and-tiers.md +++ b/.agents/skills/clue-upgrade/references/change-scope-and-tiers.md @@ -7,4 +7,4 @@ Before editing, inspect the smallest relevant context and tell the user `Recomme Paths, file counts, and changed-line counts may warn but never decide meaning. Reassess when a discovery expands semantic scope and against the complete diff before integration. If simple work grows into full work, pause and recommend the full loop. If the user explicitly declines, proceed as simple without making code, tests, or durable documentation untruthful, and add all three trailers to the final authored commit: `Cliewen-Route: simple`, `Cliewen-Recommendation: full`, and `Cliewen-Override: user chose simple; `. This records one integration authorization in Git history, not a corpus decision. -A route does not authorize a push. Push directly to an integration branch only with explicit user authorization and repository permission; otherwise follow the repository's requested workflow. A human may integrate by any mechanism the repository permits, and repository-local conventions may be stricter. A release is not a Cliewen route: each adopter defines or omits its own release process, whose work is classified by accepted-contract impact. +A route does not authorize a push; the [Review boundary](review-boundary.md) states when an agent may push to an integration branch. A human may integrate by any mechanism the repository permits, and repository-local conventions may be stricter. A release is not a Cliewen route: each adopter defines or omits its own release process, whose work is classified by accepted-contract impact. diff --git a/.agents/skills/clue-upgrade/references/durable-work-state.md b/.agents/skills/clue-upgrade/references/durable-work-state.md index db7e1d4..bf6cba8 100644 --- a/.agents/skills/clue-upgrade/references/durable-work-state.md +++ b/.agents/skills/clue-upgrade/references/durable-work-state.md @@ -4,6 +4,16 @@ An agent's private memory is never where work lives. Anything needed to implemen A suggestion raised mid-change is triaged immediately, into one of two carriers, never into memory. If the change is wrong or incomplete without it, it becomes a task in `tasks.md`, handled before merge. Otherwise it becomes a goal with `status: proposed`, written in the digest so it survives the workspace's deletion. Neither carrier is optional, and "I will remember" is not a third: a suggestion that is neither actioned nor recorded has been declined without anyone deciding to decline it. State which carrier a suggestion went to, and why, when the triage happens. +A reusable discovery earns capture only past an eligibility bar: it cost something to find — a wrong first attempt, an undocumented flag, a nonobvious recovery — and is plausibly recurring, so a fresh agent doing the same class of task would hit it again. Restating already-documented behaviour, or something observed once with no reason to expect recurrence, is not eligible; documenting an ineligible discovery is how a workaround hardens into policy. + +An eligible discovery is captured under these rules: + +- **Fix before documenting.** Ask whether the confusing step can instead be removed or automated; only what cannot yet be fixed gets written down. +- **Home.** A capability-specific discovery goes into that capability's own `design.md`; a discovery about running the repository's own tooling, tied to no single capability, goes into the repository's own contributor or operational guidance (for example `CONTRIBUTING.md`), where one exists. Correct an existing home in preference to writing beside it. +- **Shape and reach.** State the discovery's trigger, prerequisites, procedure, expected result, and recovery, and reach it from where the matching work already begins so finding it does not require reading every guide. +- **Scope.** One observation in one session supports only a claim scoped to what was actually seen — the platform, the command form, the version — never a general claim from a single trial. +- **Retirement.** Correct or retire guidance in the same change that finds it stale, the same way any other design-document content is kept current; it carries no separate lifecycle or tombstone. + A durable record never states a figure a command computes — an artifact count, a coverage percentage, a reported population size. Name the command instead. A number written into prose becomes a hand-maintained obligation that goes stale on the next change and that every later reviewer re-derives, and repairing one writes new prose carrying new numbers, so the finding regenerates instead of converging. Measurements that are the point of a record — an analysis's own results, a milestone's observed evidence — are stated with what produced them and when. -After a human reports a Cliewen change's merge, orient before starting anything else: describe the plan's next unfinished step in plain language and ask whether to start it, or say that the plan has nothing left and ask what comes next. +When a user asks what is next, run `clue next` before proposing work. It reports the first unfinished milestone in an active plan, gives alternatives with `--all`, and names unfinished rows in draft plans as proposed rather than actionable. Read the selected plan context, check that the plan still holds, and ask before starting. After a human reports a Cliewen change's merge, use the same orientation path before beginning anything else. diff --git a/.agents/skills/clue-upgrade/references/review-boundary.md b/.agents/skills/clue-upgrade/references/review-boundary.md index dddbc96..32e0307 100644 --- a/.agents/skills/clue-upgrade/references/review-boundary.md +++ b/.agents/skills/clue-upgrade/references/review-boundary.md @@ -6,16 +6,22 @@ Every full change branches from the current tip of `main`, never from unaccepted For a full Cliewen change, the human accepts the ready pull request with a merge commit. Configure the protected default branch to allow merge commits and disable squash and rebase-and-merge: the merge commit keeps the proposal, implementation, digest, and durable corpus commits reachable from `main`, while the other modes can discard or rewrite that reviewed chain. Because publication begins with the first commit, there is no unpublished branch to rebase: hosted history is never rewritten. A forge that cannot enforce the merge-commit boundary is outside the supported full-change adoption path. -Inside the full loop, this rule applies. Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. +Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. The PR exists from first publication and starts as a draft: a full change opens it right after the proposal commit. The draft is where unfinished work lives and is visible; it claims nothing and cannot be merged. Marking the PR ready for review is the explicit act that claims a candidate, taken only when local verification and the automatic agentic review loop have passed on the current commit and the hosted head equals it. The PR is the completed proposal's authorization and protected-integration boundary, not a demand for duplicate human code review: the agent may prepare and publish the candidate, but only a human-controlled PR merge accepts it. A substantive edit to a ready PR returns it to draft until its new head has earned the same binding. Inside this boundary, an agent never merges its own PR, creates a local merge commit into `main`, or pushes to `main`. A PR alone displays hosted CI but does not enforce it. Where hosting supports enforcement, the PR triggers CI, branch protection makes its required status check a merge precondition, and the agent cannot silently skip the gate. On a draft, the checks that judge a completed candidate — the digest gate and the acceptance-brief requirement — do not yet apply; they bind when the PR is marked ready and on `main`, and because the forge cannot merge a draft, the merge gate stays whole. Never weaken the workflow or required-check policy to make a change pass. -Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding; this fail-safe applies to blocking findings, while advisories stay in the handoff; never claim a chat-only finding has equivalent protection. +Because that enforcement lives at the Git host rather than in the repository, no check that reads files can see it: a clone does not carry it, no file records it, and `git log` never shows it changing. So before marking a pull request ready for the first time in a repository, find out whether the branch being relied on enforces anything, and report what was actually observed. On a host with a command for it, ask the host; on GitHub, `gh ruleset check --default` and the branch-protection endpoint both answer read-only. Where there is no way to ask, say that the state is unknown rather than assuming either answer — silence is not a pass, and a boundary reported as verified without being observed is worse than one reported as unknown. + +When the host reports that the branch enforces what the boundary needs, record what was observed and mark the pull request ready without interrupting the human. The question is asked once in a repository, not turned into a ritual at every candidate, and an adequate answer is the end of it. + +When enforcement is missing, inadequate, or unknown, stop and tell the human plainly what is absent — force-push and deletion blocked, the validation check required, pull requests required, an empty bypass list — and offer to configure what the host allows. Propose the exact commands and apply them only on explicit authorization in that exchange; repository configuration is the human's decision, and an agent that changed it unasked would be acting exactly where nobody can see. A human who declines or defers has answered: mark the pull request ready as usual and state in the readiness handoff that the boundary is unenforced, with the reason given. The decline is recorded because it is evidence about the method, not because it is a failure. + +Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding. This fail-safe covers blocking findings only; never claim a chat-only finding has equivalent protection. Any agent that edits an existing PR becomes the updater for that turn. Before editing, fetch the PR and record its hosted head; push only normal fast-forward updates, never force. If the head changed underneath the turn or a push is rejected as non-fast-forward, fetch and reconcile without overwriting remote work, then rerun verification and review on the resulting commit. A repair pushed to a ready PR returns it to draft until the repaired head has its own verification and clean review pass. If the PR merged or closed, stop without pushing — the one case where a turn ends unpushed — report the work and where it stands, and never create a follow-up change without explicit human scope. -Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above, rerun verification and review on the resulting commit, and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. +Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. -After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change; simple work may still proceed under explicit user authority, and the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. +After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change, though the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. diff --git a/.agents/skills/clue-upgrade/skill.md b/.agents/skills/clue-upgrade/skill.md index 1377d3c..bd12f17 100644 --- a/.agents/skills/clue-upgrade/skill.md +++ b/.agents/skills/clue-upgrade/skill.md @@ -1,6 +1,6 @@ --- cliewen-skill: true -version: 0.24.1 +version: 0.26.0 --- diff --git a/.agents/skills/clue-verify/references/agentic-review-loop.md b/.agents/skills/clue-verify/references/agentic-review-loop.md index dde19f1..1055bb7 100644 --- a/.agents/skills/clue-verify/references/agentic-review-loop.md +++ b/.agents/skills/clue-verify/references/agentic-review-loop.md @@ -11,6 +11,6 @@ Run this loop automatically; never ask the human to clear context or initiate a - A finding whose substance is a count, total, population figure, or arithmetic disagreement is **advisory** whatever the brief called it; a wrong, missing, or reused identity remains **blocking**. The reviewer spends no pass re-deriving figures; that is the author's verification work before readiness. - For an existing hosted PR, bind the result to its observed head. Under the **Review boundary**, publish blocking findings as unresolved hosted review conversations where supported; advisories stay in the verification handoff rather than becoming repair-required conversations, and the isolated reviewer itself remains read-only. 4. For every added or changed acceptance criterion, compare each scenario against its referenced tests' setup, action, and assertions. Record an advisory verdict for the acceptance brief: `verifies`, `verifies-something-adjacent`, or `undetermined`. This scenario-resolution result is not an actionable finding and does not gate `clue validate`; if it exposes a real defect, report that defect through the ordinary finding lifecycle. A `Human`-class criterion has no test to compare — name it in the brief instead, stating that the brief line is its proof, rather than recording a scenario-resolution verdict for it. -5. Resolve every blocking finding in the implementing context. A finding that requires a new decision or changed intent becomes an open question and stops the change. Otherwise the implementing context becomes the updater for that turn, follows the **Review boundary**, commits and pushes the repairs with the turn that made them, and reruns applicable local checks against the repaired commit. Advisories are carried in the verification evidence, not in unresolved repair-required review conversations, and never gate the ready mark. An advisory repair may ride before a review pass already required by a blocking repair; an advisory first reported by a pass with no blocking findings stays in the handoff for a later change, because editing the clean commit would create a new candidate that the exact-commit boundary requires reviewing. -6. Start a new review pass after every blocking repair; a previous clean result applies only to the commit it reviewed. Scope that pass to the diff since the reviewed commit plus the carriers those files declare, not to the whole change again — re-auditing unchanged work is what makes each pass cost as much as the first. An advisory finding alone does not start another pass, so the loop terminates on a pass with no blocking findings without changing its reviewed commit. **At most five passes** run for one change. That is a maximum, never a quota: the ordinary case is one pass that finds nothing blocking, and a further pass runs only when the immediately preceding pass returned at least one blocking finding. When the maximum is reached and blocking findings remain, stop and report them to the human — what was found, not how many passes ran — and ask whether to run further passes; only that answer runs another. Five is the default; a repository that wants a different maximum states it in its own `AGENTS.md` conventions, and that number governs there. Continue until the current commit receives a pass with no blocking findings. Do not mark the PR ready with unresolved blocking findings or without such a pass, whether or not the maximum was reached; the pushed branch and its draft PR simply show where the work stands. +5. Resolve every blocking finding in the implementing context. A finding that requires a new decision or changed intent becomes an open question and stops the change. Otherwise the implementing context becomes the updater for that turn, follows the **Review boundary**, commits and pushes the repairs with the turn that made them, and reruns applicable local checks against the repaired commit. Advisories never gate the ready mark. An advisory repair may ride before a review pass already required by a blocking repair; an advisory first reported by a pass with no blocking findings stays in the handoff for a later change, under the **Review boundary**'s exact-commit rule. +6. Start a new review pass after every blocking repair; a previous clean result applies only to the commit it reviewed. Scope that pass to the diff since the reviewed commit plus the carriers those files declare, not to the whole change again — re-auditing unchanged work is what makes each pass cost as much as the first. An advisory finding alone does not start another pass, so the loop terminates on a pass with no blocking findings without changing its reviewed commit. **At most five passes** run for one change. That is a maximum, never a quota: the ordinary case is one pass that finds nothing blocking, and a further pass runs only when the immediately preceding pass returned at least one blocking finding. When the maximum is reached and blocking findings remain, stop and report them to the human — what was found, not how many passes ran — and ask whether to run further passes; only that answer runs another. Five is the default; a repository that wants a different maximum states it in its own `AGENTS.md` conventions, and that number governs there. Continue until the current commit receives a pass with no blocking findings. Do not mark the PR ready with unresolved blocking findings or without such a pass, whether or not the maximum was reached. 7. Report the final review mode, reviewed commit, number of review passes run, and advisory findings left open with the verification evidence. diff --git a/.agents/skills/clue-verify/references/change-scope-and-tiers.md b/.agents/skills/clue-verify/references/change-scope-and-tiers.md index adeb5e2..38f84fc 100644 --- a/.agents/skills/clue-verify/references/change-scope-and-tiers.md +++ b/.agents/skills/clue-verify/references/change-scope-and-tiers.md @@ -7,4 +7,4 @@ Before editing, inspect the smallest relevant context and tell the user `Recomme Paths, file counts, and changed-line counts may warn but never decide meaning. Reassess when a discovery expands semantic scope and against the complete diff before integration. If simple work grows into full work, pause and recommend the full loop. If the user explicitly declines, proceed as simple without making code, tests, or durable documentation untruthful, and add all three trailers to the final authored commit: `Cliewen-Route: simple`, `Cliewen-Recommendation: full`, and `Cliewen-Override: user chose simple; `. This records one integration authorization in Git history, not a corpus decision. -A route does not authorize a push. Push directly to an integration branch only with explicit user authorization and repository permission; otherwise follow the repository's requested workflow. A human may integrate by any mechanism the repository permits, and repository-local conventions may be stricter. A release is not a Cliewen route: each adopter defines or omits its own release process, whose work is classified by accepted-contract impact. +A route does not authorize a push; the [Review boundary](review-boundary.md) states when an agent may push to an integration branch. A human may integrate by any mechanism the repository permits, and repository-local conventions may be stricter. A release is not a Cliewen route: each adopter defines or omits its own release process, whose work is classified by accepted-contract impact. diff --git a/.agents/skills/clue-verify/references/durable-work-state.md b/.agents/skills/clue-verify/references/durable-work-state.md index db7e1d4..bf6cba8 100644 --- a/.agents/skills/clue-verify/references/durable-work-state.md +++ b/.agents/skills/clue-verify/references/durable-work-state.md @@ -4,6 +4,16 @@ An agent's private memory is never where work lives. Anything needed to implemen A suggestion raised mid-change is triaged immediately, into one of two carriers, never into memory. If the change is wrong or incomplete without it, it becomes a task in `tasks.md`, handled before merge. Otherwise it becomes a goal with `status: proposed`, written in the digest so it survives the workspace's deletion. Neither carrier is optional, and "I will remember" is not a third: a suggestion that is neither actioned nor recorded has been declined without anyone deciding to decline it. State which carrier a suggestion went to, and why, when the triage happens. +A reusable discovery earns capture only past an eligibility bar: it cost something to find — a wrong first attempt, an undocumented flag, a nonobvious recovery — and is plausibly recurring, so a fresh agent doing the same class of task would hit it again. Restating already-documented behaviour, or something observed once with no reason to expect recurrence, is not eligible; documenting an ineligible discovery is how a workaround hardens into policy. + +An eligible discovery is captured under these rules: + +- **Fix before documenting.** Ask whether the confusing step can instead be removed or automated; only what cannot yet be fixed gets written down. +- **Home.** A capability-specific discovery goes into that capability's own `design.md`; a discovery about running the repository's own tooling, tied to no single capability, goes into the repository's own contributor or operational guidance (for example `CONTRIBUTING.md`), where one exists. Correct an existing home in preference to writing beside it. +- **Shape and reach.** State the discovery's trigger, prerequisites, procedure, expected result, and recovery, and reach it from where the matching work already begins so finding it does not require reading every guide. +- **Scope.** One observation in one session supports only a claim scoped to what was actually seen — the platform, the command form, the version — never a general claim from a single trial. +- **Retirement.** Correct or retire guidance in the same change that finds it stale, the same way any other design-document content is kept current; it carries no separate lifecycle or tombstone. + A durable record never states a figure a command computes — an artifact count, a coverage percentage, a reported population size. Name the command instead. A number written into prose becomes a hand-maintained obligation that goes stale on the next change and that every later reviewer re-derives, and repairing one writes new prose carrying new numbers, so the finding regenerates instead of converging. Measurements that are the point of a record — an analysis's own results, a milestone's observed evidence — are stated with what produced them and when. -After a human reports a Cliewen change's merge, orient before starting anything else: describe the plan's next unfinished step in plain language and ask whether to start it, or say that the plan has nothing left and ask what comes next. +When a user asks what is next, run `clue next` before proposing work. It reports the first unfinished milestone in an active plan, gives alternatives with `--all`, and names unfinished rows in draft plans as proposed rather than actionable. Read the selected plan context, check that the plan still holds, and ask before starting. After a human reports a Cliewen change's merge, use the same orientation path before beginning anything else. diff --git a/.agents/skills/clue-verify/references/review-boundary.md b/.agents/skills/clue-verify/references/review-boundary.md index dddbc96..32e0307 100644 --- a/.agents/skills/clue-verify/references/review-boundary.md +++ b/.agents/skills/clue-verify/references/review-boundary.md @@ -6,16 +6,22 @@ Every full change branches from the current tip of `main`, never from unaccepted For a full Cliewen change, the human accepts the ready pull request with a merge commit. Configure the protected default branch to allow merge commits and disable squash and rebase-and-merge: the merge commit keeps the proposal, implementation, digest, and durable corpus commits reachable from `main`, while the other modes can discard or rewrite that reviewed chain. Because publication begins with the first commit, there is no unpublished branch to rebase: hosted history is never rewritten. A forge that cannot enforce the merge-commit boundary is outside the supported full-change adoption path. -Inside the full loop, this rule applies. Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. +Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. The PR exists from first publication and starts as a draft: a full change opens it right after the proposal commit. The draft is where unfinished work lives and is visible; it claims nothing and cannot be merged. Marking the PR ready for review is the explicit act that claims a candidate, taken only when local verification and the automatic agentic review loop have passed on the current commit and the hosted head equals it. The PR is the completed proposal's authorization and protected-integration boundary, not a demand for duplicate human code review: the agent may prepare and publish the candidate, but only a human-controlled PR merge accepts it. A substantive edit to a ready PR returns it to draft until its new head has earned the same binding. Inside this boundary, an agent never merges its own PR, creates a local merge commit into `main`, or pushes to `main`. A PR alone displays hosted CI but does not enforce it. Where hosting supports enforcement, the PR triggers CI, branch protection makes its required status check a merge precondition, and the agent cannot silently skip the gate. On a draft, the checks that judge a completed candidate — the digest gate and the acceptance-brief requirement — do not yet apply; they bind when the PR is marked ready and on `main`, and because the forge cannot merge a draft, the merge gate stays whole. Never weaken the workflow or required-check policy to make a change pass. -Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding; this fail-safe applies to blocking findings, while advisories stay in the handoff; never claim a chat-only finding has equivalent protection. +Because that enforcement lives at the Git host rather than in the repository, no check that reads files can see it: a clone does not carry it, no file records it, and `git log` never shows it changing. So before marking a pull request ready for the first time in a repository, find out whether the branch being relied on enforces anything, and report what was actually observed. On a host with a command for it, ask the host; on GitHub, `gh ruleset check --default` and the branch-protection endpoint both answer read-only. Where there is no way to ask, say that the state is unknown rather than assuming either answer — silence is not a pass, and a boundary reported as verified without being observed is worse than one reported as unknown. + +When the host reports that the branch enforces what the boundary needs, record what was observed and mark the pull request ready without interrupting the human. The question is asked once in a repository, not turned into a ritual at every candidate, and an adequate answer is the end of it. + +When enforcement is missing, inadequate, or unknown, stop and tell the human plainly what is absent — force-push and deletion blocked, the validation check required, pull requests required, an empty bypass list — and offer to configure what the host allows. Propose the exact commands and apply them only on explicit authorization in that exchange; repository configuration is the human's decision, and an agent that changed it unasked would be acting exactly where nobody can see. A human who declines or defers has answered: mark the pull request ready as usual and state in the readiness handoff that the boundary is unenforced, with the reason given. The decline is recorded because it is evidence about the method, not because it is a failure. + +Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding. This fail-safe covers blocking findings only; never claim a chat-only finding has equivalent protection. Any agent that edits an existing PR becomes the updater for that turn. Before editing, fetch the PR and record its hosted head; push only normal fast-forward updates, never force. If the head changed underneath the turn or a push is rejected as non-fast-forward, fetch and reconcile without overwriting remote work, then rerun verification and review on the resulting commit. A repair pushed to a ready PR returns it to draft until the repaired head has its own verification and clean review pass. If the PR merged or closed, stop without pushing — the one case where a turn ends unpushed — report the work and where it stands, and never create a follow-up change without explicit human scope. -Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above, rerun verification and review on the resulting commit, and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. +Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. -After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change; simple work may still proceed under explicit user authority, and the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. +After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change, though the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. diff --git a/.agents/skills/clue-verify/references/verification-checklist.md b/.agents/skills/clue-verify/references/verification-checklist.md index 8d92b8d..3b9e092 100644 --- a/.agents/skills/clue-verify/references/verification-checklist.md +++ b/.agents/skills/clue-verify/references/verification-checklist.md @@ -1,6 +1,6 @@ ## Verification checklist -Run this verification and review workflow before marking a full Cliewen PR ready for review. Pushing inside that loop needs no verification — every changed turn pushes under the [Review boundary](review-boundary.md) — but the readiness claim does: complete the local checks and agentic review loop before marking the PR ready, and complete the hosted-head check immediately after. Simple work uses only checks relevant to its changed surfaces and does not invoke this skill. When the `clue` CLI exists, `clue validate` performs the mechanical half; until then, check by hand. Never fix a failure by weakening the check. +Run this verification and review workflow before marking a full Cliewen PR ready for review, and its hosted-head check immediately after. Pushing inside the loop needs no verification: every changed turn pushes under the [Review boundary](review-boundary.md). Simple work uses only checks relevant to its changed surfaces and does not invoke this skill. When the `clue` CLI exists, `clue validate` performs the mechanical half; until then, check by hand. Never fix a failure by weakening the check. - [ ] The change uses the correct workspace under [Change routing](change-scope-and-tiers.md). - [ ] Every artifact touched has frontmatter `id`, `type`, `status`, `links`, and `title`, plus decision `author`/`accepted-by`, constraint `source`/`enforcement`, capability `goal`, and any other type-specific fields. diff --git a/.agents/skills/clue-verify/skill.md b/.agents/skills/clue-verify/skill.md index 852f1f1..6561108 100644 --- a/.agents/skills/clue-verify/skill.md +++ b/.agents/skills/clue-verify/skill.md @@ -1,6 +1,6 @@ --- cliewen-skill: true -version: 0.24.1 +version: 0.26.0 --- diff --git a/.claude/skills/clue-analysis/SKILL.md b/.claude/skills/clue-analysis/SKILL.md index b3e664d..eeb3485 100644 --- a/.claude/skills/clue-analysis/SKILL.md +++ b/.claude/skills/clue-analysis/SKILL.md @@ -1,6 +1,6 @@ --- cliewen-skill: true -version: 0.24.1 +version: 0.26.0 --- diff --git a/.claude/skills/clue-delta/SKILL.md b/.claude/skills/clue-delta/SKILL.md index 2af6c46..84233b7 100644 --- a/.claude/skills/clue-delta/SKILL.md +++ b/.claude/skills/clue-delta/SKILL.md @@ -1,6 +1,6 @@ --- cliewen-skill: true -version: 0.24.1 +version: 0.26.0 --- @@ -16,6 +16,7 @@ Read each reference when its condition is reached, before taking action governed - Before recommending a route or starting a full change, read [Change routing](references/change-scope-and-tiers.md). - Before branching, publishing, updating a hosted PR, or handing work to a human, read [Review boundary](references/review-boundary.md). - After the user chooses the recommended full loop, read [Change loop](references/change-loop.md). +- Before writing the proposal for a consequential change, read [Challenge a consequential commitment](references/challenge-commitments.md). - When the change touches what the product means, or the acceptance brief must state the vision it proceeds under, read [Intent model](references/intent-model.md). - When the change makes, rejects, or carries a decision, read [Decision records](references/decision-records.md). - Before applying repository-specific implementation or digest rules, read [Repository-local conventions](references/repository-local-conventions.md). diff --git a/.claude/skills/clue-delta/references/change-loop.md b/.claude/skills/clue-delta/references/change-loop.md index 76b1bb4..8d2af75 100644 --- a/.claude/skills/clue-delta/references/change-loop.md +++ b/.claude/skills/clue-delta/references/change-loop.md @@ -2,12 +2,20 @@ Use when the user chooses the full Cliewen loop recommended for accepted-contract change. Simple work is recommended before this skill and does not invoke it. Apply [Decision records](decision-records.md), [Repository-local conventions](repository-local-conventions.md), and [Durable work state](durable-work-state.md) throughout the loop. -1. **Branch:** Follow the review boundary, get the next CH identity with `clue id next CH`, and name the branch `ch-xxx-slug` with that identity. The command follows the ledger's tracked coordination mode. When it warns that allocation is local and contributors may work in parallel clones or worktrees, stop and either serialize allocation on the integration branch or have a maintainer enable Git coordination with `clue id coordinate` before contributors branch. A contributor given a preallocated identity runs `clue id sync`, uses that reservation, and never allocates independently from a stale local ledger. If remote allocation fails, do not guess, reuse, or edit the number by hand; retry or sync the allocator's permanent claims. Coordination settings live in `.clue/id-coordination.yaml`, not in the ledger; commit both after `clue id coordinate`, and treat a merge conflict in that file as the user's decision about which remote the team meant, never yours to resolve. Never re-point an established repository at a different remote. When a command reports that Git's union merge combined the ledger, the identities are intact: run `clue id repair`, or let the next command that saves the ledger rewrite it, and never hand-edit an append-only log. If two artifacts hold one identity, allocate a fresh one for the later artifact and update its references rather than renumbering either by hand. +1. **Branch:** Follow the review boundary, get the next CH identity with `clue id next CH`, and name the branch `ch-xxx-slug` with that identity. + - The command follows the ledger's tracked coordination mode. When it warns that allocation is local and contributors may work in parallel clones or worktrees, stop and either serialize allocation on the integration branch or have a maintainer enable Git coordination with `clue id coordinate` before contributors branch. A contributor given a preallocated identity runs `clue id sync`, uses that reservation, and never allocates independently from a stale local ledger. If remote allocation fails, do not guess, reuse, or edit the number by hand; retry or sync the allocator's permanent claims. + - Coordination settings live in `.clue/id-coordination.yaml`, not in the ledger; commit both after `clue id coordinate`, and treat a merge conflict in that file as the user's decision about which remote the team meant, never yours to resolve. Never re-point an established repository at a different remote. + - When a command reports that Git's union merge combined the ledger, the identities are intact: run `clue id repair`, or let the next command that saves the ledger rewrite it, and never hand-edit an append-only log. If two artifacts hold one identity, allocate a fresh one for the later artifact and update its references rather than renumbering either by hand. 2. **Propose:** Create `/changes/CH-xxx-slug/`, commit and push it before implementation, and open the draft PR under the review boundary: - `proposal.md` states what and why; its frontmatter `links` names the real plan item it serves or explicitly declares the change plan-less. - `tasks.md` is an ordered `- [ ]` checklist with dependencies first and at most one nested level. Mark an infeasible task `[-]` with its reason on the same line, whenever it is marked. A behavior-changing task names the acceptance-criterion IDs it serves; if none exists, add the criterion before implementation. Tests trace to criteria, never transient tasks. - - `open-questions.md` records blocking questions. When one appears, write it and stop; the human answer becomes a decision record. + - `open-questions.md` records blocking questions. When one appears, write it and stop; record the human answer as a decision only when it is future-shaping. - A human may opt into a spec-first pause after Propose. Record the pause in `tasks.md`, report briefly what the proposal says and what implementation involves, and ask whether implementation should begin — the proposal is already committed, pushed, and visible on the draft PR. Stop until the human directs work to continue; otherwise proceed directly to Implement. -3. **Implement:** Update the permanent corpus. Before and after implementation, assess documentation impact: keep the required architecture and design overviews current when their structure or cross-cutting behaviour changes, update the relevant capability design or general design document when it answers a reader's question, and link rather than duplicate. State in the change or pull-request handoff which durable documentation changed, or why none was needed; do not create a permanent change-history document. Architecture owns actors, boundaries, and durable technology choices; `docs/design/README.md` owns cross-cutting flows and patterns; a capability's `design.md` owns local detail. Draft a missing overview from repository evidence, and ask the human only when a material boundary or intent remains unclear. Use Mermaid when a diagram materially clarifies a relationship, boundary, or flow; retain SVG only when Mermaid is inadequate. A relevant new or materially revised ADR or IDR links to the affected overview. Capabilities own README, criteria, and design files. Write criteria as Gherkin tagged with their canonical `-[lowercase-suffix]` identity; every new or materially revised criterion declares `Test-type: Unit|Integration|E2E|Performance|Human` on the first line of its scenario body and gets focused positive and negative evidence in that class (or records `(single-direction)` when only one direction exists). `Human` needs no code evidence — the acceptance brief's criteria line is its proof; use it for a criterion deliberately verified by human judgment, never as a placeholder for a test not written. A criterion genuinely not yet proven carries `@draft` on its tag line instead, exempting only that criterion from the active-file test requirement — the capability itself does not need to stay `draft` because one criterion is unproven. Every test declares exactly one purpose: the criterion ID, `Unit`, `Sanity`, or `Arch`, using framework tags where available and the normalized test-name prefix in Go; AC evidence also carries its declared test type and direction. On the JVM, all three evidence parts attach to the same Java or Kotlin executable through literal JUnit method tags or the stable `test[lowercase-suffix]__` name; class tags, comments, and unrelated methods cannot supply missing parts. When a criterion's meaning changes, retire it with `@retired`, keep the tombstone, mint a new ID, and remove or retag its tests. +3. **Implement:** + - Before starting or resuming work for a milestone, assess whether its plan still serves the goal, the milestone remains wanted and achievable, and the remaining dependencies and order still hold. Repeat the assessment when new evidence challenges the campaign. A passing assessment needs no record. When it fails, write the mismatch and options in `open-questions.md` and pause affected work for human direction. After direction, declare the selected revision in the plan; record it only when the selected course is future-shaping. + - Update the permanent corpus. Before and after implementation, assess documentation impact: keep the required architecture and design overviews current when their structure or cross-cutting behaviour changes, update the relevant capability design or general design document when it answers a reader's question, and link rather than duplicate. State in the change or pull-request handoff which durable documentation changed, or why none was needed; do not create a permanent change-history document. Architecture owns actors, boundaries, and durable technology choices; `docs/design/README.md` owns cross-cutting flows and patterns; a capability's `design.md` owns local detail. Draft a missing overview from repository evidence, and ask the human only when a material boundary or intent remains unclear. Use Mermaid when a diagram materially clarifies a relationship, boundary, or flow; retain SVG only when Mermaid is inadequate. A relevant new or materially revised ADR or IDR links to the affected overview. + - Capabilities own README, criteria, and design files. Write criteria as Gherkin tagged with their canonical `-[lowercase-suffix]` identity; every new or materially revised criterion declares `Test-type: Unit|Integration|E2E|Performance|Human` on the first line of its scenario body and gets focused positive and negative evidence in that class (or records `(single-direction)` when only one direction exists). `Human` needs no code evidence — the acceptance brief's criteria line is its proof; use it for a criterion deliberately verified by human judgment, never as a placeholder for a test not written. A criterion genuinely not yet proven carries `@draft` on its tag line instead, exempting only that criterion from the active-file test requirement — the capability itself does not need to stay `draft` because one criterion is unproven. + - Every test declares exactly one purpose: the criterion ID, `Unit`, `Sanity`, or `Arch`, using framework tags where available and the normalized test-name prefix in Go; AC evidence also carries its declared test type and direction. On the JVM, all three evidence parts attach to the same Java or Kotlin executable through literal JUnit method tags or the stable `test[lowercase-suffix]__` name; class tags, comments, and unrelated methods cannot supply missing parts. + - When a criterion's meaning changes, retire it with `@retired`, keep the tombstone, mint a new ID, and remove or retag its tests. 4. **Digest:** After every task is `[x]` or `[-]` with a reason, update permanent `/docs`, regenerate README indexes, apply repository-local digest conventions, record decisions, and update plan bookkeeping. Retiring a non-criterion artifact means deleting its file in this same digest — never leaving a `status: retired` file behind — and naming the dead ID in a `supersedes:` field on its successor or best live next stop; criteria tombstones (`@retired`, file kept so the test tag keeps failing) and completed plans (frozen, never deleted) are the named exceptions. Delete the change workspace. The digest is never a task in `tasks.md`; deletion is the digest, so a self-referential digest task cannot be completed honestly. 5. **Verify, review, and propose for acceptance:** Run `clue-verify`, including its automatic agentic review loop on the verified committed candidate, then mark the draft PR ready under the [Review boundary](review-boundary.md). For a full change, fill the acceptance brief at the top of the PR body with the plan item and whether it remains wanted, every added or changed criterion and its scenario-resolution verdict — naming any newly or materially declared `Human`-class criterion there as its proof — and what merge binds or supersedes, including any authorized unmerged base and the meaning accepting this change would bind before that base is accepted; keep it to one screen and never leave template placeholders. Never ask the human to initiate the review. Merging accepts the change; decision provenance follows [Decision records](decision-records.md). diff --git a/.claude/skills/clue-delta/references/change-scope-and-tiers.md b/.claude/skills/clue-delta/references/change-scope-and-tiers.md index adeb5e2..38f84fc 100644 --- a/.claude/skills/clue-delta/references/change-scope-and-tiers.md +++ b/.claude/skills/clue-delta/references/change-scope-and-tiers.md @@ -7,4 +7,4 @@ Before editing, inspect the smallest relevant context and tell the user `Recomme Paths, file counts, and changed-line counts may warn but never decide meaning. Reassess when a discovery expands semantic scope and against the complete diff before integration. If simple work grows into full work, pause and recommend the full loop. If the user explicitly declines, proceed as simple without making code, tests, or durable documentation untruthful, and add all three trailers to the final authored commit: `Cliewen-Route: simple`, `Cliewen-Recommendation: full`, and `Cliewen-Override: user chose simple; `. This records one integration authorization in Git history, not a corpus decision. -A route does not authorize a push. Push directly to an integration branch only with explicit user authorization and repository permission; otherwise follow the repository's requested workflow. A human may integrate by any mechanism the repository permits, and repository-local conventions may be stricter. A release is not a Cliewen route: each adopter defines or omits its own release process, whose work is classified by accepted-contract impact. +A route does not authorize a push; the [Review boundary](review-boundary.md) states when an agent may push to an integration branch. A human may integrate by any mechanism the repository permits, and repository-local conventions may be stricter. A release is not a Cliewen route: each adopter defines or omits its own release process, whose work is classified by accepted-contract impact. diff --git a/.claude/skills/clue-delta/references/durable-work-state.md b/.claude/skills/clue-delta/references/durable-work-state.md index db7e1d4..bf6cba8 100644 --- a/.claude/skills/clue-delta/references/durable-work-state.md +++ b/.claude/skills/clue-delta/references/durable-work-state.md @@ -4,6 +4,16 @@ An agent's private memory is never where work lives. Anything needed to implemen A suggestion raised mid-change is triaged immediately, into one of two carriers, never into memory. If the change is wrong or incomplete without it, it becomes a task in `tasks.md`, handled before merge. Otherwise it becomes a goal with `status: proposed`, written in the digest so it survives the workspace's deletion. Neither carrier is optional, and "I will remember" is not a third: a suggestion that is neither actioned nor recorded has been declined without anyone deciding to decline it. State which carrier a suggestion went to, and why, when the triage happens. +A reusable discovery earns capture only past an eligibility bar: it cost something to find — a wrong first attempt, an undocumented flag, a nonobvious recovery — and is plausibly recurring, so a fresh agent doing the same class of task would hit it again. Restating already-documented behaviour, or something observed once with no reason to expect recurrence, is not eligible; documenting an ineligible discovery is how a workaround hardens into policy. + +An eligible discovery is captured under these rules: + +- **Fix before documenting.** Ask whether the confusing step can instead be removed or automated; only what cannot yet be fixed gets written down. +- **Home.** A capability-specific discovery goes into that capability's own `design.md`; a discovery about running the repository's own tooling, tied to no single capability, goes into the repository's own contributor or operational guidance (for example `CONTRIBUTING.md`), where one exists. Correct an existing home in preference to writing beside it. +- **Shape and reach.** State the discovery's trigger, prerequisites, procedure, expected result, and recovery, and reach it from where the matching work already begins so finding it does not require reading every guide. +- **Scope.** One observation in one session supports only a claim scoped to what was actually seen — the platform, the command form, the version — never a general claim from a single trial. +- **Retirement.** Correct or retire guidance in the same change that finds it stale, the same way any other design-document content is kept current; it carries no separate lifecycle or tombstone. + A durable record never states a figure a command computes — an artifact count, a coverage percentage, a reported population size. Name the command instead. A number written into prose becomes a hand-maintained obligation that goes stale on the next change and that every later reviewer re-derives, and repairing one writes new prose carrying new numbers, so the finding regenerates instead of converging. Measurements that are the point of a record — an analysis's own results, a milestone's observed evidence — are stated with what produced them and when. -After a human reports a Cliewen change's merge, orient before starting anything else: describe the plan's next unfinished step in plain language and ask whether to start it, or say that the plan has nothing left and ask what comes next. +When a user asks what is next, run `clue next` before proposing work. It reports the first unfinished milestone in an active plan, gives alternatives with `--all`, and names unfinished rows in draft plans as proposed rather than actionable. Read the selected plan context, check that the plan still holds, and ask before starting. After a human reports a Cliewen change's merge, use the same orientation path before beginning anything else. diff --git a/.claude/skills/clue-delta/references/intent-model.md b/.claude/skills/clue-delta/references/intent-model.md index 9d3debd..f712092 100644 --- a/.claude/skills/clue-delta/references/intent-model.md +++ b/.claude/skills/clue-delta/references/intent-model.md @@ -36,6 +36,6 @@ Recommend for or against one, say why, and let the human decide. A use case is c ### Marking what is not yet confirmed -Agent-drafted intent is `status: draft` with `provenance: inferred` and a stated `reversal-cost`, and its assumptions and open questions stay visible in the artifact. Promotion is a human act. Never present an inference as a fact, and never resolve a contradiction between sources by picking the convenient reading — record it and ask. +Agent-drafted intent is `status: draft` with `provenance: inferred` and `reversal-cost: low|high`; low explicitly permits deferral, while high can block an active capability that directly depends on the artifact. Once a human verifies the meaning, remove `reversal-cost`; it is no longer used. Assumptions and open questions stay visible in the artifact. Promotion is a human act. Never present an inference as a fact, and never resolve a contradiction between sources by picking the convenient reading — record it and ask. **A full change's acceptance brief states the vision it proceeds under**, or states that the repository has none and that the change proceeds without one. When unresolved meaning would materially change what the system is for, stop and ask rather than deciding it inside an implementation. diff --git a/.claude/skills/clue-delta/references/review-boundary.md b/.claude/skills/clue-delta/references/review-boundary.md index dddbc96..32e0307 100644 --- a/.claude/skills/clue-delta/references/review-boundary.md +++ b/.claude/skills/clue-delta/references/review-boundary.md @@ -6,16 +6,22 @@ Every full change branches from the current tip of `main`, never from unaccepted For a full Cliewen change, the human accepts the ready pull request with a merge commit. Configure the protected default branch to allow merge commits and disable squash and rebase-and-merge: the merge commit keeps the proposal, implementation, digest, and durable corpus commits reachable from `main`, while the other modes can discard or rewrite that reviewed chain. Because publication begins with the first commit, there is no unpublished branch to rebase: hosted history is never rewritten. A forge that cannot enforce the merge-commit boundary is outside the supported full-change adoption path. -Inside the full loop, this rule applies. Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. +Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. The PR exists from first publication and starts as a draft: a full change opens it right after the proposal commit. The draft is where unfinished work lives and is visible; it claims nothing and cannot be merged. Marking the PR ready for review is the explicit act that claims a candidate, taken only when local verification and the automatic agentic review loop have passed on the current commit and the hosted head equals it. The PR is the completed proposal's authorization and protected-integration boundary, not a demand for duplicate human code review: the agent may prepare and publish the candidate, but only a human-controlled PR merge accepts it. A substantive edit to a ready PR returns it to draft until its new head has earned the same binding. Inside this boundary, an agent never merges its own PR, creates a local merge commit into `main`, or pushes to `main`. A PR alone displays hosted CI but does not enforce it. Where hosting supports enforcement, the PR triggers CI, branch protection makes its required status check a merge precondition, and the agent cannot silently skip the gate. On a draft, the checks that judge a completed candidate — the digest gate and the acceptance-brief requirement — do not yet apply; they bind when the PR is marked ready and on `main`, and because the forge cannot merge a draft, the merge gate stays whole. Never weaken the workflow or required-check policy to make a change pass. -Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding; this fail-safe applies to blocking findings, while advisories stay in the handoff; never claim a chat-only finding has equivalent protection. +Because that enforcement lives at the Git host rather than in the repository, no check that reads files can see it: a clone does not carry it, no file records it, and `git log` never shows it changing. So before marking a pull request ready for the first time in a repository, find out whether the branch being relied on enforces anything, and report what was actually observed. On a host with a command for it, ask the host; on GitHub, `gh ruleset check --default` and the branch-protection endpoint both answer read-only. Where there is no way to ask, say that the state is unknown rather than assuming either answer — silence is not a pass, and a boundary reported as verified without being observed is worse than one reported as unknown. + +When the host reports that the branch enforces what the boundary needs, record what was observed and mark the pull request ready without interrupting the human. The question is asked once in a repository, not turned into a ritual at every candidate, and an adequate answer is the end of it. + +When enforcement is missing, inadequate, or unknown, stop and tell the human plainly what is absent — force-push and deletion blocked, the validation check required, pull requests required, an empty bypass list — and offer to configure what the host allows. Propose the exact commands and apply them only on explicit authorization in that exchange; repository configuration is the human's decision, and an agent that changed it unasked would be acting exactly where nobody can see. A human who declines or defers has answered: mark the pull request ready as usual and state in the readiness handoff that the boundary is unenforced, with the reason given. The decline is recorded because it is evidence about the method, not because it is a failure. + +Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding. This fail-safe covers blocking findings only; never claim a chat-only finding has equivalent protection. Any agent that edits an existing PR becomes the updater for that turn. Before editing, fetch the PR and record its hosted head; push only normal fast-forward updates, never force. If the head changed underneath the turn or a push is rejected as non-fast-forward, fetch and reconcile without overwriting remote work, then rerun verification and review on the resulting commit. A repair pushed to a ready PR returns it to draft until the repaired head has its own verification and clean review pass. If the PR merged or closed, stop without pushing — the one case where a turn ends unpushed — report the work and where it stands, and never create a follow-up change without explicit human scope. -Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above, rerun verification and review on the resulting commit, and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. +Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. -After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change; simple work may still proceed under explicit user authority, and the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. +After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change, though the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. diff --git a/.claude/skills/clue-extract/SKILL.md b/.claude/skills/clue-extract/SKILL.md index 957f346..9a1d493 100644 --- a/.claude/skills/clue-extract/SKILL.md +++ b/.claude/skills/clue-extract/SKILL.md @@ -1,6 +1,6 @@ --- cliewen-skill: true -version: 0.24.1 +version: 0.26.0 --- diff --git a/.claude/skills/clue-extract/references/durable-work-state.md b/.claude/skills/clue-extract/references/durable-work-state.md index db7e1d4..bf6cba8 100644 --- a/.claude/skills/clue-extract/references/durable-work-state.md +++ b/.claude/skills/clue-extract/references/durable-work-state.md @@ -4,6 +4,16 @@ An agent's private memory is never where work lives. Anything needed to implemen A suggestion raised mid-change is triaged immediately, into one of two carriers, never into memory. If the change is wrong or incomplete without it, it becomes a task in `tasks.md`, handled before merge. Otherwise it becomes a goal with `status: proposed`, written in the digest so it survives the workspace's deletion. Neither carrier is optional, and "I will remember" is not a third: a suggestion that is neither actioned nor recorded has been declined without anyone deciding to decline it. State which carrier a suggestion went to, and why, when the triage happens. +A reusable discovery earns capture only past an eligibility bar: it cost something to find — a wrong first attempt, an undocumented flag, a nonobvious recovery — and is plausibly recurring, so a fresh agent doing the same class of task would hit it again. Restating already-documented behaviour, or something observed once with no reason to expect recurrence, is not eligible; documenting an ineligible discovery is how a workaround hardens into policy. + +An eligible discovery is captured under these rules: + +- **Fix before documenting.** Ask whether the confusing step can instead be removed or automated; only what cannot yet be fixed gets written down. +- **Home.** A capability-specific discovery goes into that capability's own `design.md`; a discovery about running the repository's own tooling, tied to no single capability, goes into the repository's own contributor or operational guidance (for example `CONTRIBUTING.md`), where one exists. Correct an existing home in preference to writing beside it. +- **Shape and reach.** State the discovery's trigger, prerequisites, procedure, expected result, and recovery, and reach it from where the matching work already begins so finding it does not require reading every guide. +- **Scope.** One observation in one session supports only a claim scoped to what was actually seen — the platform, the command form, the version — never a general claim from a single trial. +- **Retirement.** Correct or retire guidance in the same change that finds it stale, the same way any other design-document content is kept current; it carries no separate lifecycle or tombstone. + A durable record never states a figure a command computes — an artifact count, a coverage percentage, a reported population size. Name the command instead. A number written into prose becomes a hand-maintained obligation that goes stale on the next change and that every later reviewer re-derives, and repairing one writes new prose carrying new numbers, so the finding regenerates instead of converging. Measurements that are the point of a record — an analysis's own results, a milestone's observed evidence — are stated with what produced them and when. -After a human reports a Cliewen change's merge, orient before starting anything else: describe the plan's next unfinished step in plain language and ask whether to start it, or say that the plan has nothing left and ask what comes next. +When a user asks what is next, run `clue next` before proposing work. It reports the first unfinished milestone in an active plan, gives alternatives with `--all`, and names unfinished rows in draft plans as proposed rather than actionable. Read the selected plan context, check that the plan still holds, and ask before starting. After a human reports a Cliewen change's merge, use the same orientation path before beginning anything else. diff --git a/.claude/skills/clue-extract/references/intent-model.md b/.claude/skills/clue-extract/references/intent-model.md index 9d3debd..f712092 100644 --- a/.claude/skills/clue-extract/references/intent-model.md +++ b/.claude/skills/clue-extract/references/intent-model.md @@ -36,6 +36,6 @@ Recommend for or against one, say why, and let the human decide. A use case is c ### Marking what is not yet confirmed -Agent-drafted intent is `status: draft` with `provenance: inferred` and a stated `reversal-cost`, and its assumptions and open questions stay visible in the artifact. Promotion is a human act. Never present an inference as a fact, and never resolve a contradiction between sources by picking the convenient reading — record it and ask. +Agent-drafted intent is `status: draft` with `provenance: inferred` and `reversal-cost: low|high`; low explicitly permits deferral, while high can block an active capability that directly depends on the artifact. Once a human verifies the meaning, remove `reversal-cost`; it is no longer used. Assumptions and open questions stay visible in the artifact. Promotion is a human act. Never present an inference as a fact, and never resolve a contradiction between sources by picking the convenient reading — record it and ask. **A full change's acceptance brief states the vision it proceeds under**, or states that the repository has none and that the change proceeds without one. When unresolved meaning would materially change what the system is for, stop and ask rather than deciding it inside an implementation. diff --git a/.claude/skills/clue-extract/references/rehearsal-before-mutation.md b/.claude/skills/clue-extract/references/rehearsal-before-mutation.md index cdd3523..8b1a8cb 100644 --- a/.claude/skills/clue-extract/references/rehearsal-before-mutation.md +++ b/.claude/skills/clue-extract/references/rehearsal-before-mutation.md @@ -4,8 +4,8 @@ After the extraction's full change is proposed, begin with a mandatory report-on The rehearsal report inventories source formats and entry points, proposed artifact mappings, preserved and minted IDs, confidence and reversal cost, test-purpose work, instruction conflicts, planned deletions, and named plan doors. An unresolved conflict becomes an `open-questions.md` entry and stops before mutation. -The rehearsal also writes a pinned source manifest under the change workspace: the exact source revision and location read, and one proof-class, direction, and evidence-location row for every classified reference a criterion has, or one declared exclusion with reason, or one `draft`/`human`/`retired` disposition with a readable justification, its particular `disposition-source-location`, and its own existing target milestone as `plan-door`. This is the same manifest `clue parity` compares against the corpus it derives — write it once here rather than reconstructing it afterward. +The rehearsal also writes a pinned source manifest under the change workspace: the exact source revision and location read, and one proof-class, direction, and evidence-location row for every classified reference a criterion has, or one declared exclusion with reason, or one `draft`/`human`/`retired` disposition with a readable justification, its particular `disposition-source-location`, and its own existing target milestone as `plan-door`. `clue parity` compares the derived corpus against this manifest. -The rehearsal also writes a pinned carrier inventory under the change workspace: the same source revision and location, every source-repository path the migration will delete (`deleted-paths`), and one row per operational carrier found — an `instruction`, `workflow`, `freshness-input`, `registry`, `link`, or `diagram-asset` — naming its `id`, `kind`, and `source-path`, plus either its mapped `target-path` and content `fingerprint`, or an explicit `blocked: true` with a `reason` when no target exists yet. This is the same inventory `clue carriers` reconciles against the corpus it derives — write it once here rather than reconstructing it afterward. +The rehearsal also writes a pinned carrier inventory under the change workspace: the same source revision and location, every source-repository path the migration will delete (`deleted-paths`), and one row per operational carrier found — an `instruction`, `workflow`, `freshness-input`, `registry`, `link`, or `diagram-asset` — naming its `id`, `kind`, and `source-path`, plus either its mapped `target-path` and content `fingerprint`, or an explicit `blocked: true` with a `reason` when no target exists yet. `clue carriers` reconciles the derived corpus against this inventory. Write both once here rather than reconstructing them afterward. Only explicit human direction begins the existing full extraction change's mutate phase. That phase digests the rehearsal into the durable extraction report under `/docs/analysis`, then performs the accepted conversion; the ready PR deletes both the transient change workspace and the parallel source corpus. diff --git a/.claude/skills/clue-extract/references/review-boundary.md b/.claude/skills/clue-extract/references/review-boundary.md index dddbc96..32e0307 100644 --- a/.claude/skills/clue-extract/references/review-boundary.md +++ b/.claude/skills/clue-extract/references/review-boundary.md @@ -6,16 +6,22 @@ Every full change branches from the current tip of `main`, never from unaccepted For a full Cliewen change, the human accepts the ready pull request with a merge commit. Configure the protected default branch to allow merge commits and disable squash and rebase-and-merge: the merge commit keeps the proposal, implementation, digest, and durable corpus commits reachable from `main`, while the other modes can discard or rewrite that reviewed chain. Because publication begins with the first commit, there is no unpublished branch to rebase: hosted history is never rewritten. A forge that cannot enforce the merge-commit boundary is outside the supported full-change adoption path. -Inside the full loop, this rule applies. Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. +Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. The PR exists from first publication and starts as a draft: a full change opens it right after the proposal commit. The draft is where unfinished work lives and is visible; it claims nothing and cannot be merged. Marking the PR ready for review is the explicit act that claims a candidate, taken only when local verification and the automatic agentic review loop have passed on the current commit and the hosted head equals it. The PR is the completed proposal's authorization and protected-integration boundary, not a demand for duplicate human code review: the agent may prepare and publish the candidate, but only a human-controlled PR merge accepts it. A substantive edit to a ready PR returns it to draft until its new head has earned the same binding. Inside this boundary, an agent never merges its own PR, creates a local merge commit into `main`, or pushes to `main`. A PR alone displays hosted CI but does not enforce it. Where hosting supports enforcement, the PR triggers CI, branch protection makes its required status check a merge precondition, and the agent cannot silently skip the gate. On a draft, the checks that judge a completed candidate — the digest gate and the acceptance-brief requirement — do not yet apply; they bind when the PR is marked ready and on `main`, and because the forge cannot merge a draft, the merge gate stays whole. Never weaken the workflow or required-check policy to make a change pass. -Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding; this fail-safe applies to blocking findings, while advisories stay in the handoff; never claim a chat-only finding has equivalent protection. +Because that enforcement lives at the Git host rather than in the repository, no check that reads files can see it: a clone does not carry it, no file records it, and `git log` never shows it changing. So before marking a pull request ready for the first time in a repository, find out whether the branch being relied on enforces anything, and report what was actually observed. On a host with a command for it, ask the host; on GitHub, `gh ruleset check --default` and the branch-protection endpoint both answer read-only. Where there is no way to ask, say that the state is unknown rather than assuming either answer — silence is not a pass, and a boundary reported as verified without being observed is worse than one reported as unknown. + +When the host reports that the branch enforces what the boundary needs, record what was observed and mark the pull request ready without interrupting the human. The question is asked once in a repository, not turned into a ritual at every candidate, and an adequate answer is the end of it. + +When enforcement is missing, inadequate, or unknown, stop and tell the human plainly what is absent — force-push and deletion blocked, the validation check required, pull requests required, an empty bypass list — and offer to configure what the host allows. Propose the exact commands and apply them only on explicit authorization in that exchange; repository configuration is the human's decision, and an agent that changed it unasked would be acting exactly where nobody can see. A human who declines or defers has answered: mark the pull request ready as usual and state in the readiness handoff that the boundary is unenforced, with the reason given. The decline is recorded because it is evidence about the method, not because it is a failure. + +Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding. This fail-safe covers blocking findings only; never claim a chat-only finding has equivalent protection. Any agent that edits an existing PR becomes the updater for that turn. Before editing, fetch the PR and record its hosted head; push only normal fast-forward updates, never force. If the head changed underneath the turn or a push is rejected as non-fast-forward, fetch and reconcile without overwriting remote work, then rerun verification and review on the resulting commit. A repair pushed to a ready PR returns it to draft until the repaired head has its own verification and clean review pass. If the PR merged or closed, stop without pushing — the one case where a turn ends unpushed — report the work and where it stands, and never create a follow-up change without explicit human scope. -Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above, rerun verification and review on the resulting commit, and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. +Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. -After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change; simple work may still proceed under explicit user authority, and the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. +After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change, though the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. diff --git a/.claude/skills/clue-extract/references/target-contract.md b/.claude/skills/clue-extract/references/target-contract.md index a37b9ab..d3a21d0 100644 --- a/.claude/skills/clue-extract/references/target-contract.md +++ b/.claude/skills/clue-extract/references/target-contract.md @@ -3,13 +3,13 @@ The extraction PR is complete only when all of these hold: 1. **The full taxonomy and system overviews exist:** `/docs` has goals, plans, capabilities, decisions, constraints, analysis, architecture, and design, with an indexed README in every folder and README, criteria, and design files in each capability folder. `docs/architecture/README.md` is a concise evidence-based overview of actors, boundaries, components, and durable technology choices; `docs/design/README.md` is a concise overview of cross-cutting flows, interactions, and patterns. Extract the big picture, not every local detail: capability `design.md` remains the local home. Survey the source for suitable existing overview documents and visual assets. Before moving any found overview into the canonical path, present one grouped source-to-target mapping and link rewrites to the human; move only after explicit consent. If consent is declined, keep the source and write a concise canonical pointer rather than duplicate it. Where evidence cannot establish a material boundary or intent, ask the human; otherwise draft the overview as inferred repository truth. Use Mermaid when it materially clarifies a relationship or flow, retaining SVG when Mermaid is inadequate. A folder with nothing real to hold stays empty but indexed. An index row states its record and says what the artifact is about; index generation seeds that sentence from the artifact's own body, and you correct it rather than leaving a seed that reads as a summary but states a problem. -2. **Everything extracted is born inferred and decisions route by subject:** Use `provenance: inferred` plus `reversal-cost: low|high` on every non-decision artifact, classifying whether its meaning is cheap and local or expensive to reverse. A future-shaping decision instead uses `status: inferred` and `author: agent`, routing to ADR for architecture, PDR for project/process, or IDR for implementation; routine facts and history do not become records. Human review may promote records to `verified`, file by file or in bulk. An active capability cannot depend by one `links:` edge on high-cost inferred meaning, while low-cost inferred findings may remain legitimately deferred. Extracted decisions also follow [Decision records](decision-records.md). A legacy decision log is inventoried row by row in the rehearsal and remains until a reviewed full change classifies every future-shaping choice and explicitly accounts for discarded narrative; extraction never guesses or silently drops a row. +2. **Everything extracted is born inferred and decisions route by subject:** Use `provenance: inferred` plus `reversal-cost: low|high` on every non-decision artifact, classifying whether its meaning is cheap and local or expensive to reverse. Low explicitly permits deferral; high-cost inferred meaning blocks an active capability joined to it by one links edge. When a human promotes the artifact to `verified`, remove `reversal-cost` because the classification has been consumed. A future-shaping decision instead uses `status: inferred` and `author: agent`, routing to ADR for architecture, PDR for project/process, or IDR for implementation; routine facts and history do not become records. Extracted decisions also follow [Decision records](decision-records.md). A legacy decision log is inventoried row by row in the rehearsal and remains until a reviewed full change classifies every future-shaping choice and explicitly accounts for discarded narrative; extraction never guesses or silently drops a row. 3. **Existing criterion IDs survive; a criterion with none is minted deterministically:** Declare each capability's namespace with `ac-prefix:` and keep source IDs verbatim — never renumber, since IDs are meaning-immutable and existing test tags must keep resolving. A namespace may contain one or more uppercase alphanumeric segments joined by single hyphens, and a canonical criterion ID may carry a lowercase letter suffix after its numeric portion; case and punctuation are exact in the corpus. When a source requirement carries no stable ID of its own, mint one in its capability's `ac-prefix:` namespace: take the requirements without IDs in the source's own stated or file order and assign the next numeric slot after the maximum numeric component already declared in that namespace, ignoring letter suffixes for the maximum; an empty namespace starts at one. The corpus is the registry, a minted ID never collides with one kept verbatim, and the same source state always mints the same IDs. Record the preserved and minted mapping in the extraction report below. 4. **Every test keeps or gains exactly one purpose without losing source evidence:** Existing criterion tags remain. Untagged tests get `Unit`, `Sanity`, or `Arch` according to intent. On the JVM, normalize each supported Java or Kotlin executable so its canonical AC identity, proof type, and direction attach together through literal JUnit method tags or the stable `test[lowercase-suffix]__` name; remove hyphens from segmented prefixes only in the named form and use underscores for hyphens in literal JUnit tags. A multi-criterion executable or class-level criterion tag is a semantic conflict: the rehearsal inventories its location, identities, behavior or structural scope, and proposed resolution, while a normalizer reports it but never deletes, selects, or relocates a tag. After explicit human direction, split a multi-criterion test into one-criterion executables that retain the relevant assertions, or keep one reviewed primary identity and record every other one as needing dedicated proof or an explicit `@draft` criterion. Move a class-level identity only to the executable that actually proves it or to a scoped new test; if that work is explicitly out of scope, record its source location and named plan door with an explicit `@draft` criterion. Comments, dynamic or multi-line tag expressions, and metadata split across methods are unsupported evidence; record and resolve the gap instead of installing an external rule or letting `clue` guess. 5. **Evidence status is explicit at the narrowest honest level:** Whole-file draft phasing remains available: a capability whose extracted criteria are not ready for active use stays `status: draft`, and the extraction report names the gap and plan door. An active criteria file may also phase individual promises: tag each genuinely not-yet-proven criterion `@draft`, exempting only that criterion while evidence-backed siblings remain active. A genuine `Test-type: Human` criterion is already proven by naming it in the pull request acceptance brief and needs no code reference; it is not a placeholder for a missing test. Machine-proven criteria use supported Go, per-executable JVM, or Cucumber evidence classified by their declared `Unit`, `Integration`, `E2E`, or `Performance` type and positive/negative direction, with `(single-direction)` only when one direction is honest; legacy criteria without a declared proof type retain the one-supported-reference rule. A capability is therefore not the smallest activation unit. Extraction is never partial by silent omission: every draft file or criterion states why it is draft and names the change that will prove it. 6. **`clue validate` is green before the PR is marked ready:** The extracted corpus is judged by the same rules as a greenfield corpus. -7. **`clue parity` is clean before the source corpus is deleted:** Run it against the rehearsal's source manifest and fix every missing criterion, orphaned tag, changed direction or evidence location, stale source fingerprint, and unjustified `draft`/`human`/`retired` disposition it reports; a migration workflow uploads a failing or passing report as a CI artifact. A clean run is what makes the source deletion in the next item honest — coverage the manifest cannot account for stays in the source until it can. -8. **`clue carriers` is clean before the source corpus is deleted:** Run it against the rehearsal's carrier inventory and fix every stale deleted-path reference, lost fingerprint, and missing asset it reports; a migration workflow uploads a failing or passing report as a CI artifact the same way `clue parity`'s does. Every operational carrier the rehearsal found — instruction, workflow, freshness-input, registry, link, or diagram-asset — maps to a retained target or carries an explicit `blocked` marker with a reason; a clean run is what makes the source deletion in the next item honest for carriers, the same way a clean `clue parity` run makes it honest for criteria. +7. **`clue parity` is clean before the source corpus is deleted:** Run it against the rehearsal's source manifest and fix every missing criterion, orphaned tag, changed direction or evidence location, stale source fingerprint, and unjustified `draft`/`human`/`retired` disposition it reports; a migration workflow uploads a failing or passing report as a CI artifact. A clean run is what makes the source deletion in item 9 honest — coverage the manifest cannot account for stays in the source until it can. +8. **`clue carriers` is clean before the source corpus is deleted:** Run it against the rehearsal's carrier inventory and fix every stale deleted-path reference, lost fingerprint, and missing asset it reports, uploading the report as `clue parity`'s is. Every operational carrier the rehearsal found maps to a retained target or carries an explicit `blocked` marker with a reason; a clean run makes the source deletion in item 9 honest for carriers, as a clean `clue parity` run does for criteria. 9. **The source corpus dies in the same PR without losing its links:** Delete parallel specification trees, registries, and source-format skills only after every retained link and asset is preserved. A deterministic source-to-Cliewen mapping rewrites a source target to its converted target; an unmapped target is a finding that stops destructive source deletion, never a reason to remove the link or asset. Git history is the archive once the mapping is complete. Two systems of record is zero systems of record. A hand-maintained per-folder index file is one of these, whatever it is called: absorb what it says into that folder's README index rows first — its description column becomes the row's sentence, and any column that only restates a `links:` edge is dropped rather than carried, because `clue context` already walks those edges — then delete the file. Two indexes in one folder is the same failure as two corpora, and the generated block will otherwise list the hand-maintained one among its own entries. Adopters carrying several such files rarely agree on their columns; map each one on what it says, not on its heading. A source repository's still-open pending change is a distinct case: do not delete its in-flight work until its `imported-change` record's status reaches `complete` — `clue` cannot check this itself, since it never reads the source repository, so the refusal is this rehearsal's own judgment, not a validator rule. 10. **Routing is rewritten and reconciled:** Point every assistant entry point the repository carries — `AGENTS.md` and any other assistant-specific entry file, such as `CLAUDE.md` or `.cursor/rules` — to `/docs/README.md` and the installed `clue-*` skills; `AGENTS.md` is the flagship instance of this class, not its only member. Absorb compatible pre-existing instructions as repository-local conventions; record conflicts as open questions. 11. **An extraction report lands in `/docs/analysis`, and its figures are rendered rather than typed:** The mutate phase digests the rehearsal into the report, recording what was found, what mapped where, and what was dropped and why. The report's criterion counts and mapping table live in one region opened by `` and closed by ``, rendered by `clue report ` from the same pinned source manifest `clue parity` compares; `clue validate` re-renders the region and fails on any difference, so a report cannot state a population or a mapping the manifest never held. The report summarizes the mapping; the pinned manifest remains the per-criterion detail, and no second committed per-criterion registry is created. Prose outside the region is yours, and a figure that belongs to the manifest belongs inside it; a marker written in a code span or a fenced block is an example, so a document may describe the contract without becoming a report. diff --git a/.claude/skills/clue-plan/SKILL.md b/.claude/skills/clue-plan/SKILL.md index d527151..8958df3 100644 --- a/.claude/skills/clue-plan/SKILL.md +++ b/.claude/skills/clue-plan/SKILL.md @@ -1,6 +1,6 @@ --- cliewen-skill: true -version: 0.24.1 +version: 0.26.0 --- @@ -16,4 +16,5 @@ Read each reference when its condition is reached, before taking action governed - Before creating or revising a plan, read [Planning workflow](references/planning-workflow.md). - Before deciding which goals a plan serves, and whether any journey needs a use case, read [Intent model](references/intent-model.md). - When the repository states no usable vision, read [Intent discovery](references/intent-discovery.md). +- Before adopting or revising a plan's promise, read [Challenge a consequential commitment](references/challenge-commitments.md). - When plan meaning or another consequential choice is recorded, read [Decision records](references/decision-records.md). diff --git a/.claude/skills/clue-plan/references/intent-model.md b/.claude/skills/clue-plan/references/intent-model.md index 9d3debd..f712092 100644 --- a/.claude/skills/clue-plan/references/intent-model.md +++ b/.claude/skills/clue-plan/references/intent-model.md @@ -36,6 +36,6 @@ Recommend for or against one, say why, and let the human decide. A use case is c ### Marking what is not yet confirmed -Agent-drafted intent is `status: draft` with `provenance: inferred` and a stated `reversal-cost`, and its assumptions and open questions stay visible in the artifact. Promotion is a human act. Never present an inference as a fact, and never resolve a contradiction between sources by picking the convenient reading — record it and ask. +Agent-drafted intent is `status: draft` with `provenance: inferred` and `reversal-cost: low|high`; low explicitly permits deferral, while high can block an active capability that directly depends on the artifact. Once a human verifies the meaning, remove `reversal-cost`; it is no longer used. Assumptions and open questions stay visible in the artifact. Promotion is a human act. Never present an inference as a fact, and never resolve a contradiction between sources by picking the convenient reading — record it and ask. **A full change's acceptance brief states the vision it proceeds under**, or states that the repository has none and that the change proceeds without one. When unresolved meaning would materially change what the system is for, stop and ask rather than deciding it inside an implementation. diff --git a/.claude/skills/clue-plan/references/planning-workflow.md b/.claude/skills/clue-plan/references/planning-workflow.md index 21efe49..88f9e09 100644 --- a/.claude/skills/clue-plan/references/planning-workflow.md +++ b/.claude/skills/clue-plan/references/planning-workflow.md @@ -6,6 +6,6 @@ Use when creating a plan or changing what a plan promises. 2. Create or revise a plan through `clue-delta`; a plan mutation is itself a branch and PR. The digest is the plan file in `/docs/plans/`. 3. Keep plans as flat `P-xxx-slug.md` files with status in frontmatter (`draft` → `active` → `completed`). Milestones (`M-xxx`) are rows in the plan's milestone table, each with a verifiable exit criterion. 4. Treat semantic mutation and bookkeeping differently: - - **Semantic:** Direction, scope, milestone addition/removal, or anything else that changes the plan's promise requires human acceptance and a decision record under [Decision records](decision-records.md). Agents may propose; only humans accept. The default vehicle is a dedicated plan change and PR. A revision discovered during implementation may ride with that implementing change only when the PR declares the plan revision, a correctly typed decision record backs it, the PR calls it out for deliberate approval, and an explicit objection can revert the revision while leaving the milestone open without blocking the rest of the change. + - **Semantic:** Direction, scope, milestone addition/removal, or anything else that changes the plan's promise requires a declared revision and human direction. A revision may ride with the implementing change that uncovered it; use a plan-only change when no implementation is active or it makes the review clearer. A revision is not automatically a decision record: record one under [Decision records](decision-records.md) only when the selected course is a future-shaping choice. - **Bookkeeping:** Marking a milestone done belongs in the implementing change's merge digest, never a separate PR. Closing the plan is the same bookkeeping: the change completing the last milestone also sets it `completed`, in that digest. A campaign is over the moment its last milestone is evidenced, so leaving it `active` publishes an index claiming work is in flight that is not. Designate the successor plan there too when one is decided; not having decided one never holds the closure open. Every milestone's evidence must be in the table before that digest lands, because the closed plan is immutable afterwards. 5. Treat `status: completed` as immutable and never delete a completed plan. diff --git a/.claude/skills/clue-upgrade/SKILL.md b/.claude/skills/clue-upgrade/SKILL.md index 1377d3c..bd12f17 100644 --- a/.claude/skills/clue-upgrade/SKILL.md +++ b/.claude/skills/clue-upgrade/SKILL.md @@ -1,6 +1,6 @@ --- cliewen-skill: true -version: 0.24.1 +version: 0.26.0 --- diff --git a/.claude/skills/clue-upgrade/references/change-scope-and-tiers.md b/.claude/skills/clue-upgrade/references/change-scope-and-tiers.md index adeb5e2..38f84fc 100644 --- a/.claude/skills/clue-upgrade/references/change-scope-and-tiers.md +++ b/.claude/skills/clue-upgrade/references/change-scope-and-tiers.md @@ -7,4 +7,4 @@ Before editing, inspect the smallest relevant context and tell the user `Recomme Paths, file counts, and changed-line counts may warn but never decide meaning. Reassess when a discovery expands semantic scope and against the complete diff before integration. If simple work grows into full work, pause and recommend the full loop. If the user explicitly declines, proceed as simple without making code, tests, or durable documentation untruthful, and add all three trailers to the final authored commit: `Cliewen-Route: simple`, `Cliewen-Recommendation: full`, and `Cliewen-Override: user chose simple; `. This records one integration authorization in Git history, not a corpus decision. -A route does not authorize a push. Push directly to an integration branch only with explicit user authorization and repository permission; otherwise follow the repository's requested workflow. A human may integrate by any mechanism the repository permits, and repository-local conventions may be stricter. A release is not a Cliewen route: each adopter defines or omits its own release process, whose work is classified by accepted-contract impact. +A route does not authorize a push; the [Review boundary](review-boundary.md) states when an agent may push to an integration branch. A human may integrate by any mechanism the repository permits, and repository-local conventions may be stricter. A release is not a Cliewen route: each adopter defines or omits its own release process, whose work is classified by accepted-contract impact. diff --git a/.claude/skills/clue-upgrade/references/durable-work-state.md b/.claude/skills/clue-upgrade/references/durable-work-state.md index db7e1d4..bf6cba8 100644 --- a/.claude/skills/clue-upgrade/references/durable-work-state.md +++ b/.claude/skills/clue-upgrade/references/durable-work-state.md @@ -4,6 +4,16 @@ An agent's private memory is never where work lives. Anything needed to implemen A suggestion raised mid-change is triaged immediately, into one of two carriers, never into memory. If the change is wrong or incomplete without it, it becomes a task in `tasks.md`, handled before merge. Otherwise it becomes a goal with `status: proposed`, written in the digest so it survives the workspace's deletion. Neither carrier is optional, and "I will remember" is not a third: a suggestion that is neither actioned nor recorded has been declined without anyone deciding to decline it. State which carrier a suggestion went to, and why, when the triage happens. +A reusable discovery earns capture only past an eligibility bar: it cost something to find — a wrong first attempt, an undocumented flag, a nonobvious recovery — and is plausibly recurring, so a fresh agent doing the same class of task would hit it again. Restating already-documented behaviour, or something observed once with no reason to expect recurrence, is not eligible; documenting an ineligible discovery is how a workaround hardens into policy. + +An eligible discovery is captured under these rules: + +- **Fix before documenting.** Ask whether the confusing step can instead be removed or automated; only what cannot yet be fixed gets written down. +- **Home.** A capability-specific discovery goes into that capability's own `design.md`; a discovery about running the repository's own tooling, tied to no single capability, goes into the repository's own contributor or operational guidance (for example `CONTRIBUTING.md`), where one exists. Correct an existing home in preference to writing beside it. +- **Shape and reach.** State the discovery's trigger, prerequisites, procedure, expected result, and recovery, and reach it from where the matching work already begins so finding it does not require reading every guide. +- **Scope.** One observation in one session supports only a claim scoped to what was actually seen — the platform, the command form, the version — never a general claim from a single trial. +- **Retirement.** Correct or retire guidance in the same change that finds it stale, the same way any other design-document content is kept current; it carries no separate lifecycle or tombstone. + A durable record never states a figure a command computes — an artifact count, a coverage percentage, a reported population size. Name the command instead. A number written into prose becomes a hand-maintained obligation that goes stale on the next change and that every later reviewer re-derives, and repairing one writes new prose carrying new numbers, so the finding regenerates instead of converging. Measurements that are the point of a record — an analysis's own results, a milestone's observed evidence — are stated with what produced them and when. -After a human reports a Cliewen change's merge, orient before starting anything else: describe the plan's next unfinished step in plain language and ask whether to start it, or say that the plan has nothing left and ask what comes next. +When a user asks what is next, run `clue next` before proposing work. It reports the first unfinished milestone in an active plan, gives alternatives with `--all`, and names unfinished rows in draft plans as proposed rather than actionable. Read the selected plan context, check that the plan still holds, and ask before starting. After a human reports a Cliewen change's merge, use the same orientation path before beginning anything else. diff --git a/.claude/skills/clue-upgrade/references/review-boundary.md b/.claude/skills/clue-upgrade/references/review-boundary.md index dddbc96..32e0307 100644 --- a/.claude/skills/clue-upgrade/references/review-boundary.md +++ b/.claude/skills/clue-upgrade/references/review-boundary.md @@ -6,16 +6,22 @@ Every full change branches from the current tip of `main`, never from unaccepted For a full Cliewen change, the human accepts the ready pull request with a merge commit. Configure the protected default branch to allow merge commits and disable squash and rebase-and-merge: the merge commit keeps the proposal, implementation, digest, and durable corpus commits reachable from `main`, while the other modes can discard or rewrite that reviewed chain. Because publication begins with the first commit, there is no unpublished branch to rebase: hosted history is never rewritten. A forge that cannot enforce the merge-commit boundary is outside the supported full-change adoption path. -Inside the full loop, this rule applies. Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. +Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. The PR exists from first publication and starts as a draft: a full change opens it right after the proposal commit. The draft is where unfinished work lives and is visible; it claims nothing and cannot be merged. Marking the PR ready for review is the explicit act that claims a candidate, taken only when local verification and the automatic agentic review loop have passed on the current commit and the hosted head equals it. The PR is the completed proposal's authorization and protected-integration boundary, not a demand for duplicate human code review: the agent may prepare and publish the candidate, but only a human-controlled PR merge accepts it. A substantive edit to a ready PR returns it to draft until its new head has earned the same binding. Inside this boundary, an agent never merges its own PR, creates a local merge commit into `main`, or pushes to `main`. A PR alone displays hosted CI but does not enforce it. Where hosting supports enforcement, the PR triggers CI, branch protection makes its required status check a merge precondition, and the agent cannot silently skip the gate. On a draft, the checks that judge a completed candidate — the digest gate and the acceptance-brief requirement — do not yet apply; they bind when the PR is marked ready and on `main`, and because the forge cannot merge a draft, the merge gate stays whole. Never weaken the workflow or required-check policy to make a change pass. -Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding; this fail-safe applies to blocking findings, while advisories stay in the handoff; never claim a chat-only finding has equivalent protection. +Because that enforcement lives at the Git host rather than in the repository, no check that reads files can see it: a clone does not carry it, no file records it, and `git log` never shows it changing. So before marking a pull request ready for the first time in a repository, find out whether the branch being relied on enforces anything, and report what was actually observed. On a host with a command for it, ask the host; on GitHub, `gh ruleset check --default` and the branch-protection endpoint both answer read-only. Where there is no way to ask, say that the state is unknown rather than assuming either answer — silence is not a pass, and a boundary reported as verified without being observed is worse than one reported as unknown. + +When the host reports that the branch enforces what the boundary needs, record what was observed and mark the pull request ready without interrupting the human. The question is asked once in a repository, not turned into a ritual at every candidate, and an adequate answer is the end of it. + +When enforcement is missing, inadequate, or unknown, stop and tell the human plainly what is absent — force-push and deletion blocked, the validation check required, pull requests required, an empty bypass list — and offer to configure what the host allows. Propose the exact commands and apply them only on explicit authorization in that exchange; repository configuration is the human's decision, and an agent that changed it unasked would be acting exactly where nobody can see. A human who declines or defers has answered: mark the pull request ready as usual and state in the readiness handoff that the boundary is unenforced, with the reason given. The decline is recorded because it is evidence about the method, not because it is a failure. + +Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding. This fail-safe covers blocking findings only; never claim a chat-only finding has equivalent protection. Any agent that edits an existing PR becomes the updater for that turn. Before editing, fetch the PR and record its hosted head; push only normal fast-forward updates, never force. If the head changed underneath the turn or a push is rejected as non-fast-forward, fetch and reconcile without overwriting remote work, then rerun verification and review on the resulting commit. A repair pushed to a ready PR returns it to draft until the repaired head has its own verification and clean review pass. If the PR merged or closed, stop without pushing — the one case where a turn ends unpushed — report the work and where it stands, and never create a follow-up change without explicit human scope. -Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above, rerun verification and review on the resulting commit, and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. +Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. -After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change; simple work may still proceed under explicit user authority, and the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. +After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change, though the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. diff --git a/.claude/skills/clue-verify/SKILL.md b/.claude/skills/clue-verify/SKILL.md index 852f1f1..6561108 100644 --- a/.claude/skills/clue-verify/SKILL.md +++ b/.claude/skills/clue-verify/SKILL.md @@ -1,6 +1,6 @@ --- cliewen-skill: true -version: 0.24.1 +version: 0.26.0 --- diff --git a/.claude/skills/clue-verify/references/agentic-review-loop.md b/.claude/skills/clue-verify/references/agentic-review-loop.md index dde19f1..1055bb7 100644 --- a/.claude/skills/clue-verify/references/agentic-review-loop.md +++ b/.claude/skills/clue-verify/references/agentic-review-loop.md @@ -11,6 +11,6 @@ Run this loop automatically; never ask the human to clear context or initiate a - A finding whose substance is a count, total, population figure, or arithmetic disagreement is **advisory** whatever the brief called it; a wrong, missing, or reused identity remains **blocking**. The reviewer spends no pass re-deriving figures; that is the author's verification work before readiness. - For an existing hosted PR, bind the result to its observed head. Under the **Review boundary**, publish blocking findings as unresolved hosted review conversations where supported; advisories stay in the verification handoff rather than becoming repair-required conversations, and the isolated reviewer itself remains read-only. 4. For every added or changed acceptance criterion, compare each scenario against its referenced tests' setup, action, and assertions. Record an advisory verdict for the acceptance brief: `verifies`, `verifies-something-adjacent`, or `undetermined`. This scenario-resolution result is not an actionable finding and does not gate `clue validate`; if it exposes a real defect, report that defect through the ordinary finding lifecycle. A `Human`-class criterion has no test to compare — name it in the brief instead, stating that the brief line is its proof, rather than recording a scenario-resolution verdict for it. -5. Resolve every blocking finding in the implementing context. A finding that requires a new decision or changed intent becomes an open question and stops the change. Otherwise the implementing context becomes the updater for that turn, follows the **Review boundary**, commits and pushes the repairs with the turn that made them, and reruns applicable local checks against the repaired commit. Advisories are carried in the verification evidence, not in unresolved repair-required review conversations, and never gate the ready mark. An advisory repair may ride before a review pass already required by a blocking repair; an advisory first reported by a pass with no blocking findings stays in the handoff for a later change, because editing the clean commit would create a new candidate that the exact-commit boundary requires reviewing. -6. Start a new review pass after every blocking repair; a previous clean result applies only to the commit it reviewed. Scope that pass to the diff since the reviewed commit plus the carriers those files declare, not to the whole change again — re-auditing unchanged work is what makes each pass cost as much as the first. An advisory finding alone does not start another pass, so the loop terminates on a pass with no blocking findings without changing its reviewed commit. **At most five passes** run for one change. That is a maximum, never a quota: the ordinary case is one pass that finds nothing blocking, and a further pass runs only when the immediately preceding pass returned at least one blocking finding. When the maximum is reached and blocking findings remain, stop and report them to the human — what was found, not how many passes ran — and ask whether to run further passes; only that answer runs another. Five is the default; a repository that wants a different maximum states it in its own `AGENTS.md` conventions, and that number governs there. Continue until the current commit receives a pass with no blocking findings. Do not mark the PR ready with unresolved blocking findings or without such a pass, whether or not the maximum was reached; the pushed branch and its draft PR simply show where the work stands. +5. Resolve every blocking finding in the implementing context. A finding that requires a new decision or changed intent becomes an open question and stops the change. Otherwise the implementing context becomes the updater for that turn, follows the **Review boundary**, commits and pushes the repairs with the turn that made them, and reruns applicable local checks against the repaired commit. Advisories never gate the ready mark. An advisory repair may ride before a review pass already required by a blocking repair; an advisory first reported by a pass with no blocking findings stays in the handoff for a later change, under the **Review boundary**'s exact-commit rule. +6. Start a new review pass after every blocking repair; a previous clean result applies only to the commit it reviewed. Scope that pass to the diff since the reviewed commit plus the carriers those files declare, not to the whole change again — re-auditing unchanged work is what makes each pass cost as much as the first. An advisory finding alone does not start another pass, so the loop terminates on a pass with no blocking findings without changing its reviewed commit. **At most five passes** run for one change. That is a maximum, never a quota: the ordinary case is one pass that finds nothing blocking, and a further pass runs only when the immediately preceding pass returned at least one blocking finding. When the maximum is reached and blocking findings remain, stop and report them to the human — what was found, not how many passes ran — and ask whether to run further passes; only that answer runs another. Five is the default; a repository that wants a different maximum states it in its own `AGENTS.md` conventions, and that number governs there. Continue until the current commit receives a pass with no blocking findings. Do not mark the PR ready with unresolved blocking findings or without such a pass, whether or not the maximum was reached. 7. Report the final review mode, reviewed commit, number of review passes run, and advisory findings left open with the verification evidence. diff --git a/.claude/skills/clue-verify/references/change-scope-and-tiers.md b/.claude/skills/clue-verify/references/change-scope-and-tiers.md index adeb5e2..38f84fc 100644 --- a/.claude/skills/clue-verify/references/change-scope-and-tiers.md +++ b/.claude/skills/clue-verify/references/change-scope-and-tiers.md @@ -7,4 +7,4 @@ Before editing, inspect the smallest relevant context and tell the user `Recomme Paths, file counts, and changed-line counts may warn but never decide meaning. Reassess when a discovery expands semantic scope and against the complete diff before integration. If simple work grows into full work, pause and recommend the full loop. If the user explicitly declines, proceed as simple without making code, tests, or durable documentation untruthful, and add all three trailers to the final authored commit: `Cliewen-Route: simple`, `Cliewen-Recommendation: full`, and `Cliewen-Override: user chose simple; `. This records one integration authorization in Git history, not a corpus decision. -A route does not authorize a push. Push directly to an integration branch only with explicit user authorization and repository permission; otherwise follow the repository's requested workflow. A human may integrate by any mechanism the repository permits, and repository-local conventions may be stricter. A release is not a Cliewen route: each adopter defines or omits its own release process, whose work is classified by accepted-contract impact. +A route does not authorize a push; the [Review boundary](review-boundary.md) states when an agent may push to an integration branch. A human may integrate by any mechanism the repository permits, and repository-local conventions may be stricter. A release is not a Cliewen route: each adopter defines or omits its own release process, whose work is classified by accepted-contract impact. diff --git a/.claude/skills/clue-verify/references/durable-work-state.md b/.claude/skills/clue-verify/references/durable-work-state.md index db7e1d4..bf6cba8 100644 --- a/.claude/skills/clue-verify/references/durable-work-state.md +++ b/.claude/skills/clue-verify/references/durable-work-state.md @@ -4,6 +4,16 @@ An agent's private memory is never where work lives. Anything needed to implemen A suggestion raised mid-change is triaged immediately, into one of two carriers, never into memory. If the change is wrong or incomplete without it, it becomes a task in `tasks.md`, handled before merge. Otherwise it becomes a goal with `status: proposed`, written in the digest so it survives the workspace's deletion. Neither carrier is optional, and "I will remember" is not a third: a suggestion that is neither actioned nor recorded has been declined without anyone deciding to decline it. State which carrier a suggestion went to, and why, when the triage happens. +A reusable discovery earns capture only past an eligibility bar: it cost something to find — a wrong first attempt, an undocumented flag, a nonobvious recovery — and is plausibly recurring, so a fresh agent doing the same class of task would hit it again. Restating already-documented behaviour, or something observed once with no reason to expect recurrence, is not eligible; documenting an ineligible discovery is how a workaround hardens into policy. + +An eligible discovery is captured under these rules: + +- **Fix before documenting.** Ask whether the confusing step can instead be removed or automated; only what cannot yet be fixed gets written down. +- **Home.** A capability-specific discovery goes into that capability's own `design.md`; a discovery about running the repository's own tooling, tied to no single capability, goes into the repository's own contributor or operational guidance (for example `CONTRIBUTING.md`), where one exists. Correct an existing home in preference to writing beside it. +- **Shape and reach.** State the discovery's trigger, prerequisites, procedure, expected result, and recovery, and reach it from where the matching work already begins so finding it does not require reading every guide. +- **Scope.** One observation in one session supports only a claim scoped to what was actually seen — the platform, the command form, the version — never a general claim from a single trial. +- **Retirement.** Correct or retire guidance in the same change that finds it stale, the same way any other design-document content is kept current; it carries no separate lifecycle or tombstone. + A durable record never states a figure a command computes — an artifact count, a coverage percentage, a reported population size. Name the command instead. A number written into prose becomes a hand-maintained obligation that goes stale on the next change and that every later reviewer re-derives, and repairing one writes new prose carrying new numbers, so the finding regenerates instead of converging. Measurements that are the point of a record — an analysis's own results, a milestone's observed evidence — are stated with what produced them and when. -After a human reports a Cliewen change's merge, orient before starting anything else: describe the plan's next unfinished step in plain language and ask whether to start it, or say that the plan has nothing left and ask what comes next. +When a user asks what is next, run `clue next` before proposing work. It reports the first unfinished milestone in an active plan, gives alternatives with `--all`, and names unfinished rows in draft plans as proposed rather than actionable. Read the selected plan context, check that the plan still holds, and ask before starting. After a human reports a Cliewen change's merge, use the same orientation path before beginning anything else. diff --git a/.claude/skills/clue-verify/references/review-boundary.md b/.claude/skills/clue-verify/references/review-boundary.md index dddbc96..32e0307 100644 --- a/.claude/skills/clue-verify/references/review-boundary.md +++ b/.claude/skills/clue-verify/references/review-boundary.md @@ -6,16 +6,22 @@ Every full change branches from the current tip of `main`, never from unaccepted For a full Cliewen change, the human accepts the ready pull request with a merge commit. Configure the protected default branch to allow merge commits and disable squash and rebase-and-merge: the merge commit keeps the proposal, implementation, digest, and durable corpus commits reachable from `main`, while the other modes can discard or rewrite that reviewed chain. Because publication begins with the first commit, there is no unpublished branch to rebase: hosted history is never rewritten. A forge that cannot enforce the merge-commit boundary is outside the supported full-change adoption path. -Inside the full loop, this rule applies. Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. +Push is durability, never a signal. Every working turn that changed anything ends by committing and pushing the change branch, whatever state the work is in: an agent's local worktree is private memory, no handoff survives it, and a turn that ends without pushing has parked the work where no human, agent, or hosted check can see it. Committing and pushing claim nothing about readiness — the branch simply always holds the work as far as it got. A turn that changed nothing commits and pushes nothing, so a reviewed commit stays exactly as reviewed. The PR exists from first publication and starts as a draft: a full change opens it right after the proposal commit. The draft is where unfinished work lives and is visible; it claims nothing and cannot be merged. Marking the PR ready for review is the explicit act that claims a candidate, taken only when local verification and the automatic agentic review loop have passed on the current commit and the hosted head equals it. The PR is the completed proposal's authorization and protected-integration boundary, not a demand for duplicate human code review: the agent may prepare and publish the candidate, but only a human-controlled PR merge accepts it. A substantive edit to a ready PR returns it to draft until its new head has earned the same binding. Inside this boundary, an agent never merges its own PR, creates a local merge commit into `main`, or pushes to `main`. A PR alone displays hosted CI but does not enforce it. Where hosting supports enforcement, the PR triggers CI, branch protection makes its required status check a merge precondition, and the agent cannot silently skip the gate. On a draft, the checks that judge a completed candidate — the digest gate and the acceptance-brief requirement — do not yet apply; they bind when the PR is marked ready and on `main`, and because the forge cannot merge a draft, the merge gate stays whole. Never weaken the workflow or required-check policy to make a change pass. -Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding; this fail-safe applies to blocking findings, while advisories stay in the handoff; never claim a chat-only finding has equivalent protection. +Because that enforcement lives at the Git host rather than in the repository, no check that reads files can see it: a clone does not carry it, no file records it, and `git log` never shows it changing. So before marking a pull request ready for the first time in a repository, find out whether the branch being relied on enforces anything, and report what was actually observed. On a host with a command for it, ask the host; on GitHub, `gh ruleset check --default` and the branch-protection endpoint both answer read-only. Where there is no way to ask, say that the state is unknown rather than assuming either answer — silence is not a pass, and a boundary reported as verified without being observed is worse than one reported as unknown. + +When the host reports that the branch enforces what the boundary needs, record what was observed and mark the pull request ready without interrupting the human. The question is asked once in a repository, not turned into a ritual at every candidate, and an adequate answer is the end of it. + +When enforcement is missing, inadequate, or unknown, stop and tell the human plainly what is absent — force-push and deletion blocked, the validation check required, pull requests required, an empty bypass list — and offer to configure what the host allows. Propose the exact commands and apply them only on explicit authorization in that exchange; repository configuration is the human's decision, and an agent that changed it unasked would be acting exactly where nobody can see. A human who declines or defers has answered: mark the pull request ready as usual and state in the readiness handoff that the boundary is unenforced, with the reason given. The decline is recorded because it is evidence about the method, not because it is a failure. + +Every review of an existing hosted PR is bound to its observed head SHA. A clean result applies only to that commit; every substantive edit invalidates it. An advisory from a pass with no blocking findings stays in the verification handoff for a later change rather than editing the clean commit: the bounded loop is over, and an edit would create a new candidate that this exact-commit rule requires reviewing. A blocking finding is actionable durable PR state, not private agent memory: where the host supports resolvable review conversations, publish the finding there and leave it unresolved until a hosted commit contains the reviewed repair. Advisories do not become repair-required conversations. If the reviewer cannot publish a resolvable finding, report the PR as not merge-ready and disclose that the host cannot enforce the finding. This fail-safe covers blocking findings only; never claim a chat-only finding has equivalent protection. Any agent that edits an existing PR becomes the updater for that turn. Before editing, fetch the PR and record its hosted head; push only normal fast-forward updates, never force. If the head changed underneath the turn or a push is rejected as non-fast-forward, fetch and reconcile without overwriting remote work, then rerun verification and review on the resulting commit. A repair pushed to a ready PR returns it to draft until the repaired head has its own verification and clean review pass. If the PR merged or closed, stop without pushing — the one case where a turn ends unpushed — report the work and where it stands, and never create a follow-up change without explicit human scope. -Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above, rerun verification and review on the resulting commit, and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. +Ready means the hosted PR contains the exact locally reviewed and verified state, and marking it ready is the only claim of readiness. Before marking a change ready, commit every intended edit, run the applicable local verification and a clean agentic review pass against that commit, require `git status --porcelain` to be empty, push, and confirm that the hosted PR's head branch and SHA equal the current local branch and `HEAD`; then mark the PR ready and perform the hosted check again immediately after. Resolve satisfied review conversations only after the hosted head contains their reviewed repair. If either side differs, apply the updater rule above and check again. Stopping anywhere else is ordinary, not an exception: the branch is pushed, the PR is a draft, and no claim of readiness exists — say where the work stands rather than that a ready PR exists. -After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change; simple work may still proceed under explicit user authority, and the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. +After marking its initiated full PR ready and confirming its hosted head, an agent stops before initiating another full Cliewen change, though the agent may review or help update an existing PR under the handoff above. Review fixes stay on the same branch and PR and repeat the complete updater handoff before the PR is ready again. A follow-up full change exists only when a human has accepted this one and explicitly scoped the follow-up. diff --git a/.claude/skills/clue-verify/references/verification-checklist.md b/.claude/skills/clue-verify/references/verification-checklist.md index 8d92b8d..3b9e092 100644 --- a/.claude/skills/clue-verify/references/verification-checklist.md +++ b/.claude/skills/clue-verify/references/verification-checklist.md @@ -1,6 +1,6 @@ ## Verification checklist -Run this verification and review workflow before marking a full Cliewen PR ready for review. Pushing inside that loop needs no verification — every changed turn pushes under the [Review boundary](review-boundary.md) — but the readiness claim does: complete the local checks and agentic review loop before marking the PR ready, and complete the hosted-head check immediately after. Simple work uses only checks relevant to its changed surfaces and does not invoke this skill. When the `clue` CLI exists, `clue validate` performs the mechanical half; until then, check by hand. Never fix a failure by weakening the check. +Run this verification and review workflow before marking a full Cliewen PR ready for review, and its hosted-head check immediately after. Pushing inside the loop needs no verification: every changed turn pushes under the [Review boundary](review-boundary.md). Simple work uses only checks relevant to its changed surfaces and does not invoke this skill. When the `clue` CLI exists, `clue validate` performs the mechanical half; until then, check by hand. Never fix a failure by weakening the check. - [ ] The change uses the correct workspace under [Change routing](change-scope-and-tiers.md). - [ ] Every artifact touched has frontmatter `id`, `type`, `status`, `links`, and `title`, plus decision `author`/`accepted-by`, constraint `source`/`enforcement`, capability `goal`, and any other type-specific fields. diff --git a/.clue/id-ledger.yaml b/.clue/id-ledger.yaml index 843b482..462c4bd 100644 --- a/.clue/id-ledger.yaml +++ b/.clue/id-ledger.yaml @@ -166,6 +166,56 @@ events: - {id: AN-015, kind: numeric, state: live, prefix: AN, component: "15"} - {id: FIO-005, kind: numeric, state: reserved, prefix: FIO, component: "5"} - {id: FIO-005, kind: numeric, state: live, prefix: FIO, component: "5"} + - {id: M-005, kind: numeric, state: retired, prefix: M, component: "5"} + - {id: M-006, kind: numeric, state: live, prefix: M, component: "6"} + - {id: M-007, kind: numeric, state: retired, prefix: M, component: "7"} + - {id: M-101, kind: numeric, state: retired, prefix: M, component: "101"} + - {id: M-102, kind: numeric, state: retired, prefix: M, component: "102"} + - {id: M-103, kind: numeric, state: retired, prefix: M, component: "103"} + - {id: M-104, kind: numeric, state: retired, prefix: M, component: "104"} + - {id: M-105, kind: numeric, state: retired, prefix: M, component: "105"} + - {id: M-106, kind: numeric, state: retired, prefix: M, component: "106"} + - {id: M-107, kind: numeric, state: retired, prefix: M, component: "107"} + - {id: M-108, kind: numeric, state: retired, prefix: M, component: "108"} + - {id: M-109, kind: numeric, state: retired, prefix: M, component: "109"} + - {id: M-110, kind: numeric, state: retired, prefix: M, component: "110"} + - {id: M-111, kind: numeric, state: live, prefix: M, component: "111"} + - {id: M-112, kind: numeric, state: live, prefix: M, component: "112"} + - {id: M-113, kind: numeric, state: live, prefix: M, component: "113"} + - {id: M-114, kind: numeric, state: live, prefix: M, component: "114"} + - {id: M-115, kind: numeric, state: live, prefix: M, component: "115"} + - {id: M-116, kind: numeric, state: live, prefix: M, component: "116"} + - {id: M-117, kind: numeric, state: live, prefix: M, component: "117"} + - {id: M-118, kind: numeric, state: live, prefix: M, component: "118"} + - {id: M-119, kind: numeric, state: retired, prefix: M, component: "119"} + - {id: M-120, kind: numeric, state: retired, prefix: M, component: "120"} + - {id: M-121, kind: numeric, state: retired, prefix: M, component: "121"} + - {id: M-122, kind: numeric, state: retired, prefix: M, component: "122"} + - {id: M-123, kind: numeric, state: live, prefix: M, component: "123"} + - {id: M-124, kind: numeric, state: live, prefix: M, component: "124"} + - {id: M-125, kind: numeric, state: live, prefix: M, component: "125"} + - {id: M-126, kind: numeric, state: live, prefix: M, component: "126"} + - {id: M-127, kind: numeric, state: live, prefix: M, component: "127"} + - {id: M-128, kind: numeric, state: live, prefix: M, component: "128"} + - {id: M-129, kind: numeric, state: retired, prefix: M, component: "129"} + - {id: M-130, kind: numeric, state: live, prefix: M, component: "130"} + - {id: M-131, kind: numeric, state: retired, prefix: M, component: "131"} + - {id: M-132, kind: numeric, state: live, prefix: M, component: "132"} + - {id: M-133, kind: numeric, state: live, prefix: M, component: "133"} + - {id: M-134, kind: numeric, state: live, prefix: M, component: "134"} + - {id: M-135, kind: numeric, state: live, prefix: M, component: "135"} + - {id: M-136, kind: numeric, state: live, prefix: M, component: "136"} + - {id: M-137, kind: numeric, state: live, prefix: M, component: "137"} + - {id: M-138, kind: numeric, state: live, prefix: M, component: "138"} + - {id: M-139, kind: numeric, state: retired, prefix: M, component: "139"} + - {id: M-140, kind: numeric, state: retired, prefix: M, component: "140"} + - {id: M-141, kind: numeric, state: retired, prefix: M, component: "141"} + - {id: M-142, kind: numeric, state: retired, prefix: M, component: "142"} + - {id: M-143, kind: numeric, state: retired, prefix: M, component: "143"} + - {id: M-144, kind: numeric, state: retired, prefix: M, component: "144"} + - {id: M-145, kind: numeric, state: live, prefix: M, component: "145"} + - {id: M-146, kind: numeric, state: live, prefix: M, component: "146"} + - {id: M-147, kind: numeric, state: live, prefix: M, component: "147"} high-water: - {id: ADR-002, kind: numeric, state: reserved, prefix: ADR, component: "2"} - {id: AN-014, kind: numeric, state: reserved, prefix: AN, component: "14"} diff --git a/.github/workflows/clue.yml b/.github/workflows/clue.yml index 40d1714..6c72e84 100644 --- a/.github/workflows/clue.yml +++ b/.github/workflows/clue.yml @@ -18,10 +18,10 @@ permissions: jobs: validate: name: validate - uses: cliewen/cliewen/.github/workflows/clue-validation.yml@d98485188b0ae1505892bfdd2cafc22f8e890611 + uses: cliewen/cliewen/.github/workflows/clue-validation.yml@831166b796c9e524fe3265df2910ef88799840d5 with: runner: '["ubuntu-latest"]' - clue-version: 0.24.1 + clue-version: 0.26.0 # release rather than vendored: the binary is downloaded and its checksum # verified per run, so a multi-megabyte executable stays out of a repository # whose whole purpose is comparing robot behaviour. The version is pinned