Skip to content

fix: the host clones the constitution, so the gate needs no warm cache - #26

Merged
fatherlinux merged 4 commits into
mainfrom
fix/constitution-cloned-by-host
Nov 6, 2026
Merged

fatherlinux merged 4 commits into
mainfrom
fix/constitution-cloned-by-host

Conversation

@fatherlinux

Copy link
Copy Markdown
Member

On a gateway seat, the constitution gate could only pass if the cache volume already held the pinned tag. validate clones crunchtools/constitution from inside the gate container. There the clone goes through a CONNECT proxy that refuses github.com, because the route to GitHub is a git insteadOf in the host's git config, which the container never reads. This showed up on developer3 while working claude-agent#9.

bin/sdlc now clones the pinned tag with the host's git, once per tag, under ~/.cache/python-sdlc/constitution/. It mounts that checkout read-only at /cache/constitution/<tag>, the path validate already checks. The image doesn't change, and no git config or credentials go into any container. The clone happens before any lane forks, so lanes never race. If the host clone fails, behaviour is unchanged: validate tries its own clone and reports a 2.

This releases 0.5.1. Consumers pick it up on the next bump.

Verified on developer3:

  • With an empty cache volume, the constitution check passed against claude-agent. Before this change it was COULD NOT RUN.
  • With an unwritable host cache, it falls back to the old path and exits 2.
  • tests/test_host_contract.sh has 0 failures.
  • shellcheck didn't run locally because docker.io is refused through the gateway, so it's left to container.yml.

🤖 Generated with Claude Code

validate cloned crunchtools/constitution from inside the gate container.
On a gateway seat that clone goes through a CONNECT proxy that refuses
github.com; the route to GitHub is a git insteadOf in the host's config,
which the container never reads. A warm cache volume hid it; an empty one
was a gate that could not run (claude-agent#9, developer3).

bin/sdlc now clones the pinned tag with the host's git, once per tag under
~/.cache/python-sdlc/constitution, and mounts it read-only where validate
already looks. No git config or credentials cross into the container. A
failed host clone changes nothing: validate tries its own and reports a 2.

Release 0.5.1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gatehouse found 1 issues (1 medium)

Full review.

2 finding(s) dropped: their evidence is not in the diff.

Comment thread bin/sdlc
}' "$_manifest")
[ -n "$_tag" ] || return 0
_dir=${XDG_CACHE_HOME:-$HOME/.cache}/python-sdlc/constitution/$_tag
if [ ! -f "$_dir/constitution.md" ]; then

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MEDIUM (Bug Hunter): Concurrent sdlc invocations can delete or interfere with each other's in-progress clone. Both can observe the missing file, then one invocation's rm -rf can remove the directory while the other is cloning; a failed clone can likewise remove the other invocation's checkout. On seats where the container cannot reach GitHub, this can make the constitution gate fail intermittently.

Suggestion: Serialize cache population with a per-tag lock, or clone into a unique temporary directory and atomically publish it without deleting a directory another process may be populating.

Evidence:

if [ ! -f "$_dir/constitution.md" ]; then
  rm -rf "$_dir"
  mkdir -p "$_dir" 2>/dev/null || return 0
  git clone --quiet --depth 1 --branch "$_tag" \
      https://github.com/crunchtools/constitution "$_dir" >/dev/null 2>&1 \
    || { rm -rf "$_dir"; return 0; }
fi

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed in 0e58fd4

Each run now clones into its own mktemp -d directory and publishes it with ln -sn, so only one run can win. The loser deletes only its own copy and uses the winner's. Nothing removes a shared path anymore. I tested three runs started at once on an empty cache: all three passed and left one checkout and one link.

…rm -rf

Two sdlc runs on one tag could delete each other's clone in progress.
Each now clones into its own mktemp directory and publishes it with
ln -sn; the loser removes only its own copy and uses the winner's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gatehouse found 2 issues (2 medium)

Reviewed 1 commit since 0f993d1 (incremental).

2 finding(s) dropped: their evidence is not in the diff.

