Scaled-Tech-Consulting/Gitea-Tools
2
0
Fork 0
Code Issues 73 Pull Requests 9 Actions Packages Projects Releases Wiki Activity

fix: clarify capability preflight lifetime across safe reads (Closes #470) #490

Closed
jcwalker3 wants to merge 5 commits from feat/issue-470-preflight-contract into master
pull from: feat/issue-470-preflight-contract
merge into: :master
Conversation 2 Commits 5 Files Changed 4
+154 -3
jcwalker3 commented 2026-07-08 01:32:15 -05:00
Owner
Copy Link
Copy Source

Summary

Closes #470. Extends #469 with an explicit capability-preflight lifetime contract: read-only calls preserve proof until a gated mutation consumes it, and fail-closed errors name the exact re-resolve step.

Changes

  • preflight_contract.py — read-only safe tool set, format_missing_capability_error, format_task_mismatch_error
  • gitea_mcp_server.py — wire contract errors into verify_preflight_purity; pass task="comment_issue" on conflict-fix lease gate
  • tests/test_preflight_read_survival.py — close_pr sequencing, task replacement, explicit re-resolve error messages
  • docs/llm-workflow-runbooks.md — canonical preflight lifetime / sequencing rules

Verification

venv/bin/python -m pytest tests/test_preflight_read_survival.py tests/test_resolve_task_capability.py -q
# 31 passed

Worktree

branches/issue-470-preflight-safe-reads @ a8bcbdb

## Summary Closes #470. Extends #469 with an explicit capability-preflight lifetime contract: read-only calls preserve proof until a gated mutation consumes it, and fail-closed errors name the exact re-resolve step. ## Changes - `preflight_contract.py` — read-only safe tool set, `format_missing_capability_error`, `format_task_mismatch_error` - `gitea_mcp_server.py` — wire contract errors into `verify_preflight_purity`; pass `task="comment_issue"` on conflict-fix lease gate - `tests/test_preflight_read_survival.py` — close_pr sequencing, task replacement, explicit re-resolve error messages - `docs/llm-workflow-runbooks.md` — canonical preflight lifetime / sequencing rules ## Verification ```bash venv/bin/python -m pytest tests/test_preflight_read_survival.py tests/test_resolve_task_capability.py -q # 31 passed ``` ## Worktree `branches/issue-470-preflight-safe-reads` @ `a8bcbdb`
jcwalker3 added 3 commits 2026-07-08 01:32:15 -05:00
fix: preserve capability preflight across interleaved read-only whoami (#469) 514eae84f9 
Read-only gitea_whoami calls no longer clear a valid capability proof when
whoami was already verified clean. Capability is consumed on mutation (one
resolve per mutation), and verify_preflight_purity rejects task mismatches.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
test: reset preflight globals in read-survival setUp (#469) 2d4ab4e54e 
Prevents cross-test leakage that masked the missing-capability fail-closed case.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
fix: clarify capability preflight lifetime across safe reads (Closes #470) a8bcbdbcf2 
Add preflight_contract helpers with explicit re-resolve error messages,
document the read-only tool set and consumption rules, and extend tests
for close_pr sequencing and task replacement.

Validation: ./venv/bin/python -m pytest tests/test_preflight_read_survival.py tests/test_mcp_server.py::TestPreflightVerification -q

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
sysadmin commented 2026-07-08 01:36:21 -05:00
Owner
Copy Link
Copy Source

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #490
issue: #470
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 97777-d81fc7c9bdaa
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr490-issue-470
phase: claimed
candidate_head: a8bcbdbcf2
target_branch: master
target_branch_sha: 7af73e1539
last_activity: 2026-07-08T06:36:21Z
expires_at: 2026-07-08T08:36:21Z
blocker: none

<!-- mcp-review-lease:v1 --> repo: Scaled-Tech-Consulting/Gitea-Tools pr: #490 issue: #470 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 97777-d81fc7c9bdaa worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr490-issue-470 phase: claimed candidate_head: a8bcbdbcf2bb90ab047dc7df6083e5187ae3cbad target_branch: master target_branch_sha: 7af73e1539031009051c3b12b0bd286eddc84ae5 last_activity: 2026-07-08T06:36:21Z expires_at: 2026-07-08T08:36:21Z blocker: none
sysadmin approved these changes 2026-07-08 01:36:38 -05:00
sysadmin left a comment
Owner
Copy Link
Copy Source

Review summary (issue #470)

Decision: APPROVE at head a8bcbdbcf2bb90ab047dc7df6083e5187ae3cbad.

Issue #470 coverage

  • Contract module (preflight_contract.py) documents safe read tools and explicit re-resolve error copy.
  • verify_preflight_purity(task=…) enforces task binding, consumes proof on successful mutation, and uses actionable error messages naming gitea_resolve_task_capability(task="…").
  • record_preflight_check preserves capability across interleaved clean whoami (#469) without weakening permission gates.
  • Docs section “Capability preflight lifetime (#470)” matches runtime behavior.
  • Tests cover close_pr sequencing, task replacement, consumption, and explicit re-resolve wording.

Overlap with PR #474 / issue #469

  • #490 cherry-picks the #469 whoami-survival fix inline (commits 514eae8, 2d4ab4e) plus the #470 contract commit a8bcbdb.
  • Diff vs master is limited to 4 files (+341/−32); merge-tree simulation into master is clean.
  • Simulated merge of #490 onto #474 branch shows no conflicts.
  • Ordering: #490 is self-contained against master and does not require #474 to land first. If #490 merges first, #474 becomes redundant and should be closed/reconciled. If #474 lands first, #490 should still merge cleanly.

Authorization gates

  • Still requires whoami + resolved capability + matching task before mutations.
  • Capability is consumed once per mutation; missing/mismatched/consumed states fail closed with re-resolve instructions (no bypass path).
  • READ_ONLY_PREFLIGHT_TOOLS is documentary; runtime preservation for view/list/read tools holds because only whoami/capability touch preflight state.

Validation (review worktree branches/review-pr490-issue-470)

  • pytest tests/test_preflight_read_survival.py tests/test_mcp_server.py::TestPreflightVerification -q → 19 passed
  • py_compile on changed Python files → OK
  • git diff --check prgs/master...HEAD → clean
  • Full suite: 1741 passed, 6 skipped; 1 pre-existing failure TestMergePR::test_merge_blocked_on_stale_approval_head also fails on pristine master (out of scope).

Notes

  • Branch history is noisy, but the PR diff vs master is tight and scoped.
  • Recommend reconciling/closing #474 after #490 lands to avoid duplicate #469 work.
## Review summary (issue #470) **Decision: APPROVE** at head `a8bcbdbcf2bb90ab047dc7df6083e5187ae3cbad`. ### Issue #470 coverage - Contract module (`preflight_contract.py`) documents safe read tools and explicit re-resolve error copy. - `verify_preflight_purity(task=…)` enforces task binding, consumes proof on successful mutation, and uses actionable error messages naming `gitea_resolve_task_capability(task="…")`. - `record_preflight_check` preserves capability across interleaved clean whoami (#469) without weakening permission gates. - Docs section “Capability preflight lifetime (#470)” matches runtime behavior. - Tests cover close_pr sequencing, task replacement, consumption, and explicit re-resolve wording. ### Overlap with PR #474 / issue #469 - #490 cherry-picks the #469 whoami-survival fix inline (commits `514eae8`, `2d4ab4e`) plus the #470 contract commit `a8bcbdb`. - Diff vs `master` is limited to 4 files (+341/−32); merge-tree simulation into `master` is clean. - Simulated merge of #490 onto #474 branch shows no conflicts. - **Ordering:** #490 is self-contained against `master` and does not require #474 to land first. If #490 merges first, #474 becomes redundant and should be closed/reconciled. If #474 lands first, #490 should still merge cleanly. ### Authorization gates - Still requires whoami + resolved capability + matching task before mutations. - Capability is consumed once per mutation; missing/mismatched/consumed states fail closed with re-resolve instructions (no bypass path). - `READ_ONLY_PREFLIGHT_TOOLS` is documentary; runtime preservation for view/list/read tools holds because only whoami/capability touch preflight state. ### Validation (review worktree `branches/review-pr490-issue-470`) - `pytest tests/test_preflight_read_survival.py tests/test_mcp_server.py::TestPreflightVerification -q` → **19 passed** - `py_compile` on changed Python files → OK - `git diff --check prgs/master...HEAD` → clean - Full suite: **1741 passed, 6 skipped**; 1 pre-existing failure `TestMergePR::test_merge_blocked_on_stale_approval_head` also fails on pristine `master` (out of scope). ### Notes - Branch history is noisy, but the PR diff vs `master` is tight and scoped. - Recommend reconciling/closing #474 after #490 lands to avoid duplicate #469 work.
jcwalker3 added 1 commit 2026-07-08 02:59:54 -05:00
fix: resolve conflicts for PR #490 2e4ebc6434 
Merge prgs/master into feat/issue-470-preflight-contract, keeping stacked-PR
lock base support (#484) and explicit task binding on lock_issue preflight (#470).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
jcwalker3 added 1 commit 2026-07-08 03:09:18 -05:00
fix: resolve conflicts for PR #490 00efda0cfb 
Merge prgs/master; unify preflight read-survival tests (#469 + #470 contract).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
jcwalker3 closed this pull request 2026-07-08 03:39:08 -05:00

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
Reviewers
No Reviewers
sysadmin
Labels
Clear labels
allocator
Controller-owned work allocator
 anti-stomp
Prevent concurrent LLM session stomping
 architecture
Architecture / structural design
 bug
chore
codex
OpenAI Codex client / workflow session surface
 concurrency
Concurrent session safety
 contamination
Workflow or session contamination incident
 control-plane
MCP control-plane coordination and allocation authority
 dashboard
MCP operational dashboard/queue view
 database
Internal coordination storage (SQLite/Postgres)
 design
Design / investigation, no implementation
 documentation
Docs / runbooks
 enhancement
New feature or improvement
 gitea
Gitea MCP workflow
 glitchtip
GlitchTip integration
 important
incident
Operational or process incident requiring durable audit trail
 incident-bridge
Sentry-to-Gitea incident bridging
 integration
Integration testing
 jenkins
Jenkins integration
 labels
Label taxonomy management
 leases
Lease adopt/release/expire lifecycle
 mcp
MCP server / tooling
 mcp-health
MCP namespace and runtime health
 mcp-menu
MCP menu surface
 multi-project
Work spanning multiple monitoring projects or Gitea repos
 mutating
Mutating action; requires gating
 nice-to-have
observability
Observability, metrics, traces, error reporting
 portability
Cross-platform / portability
 preflight
Shared preflight gates before mutation
 protected-branch
Protected branch / stable-branch policy concern
 queue
Work queue visibility and allocation
 read-only
Read-only, no mutation
 reconnect
MCP client reconnect/reload recovery path
 recovery
Recovery paths for stale/foreign leases
 refactor
Code refactor / restructure
 release
Release / versioning
 reliability
Reliability / failure handling
 resumable-review
Persist and resume prepared review verdicts across sessions
 reviewer
Reviewer workflow tooling
 roadmap
Roadmap / umbrella issue
 safety
Safety rails and fail-closed mutation guards
 security
Security / trust boundary
 self-hosted
Self-hosted infrastructure integration
 sentry
Sentry error monitoring integration
 stale-runtime
Stale backend daemon / runtime-vs-master parity failures
 status:blocked
Issue is blocked
 status:in-progress
Issue is being worked on
 status:pr-open
Issue has an open pull request
 status:ready
Issue is ready for work
 terminal-lock
Terminal review lock (#332) path
 testing
Tests / test coverage
 tracker
Issue tracker hygiene / meta
 type:bug
Bug or defect
 type:feature
Feature or enhancement
 type:feature
Feature or enhancement
 type:guardrail
Safety gate or guardrail
 visibility
Workflow state visibility for LLMs/operators
 workflow
Cross-tool workflow
 workflow-hardening
LLM workflow coordination hardening
 workflow-hardening
LLM workflow coordination hardening
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
jcwalker3 sysadmin
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#490