fix(ci): remove orphaned agent worktree gitlink

[4444J99]

Outcome

Repairs both failures exposed by the exact main push after #503:

1. Removes the orphaned tracked agent-worktree gitlink that makes actions/checkout cleanup fail before Semantic Release can run.
2. Repairs the Demo sandbox contract end to end: valid and idempotent README badge mutation, compliant automation metadata, a durable Codespaces URL derived only from files actually present in the repository, and push coverage whenever the reusable workflow changes.

Gitlink custody proof

• Detached target: efff71c
• The target is reachable on the remote and is an ancestor of origin/main at 62a8f08.
• Remote custody: efff71c
• The tracked entry was only a gitlink reference; its checkout directory was empty and no unique payload was removed.

Demo custody proof

• Failed main run: https://github.com/organvm/dot-github--theoria/actions/runs/29203572112
• Generated branch commit whose intent is preserved here: 1d1804c
• The generated sed output corrupted the ampersand-bearing Codespaces URL, Actions was forbidden by organization policy from opening its PR, and its advertised devcontainer existed only in a disposable runner.
• This PR lands a corrected badge directly, removes the runner-only path claim, and adds behavioral regressions for exact URL preservation, repository-owned devcontainer selection, generic fallback, and byte-identical reruns.

Verification

• Focused policy suite: 15 passed
• actionlint on both Demo workflows: passed
• Pre-commit on changed source files: passed, with managed-link rewriting intentionally skipped because it mutates unrelated documentation; the registry's known hash-only detect-secrets false positives were independently scoped.
• Workflow registry SHA-256 values match both changed Demo workflows.
• git diff --check: passed

Merge condition

All required exact-head checks pass, merge-queue checks pass, and Semantic Release plus Demo Sandbox are green on the resulting main SHA.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[github-actions]

🤖 Hi @4444J99, I've received your request, and I'm working on it now! You can track my progress in the logs for more details.

[github-actions]

🔍 Reviewers Assigned

Reviewers have been automatically assigned based on the CODEOWNERS file.

What's Next:

• Reviewers will be notified
• Please respond to any feedback
• Ensure all CI checks pass
• Reviews typically completed within 48 hours

Need Help?

• Review Process Guide
• Contributing Guidelines

---

Automated reviewer assignment - PR #504

[github-actions]

✅ Task Catcher Summary

✅ All clear - No pending tasks

📋 Task Overview

Category	Count
PR Body Unchecked Tasks	0
PR Body Checked Tasks	0 ✅
Comment Tasks	0
Blocker Items	0 🚨
Suggestions	0 💡
Unresolved Review Threads	0

---

🎯 Next Steps

• 🚀 All tasks complete! Ready to merge when CI passes.

---

Options:

• ✅ Check off tasks as you complete them
• 📋 Create issues for tasks to handle later: Add create-issues-for-tasks label
• 🚫 Ignore tasks for merge: Add ignore-task-checks label

Last scanned: 2026-07-12 18:50 UTC
Triggered by: issue_comment

[github-actions]

💡 Tip: Link Related Issues

We noticed this PR doesn't reference any issues. If this PR addresses an existing issue, please link it using:

• Fixes #123 (for bug fixes)
• Closes #123 (for feature implementations)
• Relates to #123 (for related work)

This helps track the relationship between issues and PRs.

[claude]

Code Review — fix(ci): remove orphaned agent worktree gitlink

Overview

This PR fixes a broken actions/checkout cleanup step caused by an orphaned gitlink (mode 160000) at .claude/worktrees/agent-a9ca0d473436e9943 pointing to commit efff71cb. The three-part fix is: (1) remove the tracked gitlink, (2) prevent recurrence via .gitignore, and (3) add a regression test. The approach is correct and well-scoped.

---

What the PR Does

• Removes .claude/worktrees/agent-a9ca0d473436e9943 — an orphaned subproject gitlink that caused actions/checkout's post-run cleanup to fail, blocking Semantic Release.
• Adds /.claude/worktrees/ to .gitignore (root-anchored, correct).
• Adds test_agent_worktrees_are_local_runtime_state to the policy contracts test suite.

