Add native MCP bootstrap for allocated author issue worktrees #850

New Issue

2026-07-23T14:37:59-05:00

jcwalker3 commented

2026-07-23 14:37:59 -05:00

Problem statement

An unattended controller-routed author cycle cannot start a newly selected issue using only sanctioned Gitea-Tools MCP operations.

For live Issue #639, the controller preview correctly routed author / implement to gitea-author. The author namespace passed identity, role, capability, namespace-health, workflow-skill, and master-parity checks, but it had no issue worktree yet. That is task-bound state before allocation, not itself an error. The required next transition is:

selected issue → assignment/lease → issue lock → validated branch/worktree under branches/

The live author tool registry exposes allocation/lease operations and gitea_lock_issue, but no native MCP operation that creates and binds the registered issue worktree needed by gitea_lock_issue. The runtime's only recovery guidance is scripts/worktree-start or git worktree add, which MCP-only scheduled workers are prohibited from using.

Affected runtime

Repository: Scaled-Tech-Consulting/Gitea-Tools
Remote: prgs
Namespace/profile/identity/role: gitea-author / prgs-author / jcwalker3 / author
Controller selection: Issue #639, action implement, candidate fingerprint 82f19c3936eda98f9cf7c1923fc16a07c53749aad8b01dc007c9d4853fd42db7
Server and live master SHA: 1c455b6ec0f9cb761fe6248de68c17e061fb5ecd
Master parity: in parity; restart not required; mutation-safe
Canonical workflow: work-issue.md SHA-256 14e515cdaa6a859c756c51091b71b4ed98e72b72e85ffa349b64bcff83b4c6d91
Author namespace health: callable; gitea_lock_issue registered

Expected behavior

After atomic controller allocation, a role-correct author namespace must expose one sanctioned MCP transition that creates or recovers the issue branch and registered worktree under branches/, binds it to the assignment/lease, and makes it eligible for the canonical issue lock without touching the stable control checkout.

Actual behavior

No native MCP branch/worktree bootstrap operation is registered. The canonical tool inventory contains worktree audit/snapshot tools but no create/bind operation. gitea_get_runtime_context reports the stable control checkout and instructs the worker to use a shell helper or raw Git. In an MCP-only scheduled run, applying the allocation would therefore knowingly create a lease that cannot advance to the required issue lock/worktree state.

No allocation was applied for #639, and no branch, worktree, lock, file, commit, push, or PR mutation was produced.

Recovery attempts and authoritative evidence

Verified gitea-workflow mounts and clean instruction boundary.
Corrected the initial default-remote guide probe to authoritative remote prgs.
Verified controller and author identities and profiles.
Verified controller/author namespace health and current master parity.
Re-read #639 and dependencies: hard dependency #634 is closed; soft dependency #638 has an open PR.
gitea_assess_work_issue_duplicate(issue_number=639, phase=pre_claim): no linked open PR, conflicting branch, or active claim.
Inspected the complete live author registry and docs/mcp-tool-inventory.md: only worktree audit/snapshot/cleanup assessment tools exist; no native create/bind transition exists.
Did not use shell Git, direct API, browser, credentials, filesystem worktree manipulation, or MCP internals.

Assignment and lease impact

Issue #639: no assignment or lease created.
No issue lock exists for #639.
An unrelated stale-dead-process lease for #637 remains active, but #637 already has PR #849 and a protected clean open-PR worktree; it was not reclaimed or released because foreign ownership could not be safely authorized.

Scheduled-run impact

Every fresh MCP-only scheduled author cycle that selects an issue without an existing registered worktree must stop before allocation or create an unadvanceable lease. The live recovery text directs workers toward operations that the automation security boundary forbids.

Duplicate search

Searched all 469 open and closed issue titles and inspected the closest bodies.

#275: allows claim/lock from an already-created branches worktree; it does not create one.
#749 and #757: provide the pure-remote create_issue bootstrap; they do not bootstrap post-issue author worktrees.
#713: requires registered-worktree proof and rejects fake directories; it does not supply native creation/binding.
#39: covers shell worktree helpers, not MCP-only scheduled execution.
#618: worktree-binding consistency, not a native post-allocation bootstrap transition.
#812/#816: publication recovery for existing worktrees/commits, not first worktree creation.

No issue fully covers this root cause.

Acceptance criteria

A native author MCP operation atomically attempts assigned issue → issue branch → registered branches/ worktree → bound workflow lease/assignment → issue-lock-ready state.
The operation derives repository, stable branch, issue number, branch name, worktree path, identity, role, lease, and expected base SHA from authoritative state; callers cannot forge ownership.
Successful creation is recognized by the branches-only and anti-stomp guards and is base-equivalent to current live master.
Failure atomically rolls back every partial mutation: Git ref/branch, worktree directory, .git/worktrees metadata, lock state, issue lock, assignment, and workflow lease.
Failed bootstrap releases or safely transitions the assignment/lease so unattended work does not remain occupied until TTL.
The stable control checkout remains on the stable branch, clean, and unchanged.
Recovery supports exact-identity resumable work and refuses foreign/live ownership.
Native read-after-write proof reports the resulting branch, registered worktree path, HEAD/base SHA, assignment, lease, and lock state.
Regression coverage exercises success, permission denial, partial branch creation, partial worktree metadata/directory creation, guard recognition, rollback, lease cleanup, and stable-checkout preservation.
Controller allocation can either atomically include this transition or prove before allocation that the routed namespace can perform it.

Non-goals

Weakening registered-worktree proof.
Allowing arbitrary directories under branches/.
Permitting shell Git or helper scripts in MCP-only scheduled runs.
Reclaiming another identity's live work.

## Problem statement An unattended controller-routed author cycle cannot start a newly selected issue using only sanctioned Gitea-Tools MCP operations. For live Issue #639, the controller preview correctly routed `author / implement` to `gitea-author`. The author namespace passed identity, role, capability, namespace-health, workflow-skill, and master-parity checks, but it had no issue worktree yet. That is task-bound state before allocation, not itself an error. The required next transition is: `selected issue → assignment/lease → issue lock → validated branch/worktree under branches/` The live author tool registry exposes allocation/lease operations and `gitea_lock_issue`, but no native MCP operation that creates and binds the registered issue worktree needed by `gitea_lock_issue`. The runtime's only recovery guidance is `scripts/worktree-start` or `git worktree add`, which MCP-only scheduled workers are prohibited from using. ## Affected runtime - Repository: `Scaled-Tech-Consulting/Gitea-Tools` - Remote: `prgs` - Namespace/profile/identity/role: `gitea-author / prgs-author / jcwalker3 / author` - Controller selection: Issue #639, action `implement`, candidate fingerprint `82f19c3936eda98f9cf7c1923fc16a07c53749aad8b01dc007c9d4853fd42db7` - Server and live master SHA: `1c455b6ec0f9cb761fe6248de68c17e061fb5ecd` - Master parity: in parity; restart not required; mutation-safe - Canonical workflow: `work-issue.md` SHA-256 `14e515cdaa6a859c756c51091b71b4ed98e72b72e85ffa349b64bcff83b4c6d91` - Author namespace health: callable; `gitea_lock_issue` registered ## Expected behavior After atomic controller allocation, a role-correct author namespace must expose one sanctioned MCP transition that creates or recovers the issue branch and registered worktree under `branches/`, binds it to the assignment/lease, and makes it eligible for the canonical issue lock without touching the stable control checkout. ## Actual behavior No native MCP branch/worktree bootstrap operation is registered. The canonical tool inventory contains worktree audit/snapshot tools but no create/bind operation. `gitea_get_runtime_context` reports the stable control checkout and instructs the worker to use a shell helper or raw Git. In an MCP-only scheduled run, applying the allocation would therefore knowingly create a lease that cannot advance to the required issue lock/worktree state. No allocation was applied for #639, and no branch, worktree, lock, file, commit, push, or PR mutation was produced. ## Recovery attempts and authoritative evidence - Verified `gitea-workflow` mounts and clean instruction boundary. - Corrected the initial default-remote guide probe to authoritative remote `prgs`. - Verified controller and author identities and profiles. - Verified controller/author namespace health and current master parity. - Re-read #639 and dependencies: hard dependency #634 is closed; soft dependency #638 has an open PR. - `gitea_assess_work_issue_duplicate(issue_number=639, phase=pre_claim)`: no linked open PR, conflicting branch, or active claim. - Inspected the complete live author registry and `docs/mcp-tool-inventory.md`: only worktree audit/snapshot/cleanup assessment tools exist; no native create/bind transition exists. - Did not use shell Git, direct API, browser, credentials, filesystem worktree manipulation, or MCP internals. ## Assignment and lease impact - Issue #639: no assignment or lease created. - No issue lock exists for #639. - An unrelated stale-dead-process lease for #637 remains active, but #637 already has PR #849 and a protected clean open-PR worktree; it was not reclaimed or released because foreign ownership could not be safely authorized. ## Scheduled-run impact Every fresh MCP-only scheduled author cycle that selects an issue without an existing registered worktree must stop before allocation or create an unadvanceable lease. The live recovery text directs workers toward operations that the automation security boundary forbids. ## Duplicate search Searched all 469 open and closed issue titles and inspected the closest bodies. - #275: allows claim/lock from an already-created branches worktree; it does not create one. - #749 and #757: provide the pure-remote `create_issue` bootstrap; they do not bootstrap post-issue author worktrees. - #713: requires registered-worktree proof and rejects fake directories; it does not supply native creation/binding. - #39: covers shell worktree helpers, not MCP-only scheduled execution. - #618: worktree-binding consistency, not a native post-allocation bootstrap transition. - #812/#816: publication recovery for existing worktrees/commits, not first worktree creation. No issue fully covers this root cause. ## Acceptance criteria 1. A native author MCP operation atomically attempts `assigned issue → issue branch → registered branches/ worktree → bound workflow lease/assignment → issue-lock-ready state`. 2. The operation derives repository, stable branch, issue number, branch name, worktree path, identity, role, lease, and expected base SHA from authoritative state; callers cannot forge ownership. 3. Successful creation is recognized by the branches-only and anti-stomp guards and is base-equivalent to current live master. 4. Failure atomically rolls back every partial mutation: Git ref/branch, worktree directory, `.git/worktrees` metadata, lock state, issue lock, assignment, and workflow lease. 5. Failed bootstrap releases or safely transitions the assignment/lease so unattended work does not remain occupied until TTL. 6. The stable control checkout remains on the stable branch, clean, and unchanged. 7. Recovery supports exact-identity resumable work and refuses foreign/live ownership. 8. Native read-after-write proof reports the resulting branch, registered worktree path, HEAD/base SHA, assignment, lease, and lock state. 9. Regression coverage exercises success, permission denial, partial branch creation, partial worktree metadata/directory creation, guard recognition, rollback, lease cleanup, and stable-checkout preservation. 10. Controller allocation can either atomically include this transition or prove before allocation that the routed namespace can perform it. ## Non-goals - Weakening registered-worktree proof. - Allowing arbitrary directories under `branches/`. - Permitting shell Git or helper scripts in MCP-only scheduled runs. - Reclaiming another identity's live work.

jcwalker3 added the status:ready workflow-hardening type:bug labels 2026-07-23 14:37:59 -05:00

jcwalker3 commented

2026-07-23 15:17:17 -05:00

Specification amendment — durable, idempotent provisioning transition

This comment is an authoritative amendment to Issue #850. It refines the existing AC1–AC10 and replaces any implication of an unrealistic cross-system atomic transaction.

Durable phase journal

The provisioning operation MUST persist a durable phase journal for the transition. Each completed phase MUST have authoritative read-after-write evidence sufficient to resume safely after interruption.

The journal MUST distinguish at least:

request accepted and authoritative inputs recorded;
branch/ref created or valid existing branch confirmed;
canonical path reserved or valid existing path confirmed;
worktree created or valid existing worktree confirmed;
worktree registration verified;
lock, assignment, and lease state established;
transition completed;
compensating recovery required or completed.

Idempotency key

The operation MUST accept or authoritatively derive an idempotency key.

Replaying the same request with the same key and compatible authoritative inputs MUST return or recover the same transition and artifacts. It MUST NOT create duplicate branches, paths, worktrees, registrations, locks, assignments, or leases.

Reuse is permitted only after exact identity and compatibility are proven.

Concurrency pin and stale refusal

The request MUST carry an authoritative expected-base/concurrency pin.

If the live base, allocation, ownership, branch, path, worktree registration, or other protected state no longer matches the pin, the operation MUST fail closed with a typed stale-pin result. It MUST NOT silently rebase, repoint, overwrite, or continue against newer state.

Compensating recovery boundary

Rollback is compensating recovery, not a cross-system transaction.

Recovery MUST affect only artifacts proven to have been created by this journaled transition. Preexisting or foreign-owned refs, directories, worktrees, registrations, locks, assignments, leases, and tracked or untracked content MUST remain byte-for-byte unchanged.

Server-side implementation reuse

The MCP server MAY internally reuse vetted worktree-start logic or equivalent repository helpers.

The prohibition applies to callers and scheduled workers invoking shell Git, Bash, or helper scripts as a fallback. It does not prohibit validated server-side reuse behind the sanctioned MCP operation.

Canonical-path and preservation requirements

The operation MUST reject:

any requested or derived path outside the canonical branches root;
incompatible branch/path/worktree registrations;
foreign ownership;
ambiguous existing state;
preexisting dirty tracked or untracked content when the operation cannot prove preservation;
any recovery that would delete, clean, reset, overwrite, or modify protected preexisting work.

Satisfiable next action

Every blocking result MUST provide an exact_next_action that the caller can actually perform through its sanctioned capabilities at the phase where the blocker is emitted.

A scheduled MCP-only worker MUST NOT be directed to run scripts/worktree-start, git worktree add, Bash, or another forbidden fallback.

Required regression scenarios

Tests MUST cover at least:

concurrent duplicate bootstrap requests;
interruption and replay after every journaled phase;
stale expected base or concurrency pin;
a path outside the canonical branches root;
preexisting dirty tracked and untracked work;
protected preexisting work remaining byte-for-byte unchanged.

These requirements extend #850 without expanding it into stale-daemon, namespace-availability, restart-required, post-merge resynchronization, general lease-renewal, or cycle-terminal-state-classifier work.

Canonical Issue State

STATE: ready
WHO_IS_NEXT: controller
NEXT_ACTION: Controller assesses eligibility and allocates Issue #850 after specification amendment verification
NEXT_PROMPT:

Assess Issue #850 eligibility and allocate to gitea-author for implementation of native MCP bootstrap provisioning per amended specification.

WHAT_HAPPENED: Author appended authoritative specification amendment for durable, idempotent provisioning transition to Issue #850.
WHY: Refines AC1-AC10 into journaled phases, idempotency key, concurrency pin, compensating recovery, server-side reuse, canonical path/preservation, and satisfiable next action.
RELATED_PRS: none
BLOCKERS: none
VALIDATION: Author verified Issue #850 open, read prior state, resolved comment_issue capability, and posted authoritative amendment comment with read-after-write verification.
LAST_UPDATED_BY: jcwalker3 (prgs-author)

