docs(track-a): enforce canonical runtime rules for research agents

[blakinio]

Result

Enforces the final Track A canonical-live runtime rules at the normal research-agent entrypoints and adds deterministic CI enforcement for future Track A task/runtime changes.

Universal worker admission

Every Track A (official-client-re) worker must read the current runtime-admission contract and persist the complete admission record at task claim/resume/checkpoint before substantial Track A work. Static/no-runtime workers use runtime_access: none; live access must be re-admitted before the first runtime operation and after any material authority/identity change.

Allowed runtime classes are exactly:

• none
• read_only
• ephemeral_isolated
• canonical_reuse_or_mutation
• canonical_bootstrap
• canonical_rebind

The universally mandatory docs/agents/README.md, nested Track A agent instructions, and docs/agents/prompts/OTCLIENT_TIBIA_RE_CANONICAL.md route workers through docs/agents/contracts/TRACK_A_RUNTIME_AGENT_ADMISSION_V1.md.

read_only is live observation only and fails closed unless non-invasiveness, an explicit non-conflicting target/namespace/ownership boundary, and target_uniqueness: PROVEN are current. Static/artifact research uses none.

Canonical mutation is fail-closed and requires current-task ownership, the authoritative canonical namespace, current Gate A, any required reviewed generation rebind, Gate B, target uniqueness, positive equal current/registration lease generations after rebind, and the final PR #321 cancellation-safe whole-lifetime supervisor. Missing registration routes only to bootstrap; generation mismatch routes only to reviewed rebind; manual registration editing is forbidden; ephemeral runtimes cannot use or alias the canonical namespace.

Current non-claims remain :98 = UNKNOWN, 6082 = UNKNOWN, PID/session = NOT_REGISTERED. Exact client fence remains 15.32.df7b29 / 51965216 / e6c244bd39fe2e0632f6f000efd3147164696efa8e901718668e0442325ff7fe.

CI enforcement

.github/workflows/track-a-agent-runtime-governance.yml runs on the universal/nested agent entrypoints, Track A contracts/prompts/active tasks, and runtime-sensitive official-client paths. The policy audit checks the PR diff against the base SHA and passes the current PR head branch into the admission validator.

Added/modified Track A tasks must carry the complete admission record. Runtime-sensitive Track A implementation changes require a changed active Track A task whose declared branch matches the current PR head; an unrelated/decoy Track A task cannot satisfy the gate. Fresh behavior tests cover positive and negative runtime classes, generation/owner/namespace failures, read-only ambiguity and branch mismatch.

This remains migrate-on-next-checkpoint enforcement: historical active tasks are not mass rewritten, but the next claim/resume/checkpoint must persist the admission record before substantial Track A work.

Independent review findings repaired

• end-to-end changed-task enforcement wired to base SHA and runtime-sensitive path families;
• exact native-Linux client fence made mandatory;
• authorized canonical mutation requires positive equal controller/registration generations after rebind;
• canonical access bound to runtime_owner_task == task_id and authoritative canonical namespace;
• ephemeral namespace cannot equal/alias canonical namespace;
• universal entrypoint enforced through root-mandatory docs/agents/README.md;
• README ownership recorded in task lock metadata;
• admission persistence moved to claim/resume/checkpoint (none for static workers);
• read-only live observation requires proven uniqueness/non-conflicting ownership/namespace;
• runtime-sensitive admission task is bound to current PR head branch.

Safety / ownership

This task itself is runtime_access: none. No Tibia client launch/login/input/attach/signal/runtime mutation, credentials, canonical runtime-state access, PR #303 runtime-owned surface, Track B mutation, or owner-funded Codex/OpenAI API quota is involved. docs/agents/CHANGELOG.md remains untouched because open coordinator PR #300 currently changes it.

Current code/policy head: 03388d366a91d28fb455ab64bc4bc08d4fd78ca4. Exact-head Track A governance audit and repository CI are the current Draft promotion gates. After they pass with zero unresolved material review findings, the task will be released, PR marked Ready, the new protected Ready-state required-check generation must pass, then #324 will be merged and archived in a separate closeout PR.

Task: OTC-20260816-track-a-agent-runtime-governance.

[blakinio]

Independent promotion review — material fixes required before merge:

