Skip to content

docs(state): drop stale convergence-branch claim, fix dead issue citation - #36

Merged
forkwright merged 1 commit into
mainfrom
docs/fix-current-state-and-adapter-citation
Sep 3, 2026
Merged

docs(state): drop stale convergence-branch claim, fix dead issue citation#36
forkwright merged 1 commit into
mainfrom
docs/fix-current-state-and-adapter-citation

Conversation

@forkwright

Copy link
Copy Markdown
Owner

Finding

Two false assertions in this repo's own documentation:

  1. _llm/current_state.toml's contract_status claims the breaking v1 invocation/supervisor contract is "implemented on the convergence branch and awaits exact-head hosted compilation and gate evidence." No convergence branch exists (gh api repos/forkwright/epitelesis/branches lists only main), and the contract has been shipped and enforced since v0.3.0.

  2. hybrid-gate-adapter.yml's timeout-minutes: 90 comment cites a kanon issue number that does not exist in that repo today. The number it actually meant is forkwright/.github#45, a merged PR that raised the fleet reusable's full_gate_timeout_minutes default to 90.

Evidence

  • gh api repos/forkwright/epitelesis/branches --jq '.[].name'main only.
  • CHANGELOG.md v0.3.0 entry (2026-07-28): "⚠ BREAKING CHANGES: enforce the v1 invocation lifecycle contract (feat!: enforce the v1 invocation lifecycle contract #17)".
  • gh pr view 34 --repo forkwright/epitelesis --json statusCheckRollup and the same for PR ci: adopt the fleet release-PR healer #35: both show gate / full-gate-build and gate / gate-attestation green, merged onto main on 2026-08-25/26.
  • gh issue list --repo forkwright/kanon --state all --limit 1 → kanon's highest issue number is far below the one cited in the adapter comment; the cited number does not resolve (gh issue view on it 404s).
  • gh pr view 45 --repo forkwright/.github --json title,state,mergedAt → merged, "ci(gate): raise the default full-gate timeout to 90m fleet-wide" — this is what the comment actually meant to cite.

Why this matters

current_state.toml is declared as this repo's canonical machine-readable state doc (_llm/current_state.toml, listed in its own source_docs). An agent or tool reading it for the contract's real status is told to look for a branch that doesn't exist and to wait for evidence that already landed five weeks ago — the opposite of what the file exists to prevent.

The dead issue citation in the workflow comment sends the next reader chasing a number that resolves to nothing, right at the point where the comment is explaining why a value needs manual upkeep at all (this job is a hand-copy of the fleet reusable, not a workflow_call consumer of it, so it never inherits the reusable's own default and must be kept in sync by hand -- that fact was missing from the original comment too).

Desired correction

  • current_state.toml: state that the contract is implemented and enforced on main, verified by the hosted full gate, and refresh updated. Done in this PR.
  • hybrid-gate-adapter.yml: point the citation at the PR that actually raised the default (forkwright/.github#45), and state plainly that this file hand-copies the fleet reusable rather than calling it. Done in this PR.

Not done in this PR, reported separately: the deeper substrate-drift this hand-copy represents -- replacing the ~185-line duplicate with a direct uses: forkwright/.github/.github/workflows/hybrid-gate.yml@main call, matching forkwright/zetesis's pattern -- is out of scope here. Verified via forkwright/zetesis's live branch protection (gh api repos/forkwright/zetesis/branches/main/protection), the fleet reusable's own aggregation job is named gate, so a direct call would produce required-check context gate / gate, not this repo's current gate / gate-attestation (confirmed via this repo's own branch protection). That rename would break branch protection until coordinated with a protection update, which is out of this lane's authority. Flagged inline in the workflow comment and reported to the orchestrator.

Done when: current_state.toml and the workflow comment both state only claims that are true today, and neither cites a resource that doesn't exist.

…tion

current_state.toml still said the v1 invocation/supervisor contract was implemented on a convergence branch awaiting hosted gate evidence. That branch never existed on this repo -- only main does -- and the contract shipped as a breaking change in v0.3.0 with real hosted gate evidence on main since (green on the two most recent merged PRs). The stale claim was the only instance of this false premise in the tree.

hybrid-gate-adapter.yml's timeout comment cited an issue number that does not exist in the kanon repo (which tops out far below it). The real justification is a merged first-party PR that raised the fleet reusable's timeout input default to 90 -- this file hand-copies that reusable rather than calling it, so it never inherited the new default and had to hardcode it. Documented the hand-copy relationship explicitly, since that is the reason this timeout needs manual upkeep at all, and flagged why the copy cannot simply become a direct reusable call: the fleet reusable's aggregation job is named differently than this file's local one, so switching would rename this repo's required status check and break branch protection until that rename is coordinated separately.
@forkwright
forkwright merged commit d6133f7 into main Sep 3, 2026
7 checks passed
@forkwright
forkwright deleted the docs/fix-current-state-and-adapter-citation branch September 3, 2026 14:03
forkwright pushed a commit that referenced this pull request Sep 3, 2026
🤖 I have created a release *beep* *boop*
---


##
[0.4.1](v0.4.0...v0.4.1)
(2026-09-03)


### Documentation

* **state:** drop stale convergence-branch claim, fix dead issue
citation ([#36](#36))
([d6133f7](d6133f7))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
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