diff --git a/CHANGELOG.md b/CHANGELOG.md index 39d4b8f..feed1d0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,16 @@ ## Unreleased +## 4.0.0 - 2026-09-07 + +- Make concise canonical Markdown fields/nested lists the public OPS record format; + reject legacy JSON in normal reads and prohibit fenced or hidden duplicate payloads. +- Require an explicitly authorized audited migration of OPS-generated records in place, + preserving IDs, authors and semantic evidence while excluding human content and Git history. +- Let a requested separate reviewer repair clear implementation-scope defects directly + on the same PR, record reviewer-as-contributor and verify the final head before readiness. +- Preserve paused-writer, declared-scope, personal commit/push and no-automatic-merge boundaries; + reviewer corrections are disclosed rather than represented as independently reviewed. - End ordinary worker delivery at REVIEW_READY; require an implementing-worker review request and a different task, with ordinary self-review only by explicit user approval. - Add MERGE_READY alongside REVIEW_READY after eligible review and current head/base/checks; diff --git a/README.md b/README.md index 6bc0d85..bf5b1e6 100644 --- a/README.md +++ b/README.md @@ -114,22 +114,30 @@ Read [worker coordination](references/worker-coordination.md) for named workers [PR review](references/pr-review.md) for review work. Reload the real source when another conversation may have updated it; existing context is not rewritten by filesystem changes. -### Worker succession in 3.0.0 +### Readable records and review repair in 4.0.0 Workers are replaceable execution owners. Project assignments, commits, PRs and tested checkpoints preserve continuity when chats disappear or a later model takes over. Explicit user approval transfers named work without waiting for a predecessor response; -existing IDs and v1 records remain valid. The changed transfer contract is the reason -for the major version, not an incompatible storage migration. +existing IDs and canonical Markdown record identities remain valid. Version 4 changes +the public record format and reviewer repair contract: normal OPS record reads no longer +fall back to legacy JSON. An explicitly authorized audited migration updates existing +OPS-generated records in place, excluding human/unmanaged content and Git history. The coordination reference defines collision-checked IDs, assignment lineage, OPS ownership/commit receipts, and `DEV`/`OPS` plus `OCCUPIED`/`REVIEW_READY` label synchronization. Ordinary implementation ends at `REVIEW_READY`. Code review requires the implementing worker's request and a different task; ordinary self-review needs explicit user approval. -A valid review and current head/base/checks add `MERGE_READY` alongside `REVIEW_READY`. +The separate reviewer directly fixes clear in-scope defects on the same PR, pauses the +original writer, and records its contribution. It does not claim independent review of +its own corrections. A valid review of the final head plus current checks adds +`MERGE_READY` alongside `REVIEW_READY`. Neither label grants merge rights; new edits or invalidated evidence remove `MERGE_READY`. -Personal accounts still author development commits and create PRs when the repository -separates those actions from OPS records. Labels do not grant ownership or merge authority. +Public records use concise headings and one authoritative set of Markdown fields and +nested lists, strictly parsed by tools. No JSON fences or hidden metadata duplicates are +published. Human-readable summaries link detailed evidence instead of dumping payloads. +Personal accounts still author development and reviewer repair commits and create PRs +when the repository separates those actions from OPS records. Labels do not grant ownership or merge authority. Conversation names follow ` | | `. Use supported official tools and verify the new title; otherwise provide the suggested @@ -144,8 +152,9 @@ This repository is the canonical reusable package. Keep private routing, host po credentials and machine-specific settings outside it. Use one local source with links for authoring and reviewed commit pins for distributed recovery snapshots. -Ordinary policy edits do not bump the release version. Track working changes by content -hash and Git state. Resolve pending related changes before selecting a release number. +With user authorization for autonomous version maintenance, select a patch, minor or +major bump when verified changes warrant it. Do not bump per conversation. Track working +changes by content hash and Git state; reconcile related changes and consumer pins. See [release policy](docs/releasing.md) and [unreleased changes](CHANGELOG.md). ```sh diff --git a/SKILL.md b/SKILL.md index 7716396..2bb3c21 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,8 +1,8 @@ --- name: commit-it -description: Track requested features, fixes and GitHub delivery, prepare authorized issue-linked commits, perform scoped PR reviews, and resolve an explicitly assigned PR set through verified integration and authorized ordered merges. +description: Track requested features, fixes and GitHub delivery, prepare authorized issue-linked commits, perform requested PR reviews and bounded repairs, and resolve an explicitly assigned PR set through verified integration and authorized ordered merges. metadata: - version: "3.0.0" + version: "4.0.0" --- # Commit It @@ -14,7 +14,10 @@ and reread its current source and relevant references before use. Follow applica repository instructions, including AGENTS.md and CLAUDE.md, without replacing them. For requested changes to the skill itself, update the canonical source through its configured local maintenance workflow. Preserve concurrent edits and do not create an -independent provider copy. Ordinary policy edits do not select a new release version. +independent provider copy. When the user authorizes autonomous version maintenance, choose a semantic version +bump when verified changes warrant one; do not bump merely because a conversation +changed. Keep metadata, release notes and consumer pins consistent. Tag and Release +publication remain separately authorized; see docs/releasing.md. ## Boundaries @@ -95,6 +98,15 @@ do not invent issue numbers, links or completion. Leave the useful handoff recor GitHub, including remaining work and links, rather than requiring the next agent or human to reconstruct it from chat. +Public OPS records use one concise heading and canonical Markdown fields/nested lists, +readable by humans and strictly parsed by tools. Do not publish JSON fences, raw payload +dumps or a second hidden JSON copy of the same metadata. Each datum has one authoritative +field; link detailed evidence instead of repeating it. Follow the +[record format and migration contract](references/worker-coordination.md#public-record-format). +Normal runtime reads reject legacy JSON; only an explicitly authorized, audited migration +may convert existing OPS-generated records in place. Preserve authors, IDs and semantic +values, exclude human/unmanaged content, and never rewrite Git commits or history. + ### Issue body format Use the following English structure for new actionable issues and substantive scope @@ -375,18 +387,27 @@ only for an eligible request or an explicit user-approved exception. - Ordinary review requires the implementing worker's durable request and takes place in a different conversation/task, strictly within that implementation scope. Record the - requesting worker, implementation task, reviewer task, PR, head/base and outcome. A - changed worker name in the same conversation does not satisfy task separation. Do not + requesting worker, implementation task, reviewer task, PR, head/base and outcome. The + requested separate reviewer directly repairs clear defects within that implementation + scope on the same PR by default, then verifies and publishes the final result. A changed + worker name in the same conversation does not satisfy task separation. Do not spawn a new task without the runtime's required user authority; record a pending request. - Self-review is prohibited for ordinary workers unless the user explicitly approves it for the named scope. An implementing worker cannot approve its own exception. This - exception does not claim independent authorship or human review. A successor taking - implementation ownership follows the same rule, including for inherited code. + exception does not claim independent authorship or human review. An implementation + successor follows the same rule. A requested separate reviewer who makes bounded repairs + is instead disclosed as reviewer-as-contributor under the repair protocol; it cannot + claim independent review of its own corrections. - Reuse implementation/test evidence and inspect only the requested diff and direct - contracts/callers. No proactive unrelated review or wider audit is implied. Verification + contracts/callers. Before repair, pause the original writer, declare files/scope and + expected head/base, remove `MERGE_READY`, and use Draft/`OCCUPIED`. Commit and ordinarily + push scoped fixes personally to the same PR; OPS records the contribution and final + head. Leave change requests/questions only for complex intent, material scope changes, + unresolved authority or ambiguity. No unrelated review or wider audit is implied. Verification and final diff/scope checks remain part of implementation; they are not a PR approval. - Authorized successful reviews start exactly with `Review: LGTM` for a separate reviewer, - `Self-review: LGTM` for explicitly user-approved self-review, or `Conflict resolution: LGTM` + including disclosed repair-review when it contributed corrections, `Self-review: LGTM` + for explicitly user-approved original-worker self-review, or `Conflict resolution: LGTM` for an explicitly granted resolver review under [conflict resolution](references/conflict-resolution.md). Preserve historical headings; use a concrete `Changes requested` outcome for blockers. - A valid review plus current passing checks and matching PR head/base permits adding diff --git a/docs/releasing.md b/docs/releasing.md index 507b359..fe9e6b3 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -8,7 +8,10 @@ Before a release, inspect current source, relevant installed variants, assigned and related PRs. Reconcile completed changes without taking over active work. Choose the next version only after scope and verification are known: compatible fixes use patch, additive behavior uses minor, and incompatible documented interfaces use major. -Follow [Semantic Versioning](https://semver.org/). +Follow [Semantic Versioning](https://semver.org/). When the user has authorized autonomous +version maintenance, make this decision and update metadata, release notes and verified +consumer pins without asking again. A version-only bump without a meaningful change is +unnecessary. This authorization does not itself publish a tag or GitHub Release. Commit subjects follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) and repository templates. Ordinary changes describe shipped behavior; a dedicated diff --git a/references/conflict-resolution.md b/references/conflict-resolution.md index dbe0cfb..3796b58 100644 --- a/references/conflict-resolution.md +++ b/references/conflict-resolution.md @@ -54,11 +54,12 @@ this mode. User and repository authority still govern every action. ## Durable sequence record -Keep one canonical, editable comment marked `commit-it:merge-sequence:v1` on a named -anchor PR. Store its comment ID or URL in the participating PR records. Continue -updating that same comment after the anchor PR merges: its body, old commit messages -and status mirrors do not replace the canonical sequence. Reconcile duplicate records, -missing write access or partially applied updates before advancing. +Keep one canonical, editable OPS v2 merge-sequence record on a named anchor PR. +Store its comment ID or URL in participating records. Continue updating that same record +after the anchor merges. Preserve exact schema keys and IDs; old JSON bodies, commit +messages and mirrors do not replace it. Reconcile duplicates, missing access or partial +writes before advancing. Runtime readers accept the current strict Markdown format; +legacy JSON is available only to the explicitly authorized audited migration. The existing `Work status` model remains `OCCUPIED` / `REVIEW_READY`. Record the separate `Merge status` here; do not substitute merge states for worker states or treat a PR's @@ -74,42 +75,35 @@ it does not replace Work status or authorize the sequence. | `MERGED` | Every planned step has a verified real merge receipt and resulting tree. | | `BLOCKED` | An unresolved authorization, ownership, check, state or receipt mismatch prevents the next step. Preserve completed work and the exact resume action. | -Illustrative record; resolve placeholders before publication. During preparation, -name unavailable evidence explicitly rather than inventing SHAs or passing results. +Use the configured OPS schema/renderer for the complete write payload. This is a +non-executable excerpt showing canonical lowercase fields and nested lists, not a full +copyable record. The renderer supplies the type-specific v2 marker, required repository, +authorization, anchor, PR snapshot and receipt fields. Never guess missing fields or SHA values. ```markdown - - -- Sequence: -- Revision: -- Role: conflict-resolver -- Resolver: -- Merge status: PREPARING -- Base: -- Order: -- Completed: -- Next: -- Readiness scope: next-step-only -- Ready PR: -- Pending verification: -- Authorization: -- Resume: -- Updated: - -| PR | Head | Expected base | Verified tree | Evidence | -| --- | --- | --- | --- | --- | -| | | | | | - - +### Merge sequence + +- schema_version: 2 +- id: +- role: conflict-resolver +- resolver: +- revision: 1 +- status: PREPARING +- order: + - + - +- prs: {} ``` -Every planned PR needs a head/base/tree/evidence row, with unavailable future evidence explicitly pending. `MERGE_SEQUENCE_READY` applies only to `Ready PR`, which must equal `Next`; after its receipt is saved, clear readiness and verify the next step against the new actual base. Start from the recorded full -base SHA. A later step may identify its planned predecessor and expected base tree -until that merge exists; bind its actual base SHA from the verified receipt before -execution. Never predict a future merge SHA. `Completed` records actual merge -results, not requested merges. `Next` must follow the remaining order and cannot -name an already completed PR. Include each dependency in the plan and verify that its -required tree is present before advancing. Keep detailed logs behind evidence links. +Every planned PR needs a snapshot with exact head, expected base/tree and evidence in +the schema's `prs` structure; missing future evidence is explicitly pending. Readiness +applies only to the next named step. After its receipt is saved, clear readiness and +verify the next step against the actual new base. Never predict a future merge SHA or +repeat a completed step. Preserve actual merge commit/tree receipts and dependency +order. Reference the original approval record and store its hash rather than copying +the full approval body into the sequence. Link detailed logs instead of repeating them. +Follow the [public record contract](worker-coordination.md#public-record-format): one +readable canonical payload, no JSON fence or hidden duplicate, no runtime legacy fallback. ## Commit and squash metadata @@ -155,16 +149,11 @@ Only the explicitly assigned resolver with an explicit scoped review/self-review may publish this exact first line for its verified integration scope. Without that grant, stop at `REVIEW_READY` and use the ordinary requested-review path: -```markdown -Conflict resolution: LGTM - -Resolver: · Role: conflict-resolver -Sequence: · Revision: -Reviewed head: · Base: · Verified tree: -Verification: . -Original authors: . -No blocking findings in the assigned integration scope. -``` +The first line remains exactly `Conflict resolution: LGTM`. The guarded OPS renderer +records the resolver, role, sequence/revision, original authors, head/base/tree and +verification once using the conflict-approval schema's exact keys and v2 marker. Link +that approval from the sequence instead of duplicating its body. Do not publish a +handwritten partial field set as a valid structured approval. This has the same evidentiary approval level as `Self-review: LGTM` and `Review: LGTM`: complete scope and passing required evidence for the recorded snapshot. It identifies diff --git a/references/pr-review.md b/references/pr-review.md index 0cd2d4b..fa5a580 100644 --- a/references/pr-review.md +++ b/references/pr-review.md @@ -3,7 +3,9 @@ Ordinary worker reviews are off by default. The implementing worker must request a review of its exact implementation scope, and a different conversation/task performs it. A delivery checkpoint, ready label or repository tracking opt-in is not a request. -Do not review unrelated work, start a monitor or invent new implementation scope. +The requested separate reviewer fixes clear defects within that scope on the same PR +by default, then verifies the final head and records readiness. Do not review unrelated +work, start a monitor or invent new implementation scope. ## Request and eligibility @@ -16,37 +18,56 @@ Do not review unrelated work, start a monitor or invent new implementation scope - The implementing worker may request review but may not waive separation or authorize its own self-review. Only explicit user approval for the named self-review permits that exception. Record the approval and mark the result as self-review, never independent - or human approval. An implementation successor has the same restriction. + or human approval. An implementation successor has the same restriction. A separate + requested reviewer may contribute bounded repairs under the protocol below; retain + original-request provenance and disclose its contribution instead of treating it as + the original worker's self-approved review. - A named commit-error or conflict resolver follows its explicit action/scope grant in [conflict resolution](conflict-resolution.md); a role name alone does not grant self-review. - Use the configured guarded review request/publication operation where available. Check current owner, task separation or explicit exception, scope and head/base before writing. A request is not permission to create a new task if the runtime requires user authorization. -## Review and publication - -1. Resolve the exact PR, base and head. Read the issue's acceptance checks when needed - to interpret the diff. Inspect changed behavior, direct callers/contracts and test - evidence; do not start a repository-wide audit by default. -2. Report reproducible correctness, contract, data, authorization or material performance - problems. Style preferences, optional refactors and hypothetical risks are nonblocking. -3. Distinguish executed checks from checks reported by the PR author. Pending CI is - pending verification, not proof of a product defect. Missing optional checks do not - justify rejection; a required or risk-critical missing check can block approval. -4. Immediately before publishing, confirm the head still matches the reviewed commit. - Review a changed delta before deciding. Pin the review to that commit. Reuse the prior - result for unchanged heads rather than creating repetitive comments. -5. Use `APPROVE` or `REQUEST_CHANGES` only when publication and that review action are - authorized and supported. If the signed-in account authored the PR, use `COMMENT` - with the same clear outcome; never claim it created a formal approval or change request. - A GitHub review can be submitted through `gh api .../pulls//reviews` using a - JSON input file with `commit_id`, `event`, and `body`. Preserve actual newlines. - -For corrections, identify the actual issue number, exact file and current diff line, -the concrete behavior to change, and the required recheck. Make the direction unambiguous. -Judge the implementation against the agreed outcome and code evidence, not against an -unpublished personal design. A further improvement is blocking only when necessary for -the authorized outcome; otherwise keep it explicitly optional. +## Review and repair + +1. Resolve the request, original implementation worker/task, assigned PR, expected + head/base, acceptance scope and existing checks. Inspect only the changed behavior and + direct contracts/callers; no unrelated audit is authorized. +2. Correct clear, reproducible implementation-scope defects directly. Before any edit, + declare the bounded repair scope/files and expected head/base in the OPS record, + ensure the original writer is paused, preserve its changes and use the same PR branch. + Set Draft/`OCCUPIED` and remove `MERGE_READY`. Re-read the claim and head/base immediately + before writing; actual concurrent writes or changed expectations stop that repair. +3. Make the smallest coherent fix and meaningful regression test. Personal identity + authors/commits/pushes the repair to the same PR; OPS records original author/request, + reviewer-as-contributor, claimed files, repair commits and resulting head. Preserve + authorship/history. Do not force-push, create a replacement PR, merge, edit issue scope + or acquire unrelated ownership merely because review was requested. +4. Reuse valid prior tests; rerun affected checks after corrections and verify the final + PR head/base and accepted implementation scope. Pending CI remains pending. Record + the actual repair range and state explicitly that the reviewer contributed corrections + and is not an independent reviewer of those corrections. This remains `Review: LGTM` + when the separate requested-review contract is satisfied; a new ID alone cannot create + that eligibility. Original implementation workers still need explicit user approval + for ordinary self-review. +5. For complex intent, material scope changes, unclear correction direction or missing + authority, leave only the affected unit blocked with a focused question/change request + and preserve completed fixes. Do not invent extra requirements or use optional style + preferences as blockers. A fixable, clear in-scope defect should not be returned merely + as instructions for the original worker to implement. +6. Publish the eligible result through the guarded OPS operation for the final head/base. + Use COMMENT when formal review approval is unsupported; a transport choice cannot + bypass eligibility. Return verified work to Ready/`REVIEW_READY` and add `MERGE_READY` + only after review, current checks and synchronized records pass. Release the temporary + repair claim without losing original ownership or contribution history. Neither ready + label grants automatic merge, deployment or main synchronization. + +For unresolved findings, identify the actual issue, exact file/current diff line, trigger, +observed versus expected result and the decision/recheck required. Keep the review within +the implementation's acceptance scope. Link detailed evidence, do not copy whole logs. +Public request, repair and review receipts follow the +[canonical Markdown contract](worker-coordination.md#public-record-format), with each field +once and no public JSON payload. Machine-readable data and human summaries must not diverge. Implementation ends with verified `REVIEW_READY` delivery and no approval heading. For an eligible review, reuse the implementation and tester's passing evidence; inspect @@ -58,16 +79,18 @@ Successful reviews use one exact first line, according to the actual assignment: | Approval heading | Applicable work | | --- | --- | | `Self-review: LGTM` | Own or inherited implementation only under explicit user-approved self-review for this scope. | -| `Review: LGTM` | Implementing-worker-requested review in a different task without implementation ownership. | +| `Review: LGTM` | Implementing-worker-requested review in a different task, including bounded same-PR repairs with reviewer-as-contributor disclosure. | | `Conflict resolution: LGTM` | Verified integration by the explicitly assigned `conflict-resolver` with review authority for the named PR set. | These are the only approval headings; never use bare `OK`, bare `LGTM`, or another variant. All require the same completed scope and verified evidence for the recorded head/base; none claims independent human approval or guarantees that every behavior was tested. Determine authorship from actual work, not the shared GitHub account. -A successor accepting implementation ownership finishes at `REVIEW_READY`, including -inherited work. It may self-review only with the user's explicit exception. Changing -worker/model/account does not make the work independent. Publish through the configured +A successor accepting the original implementation assignment finishes at `REVIEW_READY`, +including inherited work, and may self-review only with the user's explicit exception. +A separate requested reviewer making bounded repairs retains its review request and records +its contributor role; its corrections are not independently reviewed. Changing worker, +model or account alone does not make either case independent. Publish through the configured OPS identity where required and retain actual worker, task, request or exception evidence. Add the independent `MERGE_READY` label alongside `REVIEW_READY` only after a valid review, @@ -99,40 +122,38 @@ For data and provider changes, check identity preservation, selected inputs, bud units, actual versus estimated usage, and safe schema behavior when relevant. Mock checks do not establish live database behavior. -## Compact outcomes +## Compact public outcomes -Review of another worker's work: +Use the guarded OPS renderer for requests, repair claims and results. Preserve the +schema's exact raw keys and types rather than inventing another human-only field set. +The result's first line is the eligible exact review heading; include implementation +provenance, review task, final head/base, contribution, evidence and outcome once. For +repairs, disclose that the reviewer contributed and its corrections are not independently +reviewed. Ordinary self-review records the user's explicit scoped authorization. -```markdown -Review: LGTM - -Reviewed `` against ``: . -No blocking findings in this scope. Verification: . -``` - -Blocking finding (repeat only for independent defects): +This request excerpt illustrates the canonical representation; resolve actual values +and validate the full configured request schema before publication: ```markdown -Changes requested — - -[P1/P2] # · — -- Trigger and result: . -- Evidence: ; . -- Required change and recheck: . - -Reviewed head: ``. + +### Review requested + +- scope: +- worker: +- assignment: +- id: +- head: +- base: +- task: +- issues: [] ``` -Omit the issue field only when no issue is assigned; never invent a number. -Only for explicit user-approved self-review, use the same compact evidence format and -include the approval reference with this exact first line: - -```markdown -Self-review: LGTM - -Reviewed `` against ``: . -No blocking findings in this scope. Verification: . -``` +For unresolved blockers, use the configured change-request outcome with code, exact +issue/file/diff line, trigger, observed/expected behavior, evidence and required decision +or recheck. Omit an unassigned issue rather than inventing its number. Preserve the +reviewed head and do not copy an existing canonical record into a second JSON or prose +payload. Render `Verification blocked — VERIFICATION` for missing required evidence +instead of inventing a code defect. Historical review headings remain unchanged. Use P1 for serious failures of a normal flow and P2 for bounded failures that still need correction before the assigned scope is complete. Explain urgency with the impact; diff --git a/references/worker-coordination.md b/references/worker-coordination.md index 3f62aaa..240dfe5 100644 --- a/references/worker-coordination.md +++ b/references/worker-coordination.md @@ -41,10 +41,45 @@ below when taking over writers; the role does not silently grant coordinator rig Only separate named merge authority permits that sequence's merges. Ordinary workers remain PR-only, and no review heading grants merge or integration-checkout authority. -The resolver separately owns the canonical `commit-it:merge-sequence:v1` comment and +The resolver separately owns the canonical OPS v2 merge-sequence comment and its `Merge status`, even after its anchor PR merges. Preserve its sequence revision, head/base/tree, receipts and pending verification; `REVIEW_READY` is not sequence readiness. +## Public record format + +Public OPS-generated records have a short human heading followed by canonical Markdown +fields and nested lists. That readable content is also the machine source of truth: +no JSON fences, hidden JSON payloads or duplicate machine/narrative metadata. Keep +identifying markers when required, but store no second copy of record data inside them. +Preserve the exact raw schema keys and scalar types; do not invent capitalized aliases. +Use two-space indentation for nested bullet containers, explicit empty `[]`/`{}` and +quoted scalars only when needed to disambiguate their type. +Each value has one canonical field; summaries explain the outcome without repeating the +field inventory. Preserve exact worker/Assignment/request IDs, head/base/tree, timestamps, +authorization and evidence references. Link long logs rather than dumping them inline. + +Use the configured schema-aware parser/renderer. It must reject duplicate or missing +required fields, invalid nesting/types, ambiguous markers and unsupported structures; +never silently guess a value, drop fields or fall back to legacy JSON at runtime. Validate +and round-trip the complete record before writing, then re-read the published content. +API transport/configuration may still use JSON internally; this rule concerns public +record bodies and their normal readers, not GitHub's HTTP request encoding. + +The existing human-readable work-state:v1 contract stays supported. Former JSON record +types (review request, handoff, resolver action, merge sequence and conflict approval) +use their configured v2 markers and strict Markdown schema after migration. Do not +promise compatibility with every v1 marker or maintain a permanent dual-format reader. + +Legacy JSON conversion is a separate, explicitly authorized migration. Inventory the +entire authorized managed-repository registry and identify records by verified OPS author, +record marker/type and immutable record ID. Exclude human-authored or unmanaged content, +quoted examples and user prose outside the managed region. Preserve original authors, +record IDs/URLs, event timestamps and every semantic field; update the same record in place. +Keep an audit with before/after hashes, validation, skipped/blocked targets and results. +Re-read before writing, stop on drift, and retry only uncompleted targets idempotently. +Do not infer migration completion from a dry run or skip unreadable records as success. +No Git commit/message/history rewrite, deletion or automatic background migration is implied. + ## Durable work-state record Keep one marked work-state block at the top of the PR body. Before the first PR, use @@ -53,14 +88,17 @@ and the issue comment mirrors it; mirror to every assigned issue in a bundle. Ma and Assignment before updating. Preserve surrounding content and other assignments. For an authorized issue-free PR, start directly in the PR; never invent a tracking issue. -Keep the `v1` marker and accept legacy worker IDs. Additional fields extend the existing -record; missing lineage fields mean no recorded handoff, not permission to take ownership. +Keep the identifying `v1` marker and legacy worker IDs; neither requires a legacy JSON +reader. Existing canonical Markdown fields remain valid. Missing lineage fields mean no +recorded handoff, not permission to take ownership. For an approved first transfer of a legacy record, use prior handoff revision zero. Use actual values in this illustrative current record: ```markdown +### Work state + - Work status: OCCUPIED - Worker: codex-20260907T190000Z-a1b2c3d4 - Assignment: issue-123 @@ -121,8 +159,10 @@ A returning old worker must re-read current ownership before any mutation and st former assignment after transfer unless explicitly reassigned. Succession authorizes preservation, implementation and the already approved delivery scope; it does not grant merge, deployment, credential, paid-work or force-push authority. A successor modifying -inherited code cannot self-review without explicit user approval and must not present -that exception as independent `Review: LGTM`. +inherited implementation cannot self-review without explicit user approval. Requested +review repair is a distinct bounded role: retain the original implementation worker and +request provenance and disclose the reviewer-as-contributor rather than claiming +independent review of its corrections. ## OPS records, labels and transitions @@ -173,7 +213,11 @@ Missing or inconsistent records block a readiness claim. in a different conversation/task under [review eligibility](pr-review.md#request-and-eligibility). Record both task IDs, actual workers and head/base evidence. A worker cannot authorize its own self-review; only an explicit user-approved exception permits `Self-review: LGTM`. - Eligible separate reviews use `Review: LGTM`; an explicitly granted resolver may use + The separate reviewer repairs clear in-scope defects on the same PR by default. Follow + the [repair protocol](pr-review.md#review-and-repair) with paused original writer, + declared files, expected head/base and Draft/`OCCUPIED`. Record reviewer-as-contributor + without replacing original provenance. Eligible separate reviews use `Review: LGTM` + with correction disclosure; an explicitly granted resolver may use `Conflict resolution: LGTM` under its additional gates. 5. **Merge ready:** add `MERGE_READY` alongside `REVIEW_READY` only with a valid eligible review and current passing checks for the matching head/base. Re-read all records and @@ -186,8 +230,10 @@ Missing or inconsistent records block a readiness claim. those actions are explicitly granted; no global maintainer rights are implied. Re-read ownership and head immediately before mutations. Update only owned records; -ambiguous matches, changed owners and partial writes require reconciliation. A peer -reviewer reports findings without acquiring the branch. Draft prevents merging, not writes. +ambiguous matches, changed owners and partial writes require reconciliation. A requested +reviewer may hold bounded repair write ownership while the original writer pauses; +this does not transfer unrelated implementation assignments. Draft prevents merging, +not writes. Preserve requested scope and provenance when recording the final repair head. ## Conversation titles diff --git a/tests/test_package.py b/tests/test_package.py index 299bd75..0f02c36 100644 --- a/tests/test_package.py +++ b/tests/test_package.py @@ -64,22 +64,39 @@ def test_resolver_protocol_is_reachable_and_review_headings_are_complete(self): row = next(line for line in review.splitlines() if line.startswith('| `Conflict resolution: LGTM`')) self.assertIn('explicitly assigned `conflict-resolver`', row) - def test_sequence_record_carries_snapshot_receipts_and_separate_merge_states(self): + def test_sequence_excerpt_has_canonical_fields_and_separate_merge_states(self): + """Keep the illustrative schema lowercase and avoid publishing a duplicate payload.""" text, blocks = self.conflict_blocks() - records = [body for kind, body in blocks if body.startswith('')] - self.assertEqual(len(records), 1) - record = records[0] - fields = re.findall(r'^- ([^:]+): (.+)$', record, re.MULTILINE) - self.assertEqual(len(fields), len(dict(fields)), 'duplicate sequence record field') - self.assertEqual(set(dict(fields)), {'Sequence', 'Revision', 'Role', 'Resolver', - 'Merge status', 'Base', 'Order', 'Completed', 'Next', 'Readiness scope', 'Ready PR', 'Pending verification', 'Authorization', 'Resume', 'Updated'}) - self.assertEqual(dict(fields)['Role'], 'conflict-resolver') - self.assertNotIn('Work status', dict(fields)) - self.assertIn('| PR | Head | Expected base | Verified tree | Evidence |', record) - self.assertIn('', record) + excerpts = [body for kind, body in blocks if body.startswith('### Merge sequence\n')] + self.assertEqual(len(excerpts), 1) + record = excerpts[0] + pairs = re.findall(r'^- ([^:]+):([^\n]*)$', record, re.MULTILINE) + fields = {name: value.strip() for name, value in pairs} + self.assertEqual(len(pairs), len(fields), 'duplicate canonical field') + self.assertEqual(set(fields), {'schema_version', 'id', 'role', 'resolver', + 'revision', 'status', 'order', 'prs'}) + self.assertEqual(fields['schema_version'], '2') + self.assertEqual(fields['role'], 'conflict-resolver') + self.assertEqual(fields['prs'], '{}') + self.assertEqual(len(re.findall(r'^ - ', record, re.MULTILINE)), 2) + self.assertNotIn('```json', record) + self.assertNotIn('Work status', fields) states = set(re.findall(r'^\| `([A-Z_]+)` \|', text, re.MULTILINE)) self.assertEqual(states, {'PREPARING', 'MERGE_SEQUENCE_READY', 'MERGING', 'MERGED', 'BLOCKED'}) - self.assertIn(dict(fields)['Merge status'], states) + self.assertIn(fields['status'], states) + + def test_review_request_excerpt_has_one_public_payload(self): + """Preserve schema keys and a current record marker without a hidden JSON shadow.""" + text = (ROOT / 'references/pr-review.md').read_text() + excerpts = re.findall(r'```markdown\n(', excerpts[0]) + self.assertEqual(excerpts[0].count('