## Specification amendment — durable, idempotent provisioning transition This comment is an authoritative amendment to Issue #850. It refines the existing AC1–AC10 and replaces any implication of an unrealistic cross-system atomic transaction. 1. Durable phase journal The provisioning operation MUST persist a durable phase journal for the transition. Each completed phase MUST have authoritative read-after-write evidence sufficient to resume safely after interruption. The journal MUST distinguish at least: - request accepted and authoritative inputs recorded; - branch/ref created or valid existing branch confirmed; - canonical path reserved or valid existing path confirmed; - worktree created or valid existing worktree confirmed; - worktree registration verified; - lock, assignment, and lease state established; - transition completed; - compensating recovery required or completed. 2. Idempotency key The operation MUST accept or authoritatively derive an idempotency key. Replaying the same request with the same key and compatible authoritative inputs MUST return or recover the same transition and artifacts. It MUST NOT create duplicate branches, paths, worktrees, registrations, locks, assignments, or leases. Reuse is permitted only after exact identity and compatibility are proven. 3. Concurrency pin and stale refusal The request MUST carry an authoritative expected-base/concurrency pin. If the live base, allocation, ownership, branch, path, worktree registration, or other protected state no longer matches the pin, the operation MUST fail closed with a typed stale-pin result. It MUST NOT silently rebase, repoint, overwrite, or continue against newer state. 4. Compensating recovery boundary Rollback is compensating recovery, not a cross-system transaction. Recovery MUST affect only artifacts proven to have been created by this journaled transition. Preexisting or foreign-owned refs, directories, worktrees, registrations, locks, assignments, leases, and tracked or untracked content MUST remain byte-for-byte unchanged. 5. Server-side implementation reuse The MCP server MAY internally reuse vetted worktree-start logic or equivalent repository helpers. The prohibition applies to callers and scheduled workers invoking shell Git, Bash, or helper scripts as a fallback. It does not prohibit validated server-side reuse behind the sanctioned MCP operation. 6. Canonical-path and preservation requirements The operation MUST reject: - any requested or derived path outside the canonical branches root; - incompatible branch/path/worktree registrations; - foreign ownership; - ambiguous existing state; - preexisting dirty tracked or untracked content when the operation cannot prove preservation; - any recovery that would delete, clean, reset, overwrite, or modify protected preexisting work. 7. Satisfiable next action Every blocking result MUST provide an exact_next_action that the caller can actually perform through its sanctioned capabilities at the phase where the blocker is emitted. A scheduled MCP-only worker MUST NOT be directed to run scripts/worktree-start, git worktree add, Bash, or another forbidden fallback. 8. Required regression scenarios Tests MUST cover at least: - concurrent duplicate bootstrap requests; - interruption and replay after every journaled phase; - stale expected base or concurrency pin; - a path outside the canonical branches root; - preexisting dirty tracked and untracked work; - protected preexisting work remaining byte-for-byte unchanged. These requirements extend #850 without expanding it into stale-daemon, namespace-availability, restart-required, post-merge resynchronization, general lease-renewal, or cycle-terminal-state-classifier work. ## Canonical Issue State STATE: ready WHO_IS_NEXT: controller NEXT_ACTION: Controller assesses eligibility and allocates Issue #850 after specification amendment verification NEXT_PROMPT: ```text Assess Issue #850 eligibility and allocate to gitea-author for implementation of native MCP bootstrap provisioning per amended specification. ``` WHAT_HAPPENED: Author appended authoritative specification amendment for durable, idempotent provisioning transition to Issue #850. WHY: Refines AC1-AC10 into journaled phases, idempotency key, concurrency pin, compensating recovery, server-side reuse, canonical path/preservation, and satisfiable next action. RELATED_PRS: none BLOCKERS: none VALIDATION: Author verified Issue #850 open, read prior state, resolved comment_issue capability, and posted authoritative amendment comment with read-after-write verification. LAST_UPDATED_BY: jcwalker3 (prgs-author)

jcwalker3 referenced this issue from a commit

2026-07-23 16:29:04 -05:00

Implement native author issue worktree bootstrap (#850)

jcwalker3 referenced a pull request that will close this issue

2026-07-23 16:29:45 -05:00

Implement native author issue worktree bootstrap (#850) #853

jcwalker3 added status:pr-open and removed status:ready labels 2026-07-23 16:29:46 -05:00

sysadmin referenced this issue

2026-07-23 17:23:15 -05:00

Implement native author issue worktree bootstrap (#850) #853

jcwalker3 referenced this issue from a commit

2026-07-23 17:49:34 -05:00