Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 2 additions & 5 deletions .claude/commands/pm/issue-close.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,9 +107,6 @@ open_blockers=$(gh api --paginate "repos/{owner}/{repo}/issues/$issue_number/dep
--jq '.[] | select(.state != "closed") | .number') || exit 1
[ -z "$open_blockers" ] || { echo "❌ Native blockers remain open" >&2; exit 1; }
issue_labels=$(gh issue view "$issue_number" --json labels --jq '.labels[].name') || exit 1
category_count=$(printf '%s\n' "$issue_labels" | awk '$0 == "bug" || $0 == "enhancement" { n++ } END { print n + 0 }')
triage_count=$(printf '%s\n' "$issue_labels" | awk '/^(needs-triage|needs-info|ready-for-agent|ready-for-human|wontfix)$/ { n++ } END { print n + 0 }')
[ "$category_count" -eq 1 ] && [ "$triage_count" -eq 1 ] || { echo "❌ Issue labels violate the lifecycle contract" >&2; exit 1; }

if printf '%s\n' "$issue_labels" | grep -Fxq tracking; then
open_children=$(gh api --paginate "repos/{owner}/{repo}/issues/$issue_number/sub_issues" \
Expand All @@ -122,8 +119,8 @@ if printf '%s\n' "$issue_labels" | grep -Fxq tracking; then
fi

if printf '%s\n' "$issue_labels" | grep -Fxq runtime; then
runtime_record=$(gh issue view "$issue_number" --json comments \
--jq '[.comments[].body] | join("\n")') || exit 1
runtime_record=$(gh issue view "$issue_number" --json body,comments \
--jq '[.body] + [.comments[].body] | join("\n")') || exit 1
runtime_record="$runtime_record
$completion_evidence"
for field in "Exact target" "Named controller" "Candidate identity" \
Expand Down
20 changes: 11 additions & 9 deletions .claude/commands/pm/issue-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,14 @@ allowed-tools: Bash, Read, Write, LS, Task

# Issue Start

Verify the issue has one change contract, acceptance evidence, out-of-scope
boundary, and declared dependency. Then create one dedicated worktree and
record its contract, owner, path, branch, base SHA, allowed files, and
dependency in the worktree-private `agent-worktree.yml` path returned by
`git rev-parse --git-path agent-worktree.yml`.

Launch one writable agent only. Any concurrent analysis or review is read-only.
Stop if ownership, the base SHA, or file scope is ambiguous. Do not clean up a
worktree or branch without explicit repository-owner authorization.
Read the issue outcome, proof, comments, and native dependencies. Stop only when
the next behavior, authority, or required input is genuinely ambiguous.

Keep one write owner. Use the current checkout for an isolated local change with
known ownership and dirty state. Create a dedicated branch/worktree and private
`agent-worktree.yml` record only for concurrent, published, or multi-session
work.

Do not create another issue for an owner handoff or another attempt at the same
outcome. Record attempts, failures, cleanup, and evidence on the existing issue.
Never remove a branch or worktree without explicit repository-owner authority.
34 changes: 12 additions & 22 deletions .claude/rules/agent-coordination.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,17 @@
# Agent Coordination

Each section, issue, and PR has one write owner, branch, and worktree. Never
place multiple writable agents in one worktree or have them exchange work by
pulling a shared branch.
One active contract has one write owner. Read-only research and review may run
in parallel.

Before the first write, the owner records:
Use the current checkout for an isolated local change when its ownership and
dirty state are known. Use a dedicated branch and worktree when work is
concurrent, published, or likely to span sessions. A managed worktree records
its contract, owner, path, branch, base SHA, allowed files, and dependencies in
the private path returned by `git rev-parse --git-path agent-worktree.yml`.

```yaml
contract: Issue #{number}: {one behavior contract}
owner: {agent or human}
worktree: .worktrees/codex/{issue-slug}
branch: codex/{issue-slug}
base_sha: {exact integration-base SHA}
allowed_files: [{paths or patterns}]
dependency: None | #{blocking-issue}
```
Stop on overlapping ownership or unexpected branch movement. Re-read branch,
`HEAD`, status, and PR head before publishing or merging. Ownership handoff does
not create a new issue; update the existing contract record.

Write this YAML to the worktree-private path returned by
`git rev-parse --git-path agent-worktree.yml`. It is the runtime record; this
policy file is only its template and must not be overwritten.

Read-only research and review may run in parallel. A second writable change is
either a separate issue/worktree or waits for an explicit ownership transfer.
Before every edit, commit, rebase, push, or merge, re-read the branch, `HEAD`,
and worktree status; stop on unexpected movement. Report final worktree status
to the coordinator. Cleanup requires explicit repository-owner authorization.
Never remove a worktree or branch without explicit repository-owner
authorization for the exact target.
15 changes: 8 additions & 7 deletions .claude/rules/branch-operations.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
# Branch Operations

A branch belongs to one independently mergeable section, issue, and PR. Its
dedicated worktree has exactly one write owner.
Use a branch when a change will be published or must be isolated from concurrent
writes. A branch has one write owner and contains one independently reviewable
behavior.

Before edits, commits, rebases, pushes, or merges, re-read the branch, `HEAD`,
and status. Do not pull or push another issue's branch as a synchronization
mechanism; depend on the merged predecessor or an explicitly declared stack.
Re-read branch, `HEAD`, status, and PR head before publishing or merging. Do not
use another contract's branch as a synchronization mechanism; depend on its
merged result or an explicit stack.

Preserve branches and worktrees after merge, failure, or abandonment until the
repository owner explicitly authorizes cleanup of exact targets.
Do not delete a branch or worktree without explicit repository-owner
authorization for the exact target.
17 changes: 8 additions & 9 deletions .claude/rules/worktree-operations.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
# Worktree Operations

One section, issue, and PR is one writable rollback unit. Create one dedicated
worktree and branch for that unit; do not place two writable agents in it.
A worktree isolates concurrent, published, or multi-session writes. It is not
required for read-only work or an isolated local change with known ownership.

Before the first write, record the contract, owner, worktree path, branch, base
SHA, allowed files, and dependency. Re-read the branch, `HEAD`, and status
before edits, commits, rebases, pushes, or merges. A reviewer is read-only.
Each writable worktree has one owner. Before its first write, record the
contract, owner, path, branch, base SHA, allowed files, and dependencies in the
private `agent-worktree.yml` path returned by Git.

Use the declared integration base, not a blind checkout of `main`. Preserve
worktrees after merge or abandonment until the repository owner explicitly
authorizes removal. `git worktree list --porcelain` is the read-only inventory
command; do not use `remove`, `prune`, or branch deletion as recovery steps.
Stop on overlap or unexpected movement. Preserve worktrees after merge or
abandonment until the repository owner explicitly authorizes exact cleanup;
never use removal, prune, reset, or branch deletion as recovery.
9 changes: 6 additions & 3 deletions .claude/scripts/pm/test-github-first-issue-mutations.sh
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,9 @@ case "$*" in
'issue view 123 --json comments --jq'*)
if [ "${GH_SCENARIO:-}" = runtime_comments ]; then echo 'Exact target: svc; Named controller: alice; Candidate identity: sha-1; Configuration identity: cfg-1; Rollback identity: sha-0; Rollback procedure: restore; Stop rules: any failure; Terminal result: passed; Cleanup evidence: removed'; fi ;;
'issue view 123 --json body,comments --jq'*)
if [ "${GH_SCENARIO:-}" = runtime_body_only ]; then echo 'Exact target: svc; Named controller: alice; Candidate identity: sha-1; Configuration identity: cfg-1; Rollback identity: sha-0; Rollback procedure: restore; Stop rules: any failure; Terminal result: passed; Cleanup evidence: removed'; fi ;;
case "${GH_SCENARIO:-}" in
runtime_body_only|runtime_comments) echo 'Exact target: svc; Named controller: alice; Candidate identity: sha-1; Configuration identity: cfg-1; Rollback identity: sha-0; Rollback procedure: restore; Stop rules: any failure; Terminal result: passed; Cleanup evidence: removed' ;;
esac ;;
'issue view 123 --json number,title,state,url') [ "${GH_SCENARIO:-}" != read_fail ] && echo '{"number":123}' ;;
'issue view 123 --json state,updatedAt,url --jq'*)
[ "${GH_SCENARIO:-}" != reopen_final_read_fail ] || exit 1
Expand Down Expand Up @@ -74,13 +76,14 @@ refuse normal 'Acceptance checks: Result : passed; Result: passed'
refuse normal 'Acceptance checks: - Result: passed; Result: passed'
refuse normal 'Acceptance checks: ~~Result:~~ passed; Result: passed'
refuse normal 'Acceptance checks: focused; Result: failed'
for scenario in blocker no_category conflict_category no_triage conflict_triage; do refuse "$scenario" "$valid"; done
refuse blocker "$valid"
for scenario in no_category conflict_category no_triage conflict_triage; do allow "$scenario" "$valid"; done
refuse tracking "$valid"
refuse tracking_child "$valid; Parent acceptance audit: passed"
allow tracking_box "$valid; Parent acceptance audit: passed"
runtime='Exact target: svc; Named controller: alice; Candidate identity: sha-1; Configuration identity: cfg-1; Rollback identity: sha-0; Rollback procedure: restore; Stop rules: any failure; Terminal result: passed; Cleanup evidence: removed'
refuse runtime "$valid; ${runtime/Terminal result: passed/Terminal result: failed}"
refuse runtime_body_only "$valid"
allow runtime_body_only "$valid"
for field in "Exact target" "Named controller" "Candidate identity" "Configuration identity" "Rollback identity" "Rollback procedure" "Stop rules" "Terminal result" "Cleanup evidence"; do
missing=$(printf '%s' "$runtime" | sed -E "s/(^|; )$field: [^;]*(; |$)/\\1/")
placeholder=$(printf '%s' "$runtime" | sed -E "s/($field: )[^;]*/\\1TBD/")
Expand Down
30 changes: 8 additions & 22 deletions .github/ISSUE_TEMPLATE/bug-report.yml
Original file line number Diff line number Diff line change
@@ -1,32 +1,18 @@
name: Bug report
description: Report reproducible broken behavior for triage
labels: ["bug", "needs-triage"]
description: Record reproducible broken behavior
labels: ["bug"]
Comment thread
proerror77 marked this conversation as resolved.
body:
- type: textarea
id: current_behavior
id: evidence
attributes:
label: Current behavior
description: Describe what is broken and where it was observed.
label: Broken behavior and evidence
description: What happened, where, and the smallest repeatable observation.
validations:
required: true
- type: textarea
id: reproduction
id: expected
attributes:
label: Focused reproduction
description: Provide the smallest repeatable steps and exact evidence.
validations:
required: true
- type: textarea
id: expected_behavior
attributes:
label: Expected behavior
description: Describe the correct observable result.
validations:
required: true
- type: textarea
id: boundary
attributes:
label: Safety and scope boundary
description: Name affected trust domains and work that must remain unchanged.
label: Expected result
description: State the correct observable behavior.
validations:
required: true
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
blank_issues_enabled: false
blank_issues_enabled: true
contact_links: []
37 changes: 8 additions & 29 deletions .github/ISSUE_TEMPLATE/engineering-change.yml
Original file line number Diff line number Diff line change
@@ -1,39 +1,18 @@
name: Engineering change
description: Propose one independently mergeable and rollbackable improvement
labels: ["enhancement", "needs-triage"]
description: Record one independently verifiable improvement
labels: ["enhancement"]
body:
- type: textarea
id: contract
id: outcome
attributes:
label: Change contract
description: State one behavior and why it is needed.
label: Outcome
Comment thread
proerror77 marked this conversation as resolved.
description: What observable behavior should change, and why?
validations:
required: true
- type: textarea
id: acceptance
id: proof
attributes:
label: Acceptance evidence
description: List externally observable checks, including a safety counterexample where applicable.
validations:
required: true
- type: textarea
id: dependencies
attributes:
label: Dependencies and merge order
description: Use GitHub native blocked-by relationships after publication; write None when independent.
validations:
required: true
- type: textarea
id: out_of_scope
attributes:
label: Out of scope
description: Name adjacent behavior and trust domains excluded from this issue.
validations:
required: true
- type: textarea
id: rollout
attributes:
label: Rollout and rollback impact
description: State the production impact or None.
label: Proof
description: What smallest check will prove the outcome?
validations:
required: true
47 changes: 13 additions & 34 deletions .github/ISSUE_TEMPLATE/prd.yml
Original file line number Diff line number Diff line change
@@ -1,47 +1,26 @@
name: Product requirement
description: Define a multi-step outcome before decomposition
title: "PRD: "
labels: ["enhancement", "needs-triage", "tracking"]
name: Product outcome
description: Coordinate a durable multi-owner or multi-session outcome
title: "Outcome: "
labels: ["enhancement", "tracking"]
body:
- type: textarea
id: problem
attributes:
label: Problem Statement
description: Describe the user-visible problem and why it matters.
label: Problem
description: What user-visible problem must be solved?
validations:
required: true
- type: textarea
id: solution
id: outcome
attributes:
label: Solution
description: Describe the outcome without prescribing speculative machinery.
label: Observable outcome
description: What result proves the problem is solved?
validations:
required: true
- type: textarea
id: stories
id: constraints
attributes:
label: User Stories
description: List the actors, capabilities, and benefits this outcome must cover.
label: Constraints
description: Record only real authority, safety, or compatibility boundaries.
validations:
required: true
- type: textarea
id: decisions
attributes:
label: Implementation Decisions
description: Record approved boundaries, interfaces, and rollout units.
validations:
required: true
- type: textarea
id: testing
attributes:
label: Testing Decisions
description: Name the public seams and acceptance evidence.
validations:
required: true
- type: textarea
id: out_of_scope
attributes:
label: Out of Scope
description: Name adjacent work that this PRD does not authorize.
validations:
required: true
required: false
35 changes: 14 additions & 21 deletions .github/ISSUE_TEMPLATE/runtime-rollout.yml
Original file line number Diff line number Diff line change
@@ -1,53 +1,46 @@
name: Runtime rollout
description: Request one bounded live mutation or runtime-evidence contract
labels: ["enhancement", "needs-triage", "runtime"]
name: Runtime outcome
description: Request and record one bounded live outcome
labels: ["enhancement", "runtime"]
body:
- type: input
id: target
attributes:
label: Exact target identity
description: Name the bounded host, cluster resource, service, or repository setting.
label: Exact target
validations:
required: true
- type: input
id: controller
attributes:
label: Named controller
description: Name the one authorized writer for this rollout.
label: One controller
validations:
required: true
- type: textarea
id: candidate
attributes:
label: Candidate and configuration identity
description: Record immutable source, artifact/image/binary, and configuration identities.
label: Candidate identity
validations:
required: true
- type: textarea
id: rollback
id: configuration
attributes:
label: Rollback identity and procedure
description: Record the immutable previous state and bounded rollback action.
label: Configuration identity
validations:
required: true
- type: textarea
id: stop_rules
id: rollback
attributes:
label: Stop rules
description: Name failures that stop mutation or prevent promotion.
label: Rollback identity and procedure
validations:
required: true
- type: textarea
id: success
id: stop
attributes:
label: Success and cleanup evidence
description: Define independent readback, post-change observation, cleanup, and rollback-expiry evidence.
label: Stop and cleanup rules
validations:
required: true
- type: textarea
id: out_of_scope
id: proof
attributes:
label: Out of scope
description: Name adjacent resources, services, and trust domains that must not change.
label: Success and direct readback
validations:
required: true
Loading
Loading