1. Deterministic enforcement is not currently wired end-to-end. .github/scripts/test_track_a_agent_runtime_governance.py implements audit_changed_tasks(--changed-from) and sensitive-path detection, but .github/workflows/track-a-agent-runtime-governance.yml invokes the script without --changed-from and its paths: filter omits the general docs/agents/tasks/active/** plus the runtime-sensitive prefixes that the script is supposed to police. A future Track A runtime-script/workflow/tool change can therefore bypass the admission-record audit entirely. Fix by triggering on the guarded path families, checking out enough base history, and passing the PR base SHA (with a safe workflow_dispatch branch).

2. The task acceptance says the root agent entrypoint must explicitly require Track A runtime admission, and AGENTS.md is declared owned, but the PR currently changes only docs/agents/AGENTS.md. Root AGENTS.md currently contains only generic instruction-order/startup rules; add a narrow explicit Track A admission pointer there or revise the acceptance/ownership with equivalent directly enforced root behavior.

3. Ownership record is inconsistent with the actual diff: the PR changes docs/agents/AGENTS.md and creates docs/agents/contracts/TRACK_A_RUNTIME_AGENT_ADMISSION_V1.md, but neither appears in owned_paths; conversely root AGENTS.md and docs/agents/TIBIA_RESEARCH_TRACKS.md are declared owned but not currently changed. Reconcile owned_paths before further edits/merge.

Do not mark Ready/merge until these are repaired, exact-head deterministic audit + repository CI are green, and the task is released for independent promotion review.

[blakinio]

Follow-up promotion review: finding #2 is not satisfied by merely revising the task acceptance wording. Root AGENTS.md is the universal repository entrypoint and currently does not require docs/agents/AGENTS.md or TRACK_A_RUNTIME_AGENT_ADMISSION_V1.md for Track A runtime work; its mandatory startup reads docs/agents/README.md and general indexes, while nested docs/agents/AGENTS.md is not automatically the nearest instruction file for .github/**, tools/**, or other runtime surfaces. The canonical wrapper also is not guaranteed to be the entrypoint for every future researcher. To make the owner's rule unavoidable before live operations (not merely CI-enforced after a code change), add a narrow root AGENTS.md Track A pointer requiring docs/agents/TIBIA_RESEARCH_TRACKS.md + docs/agents/contracts/TRACK_A_RUNTIME_AGENT_ADMISSION_V1.md and runtime-access classification before any official-client runtime operation. Re-add root AGENTS.md to owned paths and to deterministic audit markers. This is a merge blocker for the stated goal that all Track A agents follow the rules.

[blakinio]

Additional material validator bypass found during independent audit: validate_track_a_task() does not validate canonical_lease_generation / registration_lease_generation values for authorized canonical reuse. Today runtime_access=canonical_reuse_or_mutation, mutation_authorized=true, both generation fields=UNKNOWN, gate_a=PASS, generation_rebind=NOT_APPLICABLE, gate_b=PASS, target_uniqueness=PROVEN can pass even though the contract requires current controller-generation binding (and rebind on mismatch) before Gate B/mutation. Tighten the validator: for mutation_authorized=true require both generation fields to be positive integers and equal after any rebind; generation_rebind=NOT_APPLICABLE is legal only when they already match, and PASS must also end with equality. Add fresh-audit negative cases for UNKNOWN generations and mismatched generations without rebind. Consider similarly requiring canonical generation fields NOT_APPLICABLE for none/ephemeral_isolated so admission records cannot carry contradictory authority metadata.

[blakinio]

Coordinator note after PR-body update: the ## Result / Final head: 78156ef... wording is premature. Green CI on that head does not address the two independent semantic findings already recorded above: (a) root AGENTS.md is still not a universal Track A admission entrypoint, and (b) authorized canonical reuse still accepts unproven/mismatched generation fields. Keep PR Draft and task actively owned until both are fixed and revalidated; then release the task for independent promotion review. Do not treat the current PR body as final disposition.

[blakinio]

Extend the generation-binding fix to the rest of the authoritative admission tuple, so we close this class of bypass in one cycle. For canonical_reuse_or_mutation with mutation_authorized=true, also require runtime_owner_task == task_id and the declared runtime namespace to be the canonical live namespace (not UNKNOWN/NOT_APPLICABLE/another task namespace). Otherwise an admission record can currently carry Gate A/B PASS while naming another owner or a noncanonical/unknown target. Add fresh negative cases for wrong owner and wrong/unknown canonical namespace alongside the unknown/mismatched generation cases. For noncanonical none/ephemeral_isolated, keep canonical generation/registration metadata NOT_APPLICABLE so authority metadata cannot leak across classes.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 78156ef58a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[blakinio]

Root-entrypoint wording should match the contract's migrate-on-claim intent, not only runtime mutation: for any Track A (official-client-re) worker, before claim/resume it must read the Track A policy + admission contract and record runtime_access (static workers use none); before the first live operation and after authority/identity changes it must re-admit as required. That ensures even agents launched outside the canonical wrapper cannot skip classification and later silently expand from static work into runtime access.

[blakinio]

Coordination handoff notice for the active implementation session: the owner has issued a new explicit dokoncz zadanie continuation to the coordinator. PR #324 was already marked Ready/final by the implementation session, then returned to Draft by independent review. The prior implementation session should perform no further branch writes after this notice. Coordinator will verify the head remains unchanged, then rotate/take over the same task to repair the recorded findings, rerun exact-head validation, merge, and archive. If the prior worker is still executing, stop at its current checkpoint rather than racing the coordinator.

[blakinio]

Equivalent lower-overlap resolution for the remaining universal-entrypoint blocker is acceptable: root AGENTS.md Mandatory startup step 1 already requires every implementation worker to read docs/agents/README.md. Therefore, instead of changing root AGENTS.md, #324 may add a narrow mandatory Track A runtime-admission rule to docs/agents/README.md (and own/audit/trigger that path). The README rule must require every official-client-re worker to read TIBIA_RESEARCH_TRACKS.md + contracts/TRACK_A_RUNTIME_AGENT_ADMISSION_V1.md and record runtime_access at claim/resume (none for static), with re-admission before live work/authority or identity changes. If using this route, add docs/agents/README.md to owned_paths, workflow paths, and static-policy markers. Either root AGENTS.md or its mandatory startup README is sufficient; nested docs/agents/AGENTS.md alone is not.

[blakinio]

One remaining material entrypoint finding is attached inline; the prior generation/ownership findings are remediated on the current branch.

[blakinio]

README universal-entrypoint remediation is accepted semantically: root AGENTS.md mandates docs/agents/README.md, the README now carries the Track A admission rule, and the workflow triggers/audits it. One ownership hygiene fix remains before handoff: docs/agents/README.md is now a changed file but is still absent from the task owned_paths. Add it to the task ownership record, checkpoint the universal-entrypoint P1 as remediated, then rerun exact-head custom governance + repository CI. No need to change root AGENTS.md if this mandatory-README path remains enforced.

[blakinio]

Universal-entrypoint implementation is accepted; one task-ownership consistency fix remains.

[blakinio]

Final semantic hardening before merge — two related admission gaps should be fixed in the same cycle:

1. Universal README entrypoint currently says to persist admission before the first runtime-related operation. The task goal is stronger: every Track A worker classifies runtime access before work/claim/resume. Require claim/resume classification/persistence (runtime_access: none for static/no-runtime work), then re-admission before the first live operation and after authority/identity-changing facts. This prevents workers launched outside the canonical wrapper from doing substantial Track A work without an admission record and later silently expanding scope.

2. read_only validation currently accepts target_uniqueness: UNKNOWN (the fresh audit explicitly expects that case to pass), but the admission contract itself says: “If non-invasiveness, ownership, or target uniqueness cannot be proven, do not observe that surface.” For runtime_access: read_only, require target_uniqueness: PROVEN before live observation and a non-conflicting declared target/namespace/ownership boundary; keep mutation false and canonical control gates NOT_APPLICABLE. Add a negative fresh-audit case for read-only + uniqueness UNKNOWN / overlapping owner. If truly static/artifact-only evidence is intended, classify it none, not read_only.

Please include these with the already-required docs/agents/README.md ownership checkpoint, rerun exact-head governance + repository CI, and then release for final promotion.

[blakinio]

One remaining live-observation admission mismatch is attached inline; otherwise the safety tuple fixes are accepted.

[blakinio]

Clarification for the final claim/resume fix: update the contract itself too, not just README. TRACK_A_RUNTIME_AGENT_ADMISSION_V1.md Purpose already says the gate applies before claiming/resuming and says static work proceeds only after declaring runtime_access: none, but its “Required admission record” currently delays persistence until the first runtime-related operation. Make those sections consistent: persist the admission record at Track A claim/resume/checkpoint (none for static); re-run/re-persist admission before first live operation and after authority/identity changes. The canonical wrapper/README/static audit should mirror this same boundary.

[blakinio]

One CI-admission binding bypass is attached inline; this is part of the same enforcement objective, not a new scope expansion.

[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, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.