diff --git a/CHANGELOG.md b/CHANGELOG.md index 5982e50..a56658b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,19 @@ ## Unreleased +## 3.0.0 - 2026-09-07 + +- Replace predecessor-acknowledged ownership transfer with explicit user-approved succession, + preserved checkpoints and project assignment lineage independent of disposable chats. +- Allocate collision-checked worker IDs while retaining existing IDs and v1 work-state records; + record successor/model verification without implying independent review or merge authority. +- Define OPS-attributed ownership, commit/PR receipts and synchronized managed labels while + retaining personal development authorship and existing repository permissions. +- Name conversations through available official client tools, with verified results and + a capability-based fallback that never edits internal conversation storage. +- This major version changes the coordination and handoff contract. Existing records remain + readable; label provisioning, tags, releases and account activation are not implicit. + ## 2.9.0 - 2026-09-07 - Add explicitly assigned conflict resolution, a durable merge sequence, exact review diff --git a/README.md b/README.md index ebfed14..df01a52 100644 --- a/README.md +++ b/README.md @@ -114,6 +114,23 @@ 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 + +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. + +The coordination reference defines collision-checked IDs, assignment lineage, OPS +ownership/commit receipts, and `DEV`/`OPS` plus `OCCUPIED`/`REVIEW_READY` label synchronization. +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. + +Conversation names follow ` | | `. +Use supported official tools and verify the new title; otherwise provide the suggested +title without blocking development. Chat titles and IDs are optional lookup aids. + For an explicitly assigned resolver of a named PR set, read [conflict resolution](references/conflict-resolution.md). Ordinary worker authority is unchanged. diff --git a/SKILL.md b/SKILL.md index 5a9ce32..94544f5 100644 --- a/SKILL.md +++ b/SKILL.md @@ -2,7 +2,7 @@ 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. metadata: - version: "2.9.0" + version: "3.0.0" --- # Commit It @@ -51,6 +51,11 @@ permission for scoped issue/PR tracking. Without that permission or a direct req prepare the proposed external update and obtain the missing authorization. Tracking permission alone never implies commit, push, PR publication, merge or branch deletion. An explicitly approved delivery sequence should proceed without repeated approval. +Where operational writes use a configured OPS account or guarded command, route +claims, labels, progress, commit receipts and review comments through that interface. +The `gh` examples below describe operations, not permission to bypass account routing +or worker restrictions on issue-body edits. Development commits and PR creation keep +the repository's personal author identity, including both commit author and committer. 1. **Start:** use `gh issue list/view` and `gh pr list/view` for the current task only. Reuse the related issue/PR. When creation is authorized and no match exists, create @@ -175,16 +180,30 @@ work; intake alone does not start implementation or create a background service. ### Coordinator and worker ownership -When the user adopts a coordinator with named workers, read -[worker coordination](references/worker-coordination.md). Use the user-assigned IDs, -Draft/Ready PR stages, an authoritative PR work-state block and issue status mirrors. -Separate ownership from verification and authenticate messages with the intended -account/App; a commit email does not set the issue/PR author. This opt-in mode does -not expand repository permissions or create accounts, labels, Projects or background jobs. - -When a repository separates development authorship from operational records, -follow its repository or global identity policy. Keep personal account mappings, -local paths, credentials and deployment configuration outside this reusable skill. +When the user assigns workers or requests succession, read +[worker coordination](references/worker-coordination.md). Workers are replaceable +execution owners, not permanent conversations. Preserve continuity through project +assignments, issues, PRs, commits and reproducible verification. Later models improve +inherited work through tests; a model change alone is neither new evidence nor a reason +to discard valid work. Archived or deleted chats must not prevent approved succession. + +Preserve supplied worker IDs. Otherwise allocate `--<8 hex digits>` +and check project records for collisions. Keep assignment lineage and handoff revisions; +explicit user approval is sufficient to transfer named work without predecessor acknowledgement. +Preserve checkpoints, reconcile current ownership and stop only actual conflicting writers. +This does not expand merge, deployment, credential or published-history authority. + +Use the reference's Draft/Ready stages, authoritative work-state record, issue mirrors, +OPS commit/PR receipts and managed `DEV`/`OPS`, `OCCUPIED`/`REVIEW_READY` labels. Provision +missing labels only within setup authorization. Separate personal development commits +and PR creation from configured OPS ownership/status/review writes; authenticate each +operation independently. Keep personal mappings, host paths and credentials outside this +package. No account, App, Project or background job creation is implied. + +At assignment or handoff, use available official tools to name the current conversation +` | | `. Verify the result; capability +absence only requires a suggested title, not blocked implementation. See the reference +for platform-specific paths and fallback rules. ### Explicit conflict-resolution mode @@ -353,7 +372,8 @@ implementation, issue management, merging, or unrelated cleanup. - Default to a brief review of the exact diff, direct contracts/callers, and relevant verification. Expand only for a concrete risk or finding. Reuse valid test evidence. - When assigned to review PRs made by others, identify work this agent actually created; - account authorship alone cannot distinguish workers sharing one GitHub account. + account authorship alone cannot distinguish workers sharing one GitHub account. A successor + who modifies inherited code uses `Self-review: LGTM`; changing workers is not independent review. - If review publication is authorized and the scope has no blockers, the first line must be exactly `Self-review: LGTM` for work this agent authored or `Review: LGTM` for another worker's work. Only an explicitly assigned conflict resolver may instead use @@ -365,7 +385,8 @@ implementation, issue management, merging, or unrelated cleanup. - A shared author account cannot formally approve or request changes on its own PR. Publish the result as a comment review in that case and describe its actual state. - For an ordinary worker's own completed PRs, reuse the implementation and tester's passing - evidence, briefly review the final diff, and post `Self-review: LGTM` immediately if unblocked. + evidence, briefly review the final diff, and post `Self-review: LGTM` after required + record, label and Draft/Ready synchronization succeeds and no blocker remains. Do not add another audit or repeat valid tests. Recheck only a relevant change or failure. Do not present self-review as independent or human approval. Unfinished work and pending required checks must not receive any approval heading. diff --git a/references/conflict-resolution.md b/references/conflict-resolution.md index 2894f06..76439b3 100644 --- a/references/conflict-resolution.md +++ b/references/conflict-resolution.md @@ -8,8 +8,10 @@ this mode. User and repository authority still govern every action. - Record role `conflict-resolver` with the resolver's actual worker ID, named input PRs, base branch and allowed actions. A role is not a new identity. Preserve source - authorship, earlier worker records, unrelated changes and active worktrees. Confirm - affected writers have stopped before editing their branches; do not take over an + authorship, earlier worker records, unrelated changes and active worktrees. Follow + [user-approved succession](worker-coordination.md#user-approved-succession) for a + transfer: explicit user approval suffices without predecessor acknowledgement. + Preserve checkpoints and pause actual conflicting writes; do not take over an unassigned PR or infer authority from a shared account. - Resolve the named PRs' accepted requirements, defects and cross-PR interactions. Ordinary workers retain their existing PR-only boundaries. Resolver assignment diff --git a/references/pr-review.md b/references/pr-review.md index 1292fb1..050246a 100644 --- a/references/pr-review.md +++ b/references/pr-review.md @@ -30,8 +30,8 @@ unpublished personal design. A further improvement is blocking only when necessa the authorized outcome; otherwise keep it explicitly optional. For an ordinary worker's completed PR, reuse the implementation and tester's passing evidence. -Briefly inspect the final diff and immediately post `Self-review: LGTM` if it has no -blocker; do not add a second audit or rerun valid tests. Recheck only a relevant new +After required record, label and Draft/Ready synchronization succeeds, briefly inspect +the final diff and post `Self-review: LGTM` if it has no blocker; do not add a second audit or rerun valid tests. Recheck only a relevant new change or failure and name the reviewed head. An unfinished scope, known blocker or pending required check must not receive any approval heading. @@ -47,6 +47,12 @@ These are the only approval headings; never use bare `OK`, bare `LGTM`, or anoth 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 who edits inherited code uses `Self-review: LGTM`, preserves earlier +worker attribution and links the reused verification. A new worker/model/account is +not independent review by itself. A separate review-only assignment may use `Review: LGTM` only +without taking implementation ownership or implementing the reviewed work. A successor +accepting implementation ownership reports completion as self-review, including inherited work. Publish through the configured OPS review +identity when required; the record still identifies the actual reviewing worker. A review never grants permission to merge or deploy. A conflict resolver preserves original authorship and follows the additional tree/sequence requirements in [conflict resolution](conflict-resolution.md); ordinary reviews do not activate it. diff --git a/references/worker-coordination.md b/references/worker-coordination.md index fc031c4..57d6a04 100644 --- a/references/worker-coordination.md +++ b/references/worker-coordination.md @@ -1,123 +1,204 @@ # Coordinator and worker ownership -Use this mode when the user explicitly adopts a coordinator plus named execution -workers. Ordinary tasks do not require this protocol. Repository role boundaries -still apply; prepare a record rather than publish it if status writes are unauthorized. - -## Roles and identity - -- The coordinator handles issue intake/scope, assigns work and normally performs - authorized merges or integration-checkout synchronization. Fetch and fast-forward - a stable main when possible; do not rewrite main just because a request says rebase. - Published-history rewrites and foreign checkout changes require explicit authority. -- Workers implement their approved assignment in isolated persistent worktrees, - verify it, publish/update its PR and provide the review result. The user assigns - stable IDs such as `worker-1`; retain the same ID across the assignment. Ask for a - missing ID before publishing ownership. Never allocate another worker's identity. -- An assignment has one writer. Multiple scopes on one issue need an explicit, - disjoint coordinator allocation. A bundle of issues shares one assignment ID. - Shared account authorship, issue assignees and PR labels do not identify a worker. - The user determines these workers and their count; this mode does not automatically - spawn tasks or give subagents separate worker identities. +Use this mode for explicitly assigned workers or user-approved succession. Ordinary +unassigned tasks do not require it. Repository role boundaries still apply; prepare +records rather than publish them when status writes are unauthorized. + +## Project continuity and identity + +Workers are replaceable execution owners, not permanent conversations. Preserve project +continuity in assignments, issues, PRs, commits and reproducible tests. A later model +may inherit and improve work incrementally; model novelty does not prove improvement +or invalidate existing checks. Chats may be archived or deleted. Their identifiers and +titles are optional navigation aids, never the only location of checkpoints or approval. + +- The coordinator handles authorized intake, scope and allocation. Ordinary workers + implement an approved assignment in persistent isolated worktrees, verify it and + deliver its PR and review. They do not inherit coordinator merge or checkout rights. +- Preserve user-supplied IDs, including legacy names such as `worker-1`. If none is + supplied, allocate `--<8 lowercase hex digits>`, using UTC + and a random suffix; for example `codex-20260907T190000Z-a1b2c3d4`. Verify against + existing project worker records before registration and regenerate on collision. + Use the actual client family such as `codex` or `claude`, not an inferred model. +- A new independent execution owner gets a new ID. Resume, context compaction and + renaming the same execution retain its ID. Record verified model/client information + separately when useful; an in-place model switch records its verification interval. + Never infer a model from a user-visible title or claim unsupported runtime metadata. +- Keep the existing Assignment across succession. Link every original Assignment when + combining previously separate scopes; do not overwrite lineage with a new bundle ID. + One assignment has one writer. Multiple scopes on one issue require disjoint explicit + allocation. An account, label or GitHub assignee is not a worker identity or lock. +- This protocol does not launch agents or increase staffing. Honor the authorized + capacity and keep shared contracts and Git mutations under one owner. ### Explicit resolver assignment -The user may assign role `conflict-resolver` for a named PR set under -[conflict resolution](conflict-resolution.md). Preserve the actual worker ID, source -authors and earlier worker history; the role does not create a new identity or confer -coordinator authority. Confirm stopped writers and the authorized assignment before -branch edits. An explicitly authorized resolver may merge that set, but ordinary -workers remain PR-only and a review heading never grants merge or checkout-sync rights. +An explicitly assigned `conflict-resolver` follows +[conflict resolution](conflict-resolution.md) for only its named PR set. Retain its +actual worker ID, prior workers and original authors. Apply the succession safeguards +below when taking over writers; the role does not silently grant coordinator rights. +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. -Keep the existing `Work status` transitions below. The resolver separately owns the -canonical `commit-it:merge-sequence:v1` comment and its `Merge status`, including after -the anchor PR merges. Update only records within the explicit assignment and preserve -original authorship/history. Sequence readiness requires verified head/base/tree and -check evidence; it is not interchangeable with one PR's `REVIEW_READY` state. +The resolver separately owns the canonical `commit-it:merge-sequence:v1` 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. -## Current record +## Durable work-state record -Keep one marked work-state block at the top of the PR body. Before the first PR, -keep the claim in one marked issue comment for the assignment. After PR creation, -the PR block is authoritative and that issue comment is its mirror. For a bundle, -mirror it to every assigned issue. Match both marker and assignment before updating; -never replace the entire issue body or another assignment's comment. For an authorized -issue-free PR, start its record directly in the PR; do not invent a tracking issue. +Keep one marked work-state block at the top of the PR body. Before the first PR, use +one marked issue comment for each Assignment. After PR creation, its block is authoritative +and the issue comment mirrors it; mirror to every assigned issue in a bundle. Match marker +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. -Illustrative record; use actual IDs, links, scope, timestamps and evidence: +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. +For an approved first transfer of a legacy record, use prior handoff revision zero. +Use actual values in this illustrative current record: ```markdown - Work status: OCCUPIED -- Worker: worker-1 +- Worker: codex-20260907T190000Z-a1b2c3d4 - Assignment: issue-123 - Scope: - Issues: #123 - PR: #456 - Verification: blocked: +- Previous worker: worker-1 +- Handoff revision: 1 +- Handoff: +- Head: - Updated: ``` -The issue therefore shows who occupies the work and which PR carries it. Use -`PR: pending` until an actual PR exists. Add the branch/task reference when it is -known and useful. Put detailed test evidence in the PR rather than copying logs -into every mirror. Other ownership comments outside the marked work-state record are -historical evidence, not the current assignment or an invitation to take over. - -## Transitions - -1. **Assign:** the coordinator authorizes the worker ID and exact scope. The - authorized record writer checks existing claims and records `OCCUPIED` before - implementation. If an active owner conflicts, stop that scope for coordination. - Labels are not an atomic claim mechanism; workers do not race to claim a backlog. -2. **Open:** at the first meaningful pushed change, create a Draft PR with the record - and linked issues, then fill its actual PR link into the issue mirrors. Do not - manufacture empty commits merely to create a reservation PR. -3. **Work:** keep `OCCUPIED` while running, waiting or blocked. Track verification - separately as `not run`, `running`, `passed` or `blocked: `; a failed - required check cannot be reported as passed. Blocking does not release the owner. -4. **Ready:** after scope and required checks are complete and writers have stopped, - set `REVIEW_READY`, update the issue mirrors and mark the PR Ready for review. - Include the reviewed head and reusable evidence in `Self-review: LGTM`; an explicitly - assigned resolver uses `Conflict resolution: LGTM` only after the additional - integration checks. Readiness alone never permits edits by a different worker. -5. **Revise:** before new implementation, return to Draft and `OCCUPIED`, update - mirrors, then edit. An existing review applies only to its recorded head. Ordinary - peer reviews use `Review: LGTM` for another worker's completed work or a concrete - change request; the explicitly assigned resolver follows its integration heading. -6. **Handoff/finish:** only the coordinator explicitly reassigns after the old owner - stops writers and preserves its checkpoint/backups. Silence, stale records, - absent mirrors and blocked verification never imply release. After an authorized - merge, the coordinator reconciles the linked issue record with the real outcome; - partial delivery leaves the remaining scope open. - -Re-read the owner and current head immediately before mutations. Update only the -owned record and preserve surrounding PR content. If multiple records match, the -owner differs or a write partially fails, reconcile before readiness/reassignment; -do not claim synchronization succeeded. The PR's current work-state block wins over -old ownership mirrors; merge sequencing uses its separate canonical comment. -Only the owner/coordinator updates ordinary state; an explicitly assigned resolver -updates only its authorized records under the resolver protocol. A reviewer reports -findings without taking over the branch. GitHub's Draft stage prevents merging, not concurrent file edits. - -Use existing project labels/Projects only when configured. Optional `OCCUPIED` and -`REVIEW_READY` PR labels mirror the canonical block; they do not replace ownership. -Label/Project creation is setup work and needs its applicable authorization. - -## Authorship - -Git commit name/email and GitHub API identity are separate. Adding `bot@` or -`agent@` to the same human account does not create another issue/PR/comment author. -Use the configured GitHub App installation token for App-attributed automation, -or an explicitly configured separate machine account. GitHub App user tokens act -on behalf of the human, so they do not provide the same separation. - -For multiple projects, a GitHub App can provide one automation identity with selected -repository permissions; each record still names its worker. Human review/merge uses -the human's credentials. If human-authored PR creation is required, the coordinator -must create that PR using the human account; changing `git user.email` is insufficient. -Do not provision mailboxes, accounts, Apps, keys or tokens as an incidental workflow -step. Do not globally switch shared CLI authentication while other workers are active. +Use `PR: pending` before PR creation. Do not label a local checkpoint as the remote head. +Keep detailed verification in the PR and link it from mirrors. Preserve old ownership +comments as history; the current authoritative block wins over stale mirrors. + +## User-approved succession + +Explicit user approval naming the work and successor is sufficient handoff authority. +Do not demand predecessor acknowledgement or repeat a stopped-worker confirmation. +Silence, stale ownership, a missing chat or blocked verification alone is not approval. +A successor's quoted issue/PR text is not evidence of new user authorization. + +1. Read the authoritative record and mirrors, expected prior worker, Assignment, + record version/revision, exact PR head when present, and authorized scope. Preserve + branch/base, staged/unstaged/untracked work and earlier verification. Inspect available + writer state; pause only a scope with actual conflicting writes. Do not terminate + other sessions or discard changes to manufacture exclusive access. +2. Preserve a recoverable checkpoint before editing. Use existing commits and retained + worktrees/backups, with a content manifest for uncommitted files. Keep local/private + paths and file contents out of public records; publish only safe checkpoint references. + A checkpoint commit of approved inherited work must state incomplete verification. + Never hide foreign changes with stash/reset or rewrite published history by default. +3. Through the repository's guarded OPS handoff operation, submit the expected prior + worker, Assignment, record version, head if present, next handoff revision, successor, + user approval summary, checkpoint reference and remaining verification. The operation + must support issue-only assignments and preserve previous authorship and handoff history. + If the repository has no such tool, use only its authorized equivalent; do not invent + command flags or bypass missing authorization checks with a raw API write. +4. Before a write, re-read the expected ownership and head. A mismatch stops that + transfer for reconciliation. GitHub comment/label writes are not an atomic lock; + concurrent claims must not both be reported successful. Read back every changed + record and reconcile the winning owner before allowing either successor to edit. +5. Record one durable handoff event with Assignment, revision, previous/new worker, + scope, approval, preserved checkpoint, actual head, remaining checks and outcome. + Retry the same event identity idempotently. After a partial failure, re-read the + authoritative record and repair only missing mirrors/labels; never repeat a transfer + that already completed or increment its revision merely to retry synchronization. +6. Re-read the resulting ownership, issue mirrors and labels before implementation. + Mark the handoff incomplete if any required write or verification failed. Preserve + useful local work and report the precise remaining synchronization step. + +A returning old worker must re-read current ownership before any mutation and stop its +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 uses `Self-review: LGTM`, not independent `Review: LGTM`. + +## OPS records, labels and transitions + +Resolve the configured personal development and OPS record identities independently. +Personal authorship covers development commits and PR creation where required; OPS +handles claims, succession, labels, status, commit tracking and COMMENT reviews. A commit +email does not select an API author. Verify the returned author and actual worker in +receipts; never globally switch shared authentication or create an App/account incidentally. +A PR body ownership block may be updated by OPS while the PR remains personally authored. + +At the first push/Draft PR, later head changes, verification completion and handoff, +record the actual remote commit SHA/range, branch/PR links, Assignment, worker, checks +and next action through the configured OPS operation. Reuse the existing receipt at an +unchanged checkpoint. Local uncommitted work is not a published commit. Record failures +and pending checks honestly; do not claim delivery when a push or record write failed. + +Use the managed labels below in this adopted workflow. Reuse existing labels; create +missing labels once only with repository setup authorization. Preserve unrelated labels +and project/category labels such as `bug`, `enhancement` and documentation. Do not create +per-worker labels or a Project board. Labels summarize records and never lock ownership. + +| Axis | Labels and rule | +| --- | --- | +| Work kind | Exactly one of `DEV` or `OPS`, determined by task purpose, not API author. Product implementation is `DEV`; operational tooling and workflow policy are `OPS`. | +| Work status | Exactly one of `OCCUPIED` or `REVIEW_READY` on active managed issues/PRs. | +| Blocked | Keep `OCCUPIED` and put the concrete blocker and next action in verification. | + +For multiple assignments on one issue, derive the issue state from all current records: +any unfinished, running or blocked assignment makes it `OCCUPIED`; only all completed, +verified assignments make it `REVIEW_READY`. Apply `OPS` only to wholly operational scope; +use `DEV` when the combined issue includes product implementation. Preserve individual +assignment kinds in records. Missing or inconsistent records block a readiness claim. + +1. **Assign/open:** check claims and record `OCCUPIED` before implementation. Create a + Draft PR at the first meaningful pushed change and mirror its actual link to issues. + No empty reservation commit is needed. Approved succession uses the procedure above. +2. **Work/revise:** keep Draft/`OCCUPIED` during implementation, waiting, failures or + required checks. Before revising a ready PR, return its state and mirrors to occupied. + Verification is `not run`, `running`, `passed`, `failed` or `blocked: `. +3. **Ready:** only after scope, checks and writer work finish, synchronize authoritative + state, issue mirrors, labels and Draft/Ready status. Read back all required targets; + interrupted synchronization remains incomplete and must be reconciled before claiming + readiness. A changed head invalidates old review evidence. Post `Self-review: LGTM` + for own completed work or `Review: LGTM` for peer review without implementation. + Only the explicit resolver may use `Conflict resolution: LGTM` under its extra gates. +4. **Finish:** only after an authorized maintainer merge, reconcile actual merge/issue + receipts under that authority. A worker never infers merged status from readiness. + Partial delivery keeps remaining scope open; no label grants permission to close it. + +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. + +## Conversation titles + +At assignment or succession, name the current conversation +` | | ` when a supported tool is available. +Put the useful outcome first. For generated IDs use `-<8 hex digits>` as the short +ID; preserve an existing readable legacy ID, or shorten its timestamp while retaining +an unambiguous mapping to the full worker ID in the record. Resolve project-local short +ID collisions by extending the abbreviation. The title never replaces the full worker ID. + +Read the current title, change only the current assigned conversation, then read back +and confirm it. Identical titles need no mutation. Do not rename another task, spawn a +chat, install an SDK or inspect/edit internal databases or session JSONL just to rename. +Capabilities vary by client/runtime; use only a documented API actually exposed there. + +| Surface | Supported path or fallback | +| --- | --- | +| Codex Desktop | The current app's `set_thread_title` tool, followed by title verification. | +| Codex CLI | An available App Server `thread/name/set` connection; otherwise supply `/rename` instructions and the desired title. | +| Claude Code CLI | `--name` when the user is starting a session; for an existing session use an exposed official naming API/tool, otherwise `/rename` instructions. | +| Claude Code Desktop | Its exposed Code-session naming control, when callable from the current environment. | +| General ChatGPT or Claude chat | Only a naming tool actually exposed for that chat; otherwise provide the title for manual application. Code-session APIs do not imply general-chat support. | + +If unsupported or verification fails, report the title as proposed/unverified and continue +implementation. Do not claim automatic renaming based solely on documentation. Official +references: [Codex App Server](https://learn.chatgpt.com/docs/app-server), +[Codex CLI commands](https://learn.chatgpt.com/docs/developer-commands?surface=cli), +[Claude Code sessions](https://code.claude.com/docs/en/sessions), and +[Claude Code Desktop](https://code.claude.com/docs/en/desktop#work-across-sessions). diff --git a/tests/test_package.py b/tests/test_package.py index c6ade71..a9971bc 100644 --- a/tests/test_package.py +++ b/tests/test_package.py @@ -21,6 +21,24 @@ def test_skill_has_metadata_and_local_references(self): if '://' not in link and not link.startswith('#'): self.assertTrue((file.parent / link.split('#')[0]).exists(), link) + def test_work_record_retains_legacy_marker_and_additive_lineage_fields(self): + """Validate the copyable record without requiring clients to migrate v1 data.""" + text = (ROOT / 'references/worker-coordination.md').read_text() + records = re.findall(r'```markdown\n([\s\S]*?)```', text) + self.assertEqual(len(records), 1) + record = records[0] + pairs = re.findall(r'^- ([^:]+): (.+)$', record, re.MULTILINE) + fields = dict(pairs) + self.assertEqual(len(pairs), len(fields), 'duplicate work-state field') + self.assertTrue({'Work status', 'Worker', 'Assignment', 'Scope', 'Issues', + 'PR', 'Verification', 'Updated'} <= fields.keys()) + self.assertEqual(fields['Previous worker'], 'worker-1') + self.assertEqual(int(fields['Handoff revision']), 1) + self.assertRegex(fields['Worker'], r'^codex-\d{8}T\d{6}Z-[0-9a-f]{8}$') + self.assertIn('', record) + self.assertNotEqual(fields['Worker'], fields['Previous worker']) + self.assertEqual(fields['Work status'], 'OCCUPIED') + def test_package_excludes_private_operations_configuration(self): for file in [ROOT / 'SKILL.md', *ROOT.joinpath('references').glob('*.md'), ROOT / 'agents/openai.yaml']: text = file.read_text()