---

Code Quality

.gitignore

• The leading / correctly anchors the pattern to the repo root, matching the existing .serena/ convention directly above it. ✓
• Placement is consistent with the "Local tool configuration" comment block. ✓

test_workflow_policy_contracts.py

• The test correctly validates two independent invariants: (a) the ignore rule exists, and (b) no paths are currently tracked.
• Using subprocess.run with check=True is safe and idiomatic here.
• capture_output=True, text=True is the correct modern alternative to stdout=PIPE.

One observation on test classification: The new test calls git ls-files as a subprocess, making it behave more like an integration/system test than a pure unit test. The file is tests/unit/… and the project has a pytest -m integration marker. This isn't a blocker — the existing tests in the same file that check .gitignore content also implicitly depend on the filesystem — but if the project enforces strict unit/integration separation in CI time budgets, it's worth noting. Consider adding @pytest.mark.integration if that matters here.

---

Potential Issues

• None blocking. The root cause (gitlink inadvertently tracked by a Claude agent worktree) is cleanly addressed.
• The cwd=ROOT in subprocess.run depends on ROOT being the actual repo root. Confirm ROOT is defined as Path(__file__).resolve().parents[N] pointing to the repo root (not just the tests/ directory) — if that's already true for the rest of the suite it's fine.

---

Security

No concerns. Removing a dangling gitlink has no security surface. The gitignore entry reduces accidental secret exposure from ephemeral agent worktrees.

---

Commit Convention

fix(ci): remove orphaned agent worktree gitlink — matches the enforced <type>(<scope>): <subject> format. ✓

---

Summary

Approve. This is a minimal, correct fix with a solid regression test. The only non-blocking suggestion is to consider whether the new test warrants an @pytest.mark.integration marker given it shells out to git. Everything else is clean and follows project conventions.

[github-actions]

Coverage report

This PR does not seem to contain any modification to coverable code.

[github-actions]

🧪 Integration Test Results

Test Suite	Status
Month 1 Test Results	✅ Passed
Month 2 Test Results	✅ Passed
Month 3 Test Results	✅ Passed
Critical Path	✅ Passed

Overall: ✅ All tests passed!

View detailed test reports

• Month 1 Test Report
• Month 2 Test Report
• Month 3 Test Report

[github-actions]

🧪 Integration Test Results

Test Suite	Status
Month 1 Test Results	✅ Passed
Month 2 Test Results	✅ Passed
Month 3 Test Results	✅ Passed
Critical Path	✅ Passed

Overall: ✅ All tests passed!

View detailed test reports

• Month 1 Test Report
• Month 2 Test Report
• Month 3 Test Report

[claude]

PR Review — fix(ci): remove orphaned agent worktree gitlink

Overall this is a clean, well-scoped fix with good regression coverage. The two root causes are correctly identified and the remediation is sound. Notes below from most to least significant.

---

Gitlink removal + .gitignore guard ✅

Straightforward. Deleting the orphaned submodule entry and adding /.claude/worktrees/ to .gitignore is the right permanent guard. The custody proof in the PR description (reachable ancestor commit, empty checkout directory) is the right level of due diligence for a deletion.

---

Python heredoc replaces sed for badge injection ✅

This is the substantive fix. The root bug is classic: sed treats & in the replacement string as "insert the matched text", so any & in $SANDBOX_URL (e.g. ?ref=main&devcontainer_path=...) gets silently mangled. The Python rewrite avoids that entirely.

Specifics that look good:

• The heredoc delimiter is single-quoted (<<'PY'), so the Python source is not subject to shell expansion — os.environ['STYLE'] is literal Python, not a shell substitution.
• Idempotency guard (if updated != text) avoids spurious git diffs on re-runs.
• raise SystemExit(...) on mismatched markers is appropriately fail-fast.
• The split(marker_start, 1) / split(marker_end, 1) pair handles arbitrary whitespace between markers correctly.

One edge case worth noting (low risk):
If marker_end appears before marker_start in a malformed README, the code would detect marker_start is present, find marker_end in the remainder, and produce garbled output instead of erroring. Given this file is owned by the repo and seeded by the script itself, this is unlikely in practice — but an additional guard would make the error surface cleaner:

if marker_start in text:
    if marker_end not in text:
        raise SystemExit("README has an opening demo marker without a closing marker")
    # also: if text.index(marker_end) < text.index(marker_start): raise ...

Not a blocker, just a note for future robustness.

---

PR metadata alignment ✅

• commit-message and title now follow feat(demo): ... — valid conventional commit with scope.
• Branch maintenance/chore/demo-sandbox-badge matches the required lifecycle/type/component pattern from the branch naming policy.

Both corrections are necessary; the old values (feat: add "Try Demo"... and demo/add-sandbox-badge) would have been caught by the policy gate.

---

Workflow registry hash update — flag for awareness

The diff updates hashes for both demo-sandbox-reusable.yml and demo-deployment.yml, but no diff for demo-deployment.yml itself is visible in this PR. The new test assertion (assert "- .github/workflows/demo-sandbox-reusable.yml" in workflow) implies demo-deployment.yml received a paths: filter addition at some point. If that change landed on main before this PR was opened (i.e., in the #503 push being remediated), the hash update here is correct catch-up. Just worth confirming the hash 58606e76... is what sha256sum .github/workflows/demo-deployment.yml produces on the post-merge tree.

---

Test coverage ✅

Both new tests are well-designed:

1. test_agent_worktrees_are_local_runtime_state — uses git ls-files --stage directly against the repo, which is the authoritative check (not just .gitignore content). Correct approach.

2. test_demo_badge_injection_preserves_query_parameters_and_is_idempotent — extracts the actual script from the parsed workflow YAML and runs it with bash -eu -o pipefail. This is the right level of integration: it tests the real artifact, not a mocked version. The double-run idempotency check and the URL-preservation assertion cover both regressions the PR targets.

The test_demo_push_and_manual_inputs_preserve_reusable_workflow_types addition of assert "- .github/workflows/demo-sandbox-reusable.yml" in workflow is a good contract check that the deployment workflow's path filter covers the reusable workflow.

---

Summary

Area	Verdict
Gitlink removal	✅ Correct
.gitignore guard	✅ Correct
Python badge injection	✅ Correct, one minor edge case noted
PR metadata (commit msg, branch)	✅ Policy-compliant
Registry hash updates	Verify demo-deployment.yml hash externally
Regression tests	✅ Well-structured end-to-end coverage

Approved with the registry hash note as a low-priority follow-up verification.

[github-actions]

🧪 Integration Test Results

Test Suite	Status
Month 1 Test Results	✅ Passed
Month 2 Test Results	✅ Passed
Month 3 Test Results	✅ Passed
Critical Path	✅ Passed

Overall: ✅ All tests passed!

View detailed test reports

• Month 1 Test Report
• Month 2 Test Report
• Month 3 Test Report

[claude]

Code Review — PR #504 fix(ci): remove orphaned agent worktree gitlink

Overall this is a clean, well-scoped fix. The PR description is thorough, the commits are logically separated, and the regression tests directly target the failure modes. A few observations below.

---

Gitlink removal + .gitignore guard

Both changes are correct and necessary together. Removing the tracked entry without the .gitignore guard would leave the door open for the same class of failure. Using the root-anchored form /.claude/worktrees/ (rather than .claude/worktrees/) is the right choice — it avoids matching nested paths that happen to share the name.

---

Python heredoc in demo-sandbox-reusable.yml

The replacement of sed -i with embedded Python is the right call. The original sed expression broke on & in the Codespaces URL because sed treats & in the replacement as the matched string. The Python script handles arbitrary URL characters safely.

One edge case not tested: what happens when SANDBOX_URL or STYLE are empty strings? os.environ['KEY'] raises KeyError (exit 1), which is actually the correct behavior in a CI context — you want hard failure, not a silently malformed badge. No change needed, just worth knowing.

Heredoc quoting: <<'PY' (single-quoted) correctly prevents shell variable expansion inside the Python source. If it were <<PY (unquoted), ${{ env.SANDBOX_URL }} passed in from the workflow env would be fine (it's not in the heredoc anyway), but os.environ references would be safe regardless. The choice is correct.

Python indentation: the 8-space indent visible in the YAML diff is the YAML indentation, not Python-level indentation. GitHub Actions strips the common leading whitespace from run: blocks, so the Python code arrives at stdin with zero leading spaces — valid at module level. Actionlint passing confirms this.

Idiomatic nit: raise SystemExit("message") on the unclosed-marker path prints the message to stderr and exits 1. That's the right behavior for a CI script. No change needed.

---

Trigger path addition in demo-deployment.yml

- .github/workflows/demo-sandbox-reusable.yml

Correct. Without this, a change to the reusable workflow logic (like this PR's badge-script fix) wouldn't trigger the calling workflow on push to main. The addition closes that gap.

---

Branch and commit message conformance

Field	Before	After
Branch	demo/add-sandbox-badge	maintenance/chore/demo-sandbox-badge
Commit message	feat: add "Try Demo" sandbox badge to README	feat(demo): add Try Demo sandbox badge
PR title	Add "Try Demo" sandbox badge	feat(demo): add Try Demo sandbox badge

All three now conform to the repo's branch-naming policy and conventional-commit convention. The old branch name (demo/...) doesn't match any allowed lifecycle prefix.

---

Tests

test_agent_worktrees_are_local_runtime_state — good use of git ls-files --stage to assert the tracked state rather than just checking .gitignore. Tests both the prevention (.gitignore) and the cure (no staged entries).

test_demo_badge_injection_preserves_query_parameters_and_is_idempotent — this is the strongest test in the set. It extracts the actual run: script from the workflow YAML and executes it, so it tests the real artifact rather than a test-side reimplementation. Running it twice and asserting byte-identical output is the right way to prove idempotency.

test_demo_push_and_manual_inputs_preserve_reusable_workflow_types — the added assertion for the new path filter entry is a lightweight guard against accidental removal.

Missing coverage (minor, not a blocker): the unclosed-marker error path (raise SystemExit(...)) has no test. A future test_demo_badge_injection_raises_on_unclosed_marker would complete the contract, but it's out of scope for a fix PR.

---

Workflow registry

Both SHA-256 entries updated for demo-deployment.yml and demo-sandbox-reusable.yml. The PR description states the registry hash matches the changed workflow — this is consistent with the repo's registry maintenance pattern.

---

Summary

• No bugs found in the changes.
• No security issues introduced (the Python heredoc is correctly isolated from shell expansion).
• Test coverage adequately captures the failure modes fixed here.
• All policy conformance items (branch name, commit message, PR title, SHA pinning) are correct.

Approved. The unclosed-marker test gap is a minor future improvement, not a blocker.

[github-actions]

🧪 Integration Test Results

Test Suite	Status
Month 1 Test Results	✅ Passed
Month 2 Test Results	✅ Passed
Month 3 Test Results	✅ Passed
Critical Path	✅ Passed

Overall: ✅ All tests passed!

View detailed test reports

• Month 1 Test Report
• Month 2 Test Report
• Month 3 Test Report

[github-actions]

🧪 Integration Test Results

Test Suite	Status
Month 1 Test Results	✅ Passed
Month 2 Test Results	✅ Passed
Month 3 Test Results	✅ Passed
Critical Path	✅ Passed

Overall: ✅ All tests passed!

View detailed test reports

• Month 1 Test Report
• Month 2 Test Report
• Month 3 Test Report

[claude]

Code Review: fix(ci) remove orphaned agent worktree gitlink

Overall assessment: Solid, focused fix. The three root problems (orphaned gitlink, sed ampersand corruption, durable URL pointing at a runner-local file) are all real bugs, the remedies are correct, and the regression suite is proportionate.

---

Overview

This PR addresses two CI failures that appeared after #503 merged:

1. An orphaned gitlink that caused actions/checkout cleanup to fail before Semantic Release could run.
2. A broken Demo sandbox contract from three issues: sed corrupting ampersands in the Codespaces URL, a badge PR branch name violating the org branch-naming policy, and the Codespaces deep link pointing at a devcontainer file that only existed on the ephemeral runner.

---

What works well

Gitlink removal and .gitignore guard - Removing the gitlink is correct. Adding /.claude/worktrees/ to .gitignore is the right preventive step. The test test_agent_worktrees_are_local_runtime_state uses git ls-files --stage to assert no tracked entries remain, which is more durable than just checking .gitignore content.

sed to Python for badge injection - sed treats & as a backreference to the full match in replacement strings, a notorious footgun when URLs appear in substitutions. The Python replacement handles all three README states (existing markers, existing H1 heading, bare file). The updated != text guard ensures idempotency at the write level.

Codespaces URL fix - The original code created a devcontainer on the runner and embedded its path in a durable URL that would be missing every time the URL was followed. The new approach is correct: check for a repo-committed devcontainer and only append devcontainer_path if it exists.

Trigger path coverage - Adding demo-sandbox-reusable.yml to demo-deployment.yml push path filters means changes to the reusable workflow now trigger the caller. Correct and previously missing.

Test design - The two new integration tests extract and execute the actual shell/Python scripts from the workflow YAML, testing the deployed artifact rather than a parallel reimplementation. This is the right approach for workflow policy contracts.

Registry hashes and branch naming - SHA-256 entries updated correctly. Branch name changed to maintenance/chore/demo-sandbox-badge, satisfying the documented maintenance// convention.

---

Issues and suggestions

Minor: missing error-path test for malformed markers - The Python script raises SystemExit if DEMO:START exists but DEMO:END does not. This branch is untested. A short parametrised case would make the contract explicit. Not blocking.

Minor: os.environ access without descriptive guards - If STYLE or SANDBOX_URL are absent the script raises a bare KeyError. An explicit SystemExit with a human-readable message would improve debuggability.

Minor: README badge URL lacks devcontainer path - The badge in README.md links to codespaces.new/organvm/dot-github--theoria?ref=main without devcontainer_path. This is correct now (no committed devcontainer exists), but if one is added later the badge will not auto-update. Worth noting as a manual follow-up.

Nit: subprocess.run error surface in the gitlink test - capture_output=True with check=True means a git environment failure surfaces as CalledProcessError rather than a readable assertion message. The test is correct; this is just a failure-mode observation.

---

Security

• SANDBOX_URL is written into README.md but is constructed from github.repository and job outputs, not from user-controlled workflow_dispatch inputs. Injection risk is negligible.
• secrets.GITHUB_TOKEN usage in the create-pull-request step is standard.
• No new external network calls or secret exposures introduced.

---

Test coverage - Five new or expanded tests: test_agent_worktrees_are_local_runtime_state (gitlink regression), test_demo_push_and_manual_inputs_preserve_reusable_workflow_types (reusable workflow path trigger), test_demo_badge_injection_preserves_query_parameters_and_is_idempotent (ampersand preservation and byte-identical rerun), test_codespaces_url_only_names_repository_owned_devcontainers (no runner-local paths in durable URLs), and test_repo_owned_pr_producers_emit_compliant_metadata (gains demo-sandbox-reusable entry). All cover the exact failure modes in the PR body.

---

Verdict: Approve with the minor suggestions noted for follow-up. The core fixes are correct, the sed-to-Python migration eliminates a well-known shell hazard, and the regression tests are well-designed. The missing error-path test and env-var messaging are cosmetic and can be addressed in a follow-up.

[claude]

Code Review — PR #504: fix(ci): remove orphaned agent worktree gitlink

Overview

This PR addresses two distinct failures exposed after #503 landed:

1. An orphaned .claude/worktrees/ gitlink (mode 160000) that blocked actions/checkout cleanup before Semantic Release could run.
2. A broken Demo sandbox contract — sed-corrupted Codespaces URLs, a runner-only devcontainer path embedded in a durable link, and non-compliant PR metadata.

Both fixes are root-cause repairs, not workarounds. The approach is sound.

---

Gitlink removal (.claude/worktrees/agent-a9ca0d473436e9943)

Correct. Deleting the tracked gitlink and adding /.claude/worktrees/ to .gitignore closes the failure loop cleanly. The custody proof in the PR description (confirming the detached target is reachable on the remote and is an ancestor of origin/main) is a good audit trail.

The regression test test_agent_worktrees_are_local_runtime_state verifies both the .gitignore entry and that no .claude/worktrees paths are staged, which is exactly the right pair of assertions.

---

Codespaces URL — git cat-file approach

Well chosen. Using git cat-file -e "HEAD:.devcontainer/demo/devcontainer.json" to determine repository-owned presence (rather than checking the filesystem with -f) is semantically precise: it tests what is committed, not what may have been written to the runner during an earlier step. The 2>/dev/null suppression is correct.

The three-state test (no file → untracked file → committed file) is exactly the regression coverage needed and is the most valuable new test in this PR.

---

Badge injection — sed → Python

Clear improvement. The sed & expansion bug is a real and notorious footgun; replacing it with Python string operations eliminates the entire class of issue. A few observations:

• UTF-8 encoding is explicit on both read and write — good.
• Idempotency guard (if updated != text) avoids unnecessary writes — good.
• Error on unclosed marker (raise SystemExit(...)) is appropriate; silent corruption would be worse.
• The f-string interpolation of os.environ['SANDBOX_URL'] is safe here since it feeds into a Python string, not a shell command.

Minor note: The embedded heredoc Python pattern (python3 - <<'PY') relies on Python 3 being on the runner PATH. GitHub-hosted runners have Python 3 available, but if this ever runs on a self-hosted runner it should be documented as a runtime requirement. This is low risk for this project.

The idempotency test (test_demo_badge_injection_preserves_query_parameters_and_is_idempotent) correctly extracts the step's run block from the parsed YAML and runs it twice, asserting byte-identical output. This is more reliable than mocking.

---

PR metadata compliance

The new branch (maintenance/chore/demo-sandbox-badge) and commit message (feat(workflows): add Try Demo sandbox badge) comply with the <lifecycle>/<type>/<component> branch convention and conventional commit format required by the project. The previous values (demo/add-sandbox-badge, feat: add "Try Demo" sandbox badge to README) did not conform.

---

Push trigger addition

Adding .github/workflows/demo-sandbox-reusable.yml to the push.paths filter in demo-deployment.yml is correct — previously, changes to the reusable workflow itself would not trigger the calling workflow. The new test assertion (assert "- .github/workflows/demo-sandbox-reusable.yml" in workflow) locks this in.

---

Workflow registry hashes

Both updated SHA-256 values correspond to the modified workflow files. This is consistent with the registry contract.

---

Summary

Area	Assessment
Gitlink removal	✅ Correct, complete, tested
Codespaces URL fix	✅ Semantically precise, regressed
Badge injection (sed → Python)	✅ Robust fix, idempotency tested
PR metadata compliance	✅ Now conforms to conventions
Push trigger coverage	✅ Correct, locked by test
Registry hashes	✅ Updated
Test quality	✅ Integration-style, real execution

No blocking issues. The PR is well-scoped, all changes have corresponding regression tests, and the custody proofs in the description are thorough. Ready to merge.

---

Reviewed by Claude Sonnet 4.6

[4444J99]

Post-merge custody receipt

• Merge-queue synthetic head and resulting main: c1085c2
• Queue-required CI, Docker, and Integration runs: all green.
• Exact-main Demo Sandbox: green, including detect, deploy, idempotent badge, and registry jobs: https://github.com/organvm/dot-github--theoria/actions/runs/29204437947
• Exact-main Advanced CI: green: https://github.com/organvm/dot-github--theoria/actions/runs/29204437834
• Every exact-main push workflow that ran completed successfully.

Semantic Release was not manually dispatched because its workflow can publish releases, tags, packages, and images; that public mutation remains outside this closeout's authority. The orphan-gitlink checkout failure is independently closed by successful checkout/post-checkout across the exact-main workflow set.

Residual external gate: repository Actions policy still forbids Actions-created pull requests. Ordinary Demo pushes are now idempotent and green; a future genuine badge-byte change would require the repository owner either to enable Actions PR creation in repository settings or provide an approved GitHub App/PAT path. No remote branch deletion was armed.