Comment thread bin/sdlc
_dir=$_root/$_tag
if [ ! -f "$_dir/constitution.md" ]; then
mkdir -p "$_root" 2>/dev/null || return 0
_own=$(mktemp -d "$_root/.$_tag.XXXXXX" 2>/dev/null) || return 0

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MEDIUM (Performance Check): Concurrent runs that need the same uncached tag each create a temporary directory and clone the full shallow repository before racing to publish it. The losing run then deletes its clone, so concurrent runs cause redundant network and disk work.

Suggestion: Serialize cache population per tag, then recheck whether the cache exists before cloning. Alternatively, use a mechanism that lets later runs wait for and reuse the in-progress clone.

Evidence:

_own=$(mktemp -d "$_root/.$_tag.XXXXXX" 2>/dev/null) || return 0
git clone --quiet --depth 1 --branch "$_tag" \
    https://github.com/crunchtools/constitution "$_own" >/dev/null 2>&1 \
  || { rm -rf "$_own"; return 0; }
ln -sn "${_own##*/}" "$_dir" 2>/dev/null || rm -rf "$_own"

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not a bug: the duplicate clone only happens when two runs start on a cold cache for a tag nobody has fetched, which is about once per seat per constitution release. It costs one --depth 1 clone of a small repo, about a second, and the losing copy is deleted at once. A lock to avoid that would mean a waiter, a timeout and stale-lock handling in a POSIX-only launcher. That's more failure modes than the second it saves, so I'm keeping the race lock-free and correct instead.

Comment thread bin/sdlc
_dir=$_root/$_tag
if [ ! -f "$_dir/constitution.md" ]; then
mkdir -p "$_root" 2>/dev/null || return 0
_own=$(mktemp -d "$_root/.$_tag.XXXXXX" 2>/dev/null) || return 0

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MEDIUM (Test Coverage): The new concurrent cache-publication logic has no corresponding test coverage in the changes shown. Its behavior depends on two runs racing to publish the symlink, including the losing run cleaning up only its own clone and then using the winner's checkout.

Suggestion: Add a test that runs two cache population attempts for the same tag concurrently and verifies that one checkout is published, the loser does not remove the winner's data, and both runs can use the published constitution. Also cover clone failure cleanup.

Evidence:

_own=$(mktemp -d "$_root/.$_tag.XXXXXX" 2>/dev/null) || return 0
git clone --quiet --depth 1 --branch "$_tag" \
    https://github.com/crunchtools/constitution "$_own" >/dev/null 2>&1 \
  || { rm -rf "$_own"; return 0; }
ln -sn "${_own##*/}" "$_dir" 2>/dev/null || rm -rf "$_own"
[ -f "$_dir/constitution.md" ] || return 0

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed in ccaf13b

tests/test_host_contract.sh now starts three bin/sdlc runs at once against an offline git whose clone is slow. It asserts one checkout, one link to it and no stray copies. It passes with ln -sn, and it fails against the earlier ln -s bug, which left 3 directories and 2 nested links.

Three bin/sdlc runs start at once against an offline git whose clone is
slow. Passes with ln -sn; fails on the ln -s that nested the losers' links.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gatehouse found 1 issues (1 medium)

Reviewed 1 commit since 0e58fd4 (incremental).

2 finding(s) dropped: their evidence is not in the diff.

esac
EOF
chmod +x "$CLONESHIM/git"
for _ in 1 2 3; do

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MEDIUM (Test Coverage): The concurrency test verifies the final cache layout but never verifies that all three hooks-installed runs succeeded. A run that fails during a clone race can be silently ignored as long as another run leaves the expected checkout and link, so the test can pass despite broken behavior for concurrent callers.

Suggestion: Capture each background process ID and check the result of each corresponding wait; fail the test if any invocation exits nonzero.

Evidence:

for _ in 1 2 3; do
  PATH="$CLONESHIM" XDG_CACHE_HOME="$CLONECACHE" sh bin/sdlc hooks-installed >/dev/null 2>&1 &
done
wait

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fixed in b6fc416

Each background run is now waited on by its PID, and its exit status is compared with a baseline run that had a cache to itself. Comparing with a baseline rather than 0 is deliberate: hooks-installed legitimately fails on a checkout with no pre-push hook, as in CI. A run whose exit differs from the baseline fails the test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gatehouse found no issues.

Reviewed 1 commit since ccaf13b (incremental).

@fatherlinux
fatherlinux merged commit 90279b2 into main Nov 6, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant