CTRL-REPO-CLIENT-01: Repository-local agent controls for thoth-client

[ja573]

Parent: thoth-pub/thoth#818

CTRL-REPO-CLIENT-01 - Repository-local agent controls for thoth-client

Programme: Shared Engineering Control
Repository: thoth-pub/thoth-client
Task ID: CTRL-REPO-CLIENT-01
Risk: MEDIUM governance
Workflow: STANDARD
Shared doctrine: thoth-pub/thoth develop merge ec7868a4a44b3d52da5638975995bb66a488b3b4 (PR #820)
Authorized base / PR target: develop at 9d3aae2dc05fca3bcdf09236719145a1759a508c
Task branch: feature/engineering/ctrl-repo-client-01
PR: #55, merged
Approved source head: 11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758
Merge commit / current develop: d6ffdc67c48cbf64f8a716f26d7d82eb541d1ecf
Runtime/package effect: NONE

Objective

Create a repository-local root AGENTS.md applying the merged shared doctrine to the standalone Python thothlibrary client without changing package/API/release behaviour.

Authoritative result

• PR CTRL-REPO-CLIENT-01: Repository-local agent controls for thoth-client #55 merged into develop on 2026-08-15 at merge commit d6ffdc67c48cbf64f8a716f26d7d82eb541d1ecf.
• Post-merge live develop points exactly to d6ffdc67c48cbf64f8a716f26d7d82eb541d1ecf.
• Merge commit parents are exactly:
  1. 9d3aae2dc05fca3bcdf09236719145a1759a508c - pre-merge develop / authorized base;
  2. 11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758 - independently approved PR head.
• GitHub verified the merge commit signature.
• Root AGENTS.md is now authoritative on develop for repository-local engineering control.
• Whole merged source scope is root AGENTS.md only; no package/runtime/test/workflow/version/release file changed.

Repository responsibility and compatibility boundary

This repository is the standalone Python client distributed as thothlibrary, distinct from the internal Rust thoth-client workspace member in thoth-pub/thoth.

The merged local control records both major contract boundaries:

• GraphQL client behaviour, including queries, mutations and PAT-based authentication;
• REST/export API behaviour, including formats/specifications/platforms and work/publisher export routes.

Future breaking Thoth GraphQL or REST/export changes must treat this repository as a downstream compatibility consumer. External consumers of published thothlibrary are not fully enumerable from Thoth repository evidence, so public package compatibility/versioning requires separate consideration.

CI / release boundary

• .github/workflows/tests.yml runs on pull requests and pushes to master/develop; the final approved head's unit-test check succeeded.
• .github/workflows/publish-to-pypi.yml triggers on release: published and publishes to PyPI using OIDC.
• A standalone Git tag does not itself trigger the PyPI workflow.
• Git tag creation, GitHub release publication and PyPI publication remain separate controlled actions; publishing a GitHub release currently carries automatic PyPI publication as a side effect.

Independent review history

Head 8a6c8e8a4ca6b847608a624d28fb1020eb1398c3

Decision: CHANGES REQUIRED.

Finding: section 12 conflated standalone Git tag creation with the release: published PyPI trigger.

Head 11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758

Decision: APPROVED.

Fresh independent review verified the remediation diff, exact ancestry, authorized file scope, current-head CI and corrected tag/release/PyPI semantics. No blocking finding remained.

Merge authorization and execution

The CTO explicitly authorized merge of PR #55 at exact approved head 11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758 into develop, subject to an immediate live integration-state recheck.

Immediately before merge:

• PR CTRL-REPO-CLIENT-01: Repository-local agent controls for thoth-client #55 remained open and mergeable;
• head remained exactly 11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758;
• base remained develop @ 9d3aae2dc05fca3bcdf09236719145a1759a508c;
• the PR was marked ready only as the mechanical prerequisite to execute the authorized merge;
• no source commit was introduced by that transition.

The merge used an expected-head-SHA guard and succeeded.

Actions not performed

No manual CI dispatch/rerun, live API call, production credential use, provider/runtime read/write, package version change, Git tag, GitHub release, PyPI publication, deployment or production activation was performed or authorized by this merge.

Current gate

MERGED - REPOSITORY-LOCAL CONTROL AUTHORITATIVE ON develop.

Repository-local implementation/review/merge is complete at merge commit d6ffdc67c48cbf64f8a716f26d7d82eb541d1ecf.

This child issue remains open only for programme-level reconciliation/closure under parent #818. No additional implementation, release, publication, deployment or production action is authorized by this state.

[ja573]

CTRL-REPO-CLIENT-01 — implementation evidence

Gate: IMPLEMENTATION COMPLETE - INDEPENDENT REVIEW REQUIRED

Base, branch, head

Authorized base:  develop @ 9d3aae2dc05fca3bcdf09236719145a1759a508c
Actual base:      9d3aae2dc05fca3bcdf09236719145a1759a508c   (verified live before branching)
Task branch:      feature/engineering/ctrl-repo-client-01
Final head:       8a6c8e8a4ca6b847608a624d28fb1020eb1398c3
PR:               #55 (DRAFT, base develop)

Commits

• 8a6c8e8a4ca6b847608a624d28fb1020eb1398c3 — docs(engineering): CTRL-REPO-CLIENT-01 repository-local agent controls

Preflight (all passed before branch creation)

• origin is git@github.com:thoth-pub/thoth-client.git; fetched.
• Working tree clean.
• origin/develop exactly 9d3aae2dc05fca3bcdf09236719145a1759a508c.
• Root AGENTS.md did not exist.
• No existing branch or PR (any state) for feature/engineering/ctrl-repo-client-01.
• Issue CTRL-REPO-CLIENT-01: Repository-local agent controls for thoth-client #54 OPEN, specification/action authorization materially unchanged.
• Read-only inspection of README.md, setup.py, requirements.txt, thothlibrary/{__init__,client,graphql,query,mutation,rest,rest_cli,rest_structures,cli}.py, thothlibrary/thoth-1_0_0/, thothlibrary/tests/, .github/workflows/tests.yml, .github/workflows/publish-to-pypi.yml; shared doctrine read from thoth-pub/thoth@ec7868a4a44b3d52da5638975995bb66a488b3b4 (AGENTS.md, docs/engineering/AGENTS.md, ai-delivery/operating-model.md, ai-delivery/implementation-handoff-template.md, repository-map/contracts.md, repository-map/repositories/thoth-client.md).

Files changed

git diff --name-status 9d3aae2dc05fca3bcdf09236719145a1759a508c 8a6c8e8a4ca6b847608a624d28fb1020eb1398c3
A       AGENTS.md

Created: AGENTS.md (410 lines). Modified: none. Deleted/moved/renamed: none.

Validation

Command	Result
git diff --cached --check	clean, exit 0
git diff --name-status <base> HEAD	A AGENTS.md only
python3 -m unittest thothlibrary.tests.test_rest thothlibrary.thoth-1_0_0.tests.tests	Ran 26 tests in 0.040s — OK (Python 3.11.6)
build-artefact check (dist/, build/, *.egg-info)	absent; none created

python -m pip install -r requirements.txt was not needed — dependencies were already present locally. python setup.py sdist bdist_wheel was not run. thothlibrary/tests/test_queries.py exists but is not part of the CI command and was not run.

Acceptance criteria

• Standalone Python thothlibrary vs internal Rust thoth-client workspace member distinction stated explicitly (§1).
• Both GraphQL (§5) and REST/export (§6) boundaries documented from verified source: ThothClient, https://api.thoth.pub, /graphql, schema version 1.0.0, bearer PAT injection; ThothRESTClient, https://export.thoth.pub, formats/specifications/platforms and work/publisher export routes.
• GraphQL surface documented as queries and mutations, not read-only; live mutations classified as external writes requiring separate authorization; production PAT use never implied.
• Public package compatibility/versioning boundary explicit (§8), including that external thothlibrary consumers are not fully enumerable from Thoth's repositories (§7).
• CI recorded accurately (§11): tests.yml on every pull_request and pushes to master/develop, Python 3.11, installs requirements.txt, runs the two unit-test modules; explicitly not evidence of live API compatibility.
• Release recorded accurately (§12): publish-to-pypi.yml triggers on release: published, builds sdist/wheel, publishes via pypa/gh-action-pypi-publish with id-token: write — publishing a GitHub release is therefore also a PyPI publication; PR creation is not release authorization.
• Exact-head independent review requirement recorded (§14); HOLD/STOP conditions recorded (§15).

Write- and action-budget compliance: PASS

Authorized and used: repository/GitHub read inspection; create root AGENTS.md; create the exact task branch from the exact base; safe local validation; commit; push; open draft PR to develop; this issue comment.

Not used: any other source/package/workflow write; delete/move/rename; live GraphQL mutation; production PAT; live provider/runtime write; manual CI dispatch or rerun; package version change; tag; release; PyPI publication; merge; deployment; production activation.

CI and automatic external effects

• Expected and observed: Tests workflow triggered by the PR — success (pull_request, run 31886852758, 11s).
• Publish to PyPI did not run for this task. The only such run in recent history is the pre-existing historic v1.2.0 release run, unrelated to this branch.
• No publication, provider or other unexpected external effect occurred.

Confirmations

• No live API call of any kind was made; no GraphQL mutation was executed.
• No production credential or PAT was accessed, used or committed.
• No package metadata, version, runtime, test or workflow file changed.
• No release, tag or publication occurred.

Cross-repository impact

None. This task changes only repository-local engineering controls: no public Python API, GraphQL/REST client behaviour, package metadata, generated contract or release workflow is affected. The new AGENTS.md requires future breaking Thoth GraphQL or REST/export changes to be handled as cross-repository compatibility work with this repository inspected before upstream scope is approved.

Deviations

NONE.

Remaining gate

Fresh independent review bound to exact head 8a6c8e8a4ca6b847608a624d28fb1020eb1398c3. Merge is not authorized; the implementing agent has not approved its own work.

[ja573]

INDEPENDENT REVIEW - CHANGES REQUIRED

Task: CTRL-REPO-CLIENT-01
PR: #55
Reviewed head: 8a6c8e8a4ca6b847608a624d28fb1020eb1398c3
Decision: CHANGES REQUIRED

Fresh independent review verified that the commit's sole parent is the exact authorized base 9d3aae2dc05fca3bcdf09236719145a1759a508c, develop remains at that SHA, PR #55 is still draft/mergeable, the whole PR changes only new root AGENTS.md, and the current Run unit tests check succeeded.

Blocking finding - release/tag/PyPI semantics

Section 12 correctly records that .github/workflows/publish-to-pypi.yml triggers on:

on:
  release:
    types: [published]

and that publishing a GitHub release causes PyPI publication. However it then states:

there is no separate "just tag it" step that avoids publishing

That is not supported by the workflow. A standalone Git tag creation/push does not match release: published and therefore does not, by itself, trigger this PyPI workflow. Tag creation remains a separately authorized action, but it must not be conflated with release publication or PyPI publication.

Required remediation

AGENTS.md only:

1. Remove the claim that there is no tag-only path avoiding publication.
2. State the verified distinction:
   • creating/pushing a Git tag alone does not trigger the current PyPI workflow;
   • publishing a GitHub release does trigger the PyPI workflow and is therefore also a PyPI publication action;
   • tag creation, GitHub release publication and PyPI publication remain separately controlled actions even when a release workflow couples the latter two operationally.
3. Preserve the deny-by-default rule and the requirement for explicit version-bound authorization.
4. Do not change any workflow, package/version file or release configuration.

Any remediation source commit invalidates this review. Fresh independent review must bind to the new exact head.

Current gate: CHANGES REQUIRED - SOURCE REMEDIATION REQUIRED.

No merge, tag, release, PyPI publication, provider/runtime action or manual CI action is authorized by this review.

[ja573]

CTRL-REPO-CLIENT-01 — remediation of independent-review finding

Gate: REMEDIATION PUSHED - FRESH INDEPENDENT REVIEW REQUIRED

Heads

Old reviewed head:  8a6c8e8a4ca6b847608a624d28fb1020eb1398c3   (review: CHANGES REQUIRED)
New exact head:     11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758
Branch:             feature/engineering/ctrl-repo-client-01   (unchanged; no new branch)
PR:                 #55 — still DRAFT, base develop

Remediation commit

• 11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758 — docs(engineering): correct tag vs release/PyPI semantics in AGENTS.md

Finding addressed

The blocking finding was that AGENTS.md §12 claimed "there is no separate "just tag it" step that avoids publishing". That claim is not supported by .github/workflows/publish-to-pypi.yml: a standalone Git tag creation/push does not emit a release: published event and therefore does not, by itself, trigger the PyPI workflow.

That sentence is removed. §12 now records the verified distinction:

• creating or pushing a Git tag alone does not trigger .github/workflows/publish-to-pypi.yml, because a standalone tag does not emit a release: published event;
• publishing a GitHub release does trigger that workflow and is therefore also a PyPI publication action under the current configuration;
• Git tag creation, GitHub release publication and PyPI publication are separate controlled actions for authorization purposes, even though the current workflow couples the second to the third operationally — authorization to create a tag is not authorization to create or publish a GitHub release, and neither is authorization to publish to PyPI;
• where an authorized action carries an automatic side effect, that side effect must be explicitly anticipated and explicitly authorized before the action is taken;
• tag, release and publication actions must always be authorized separately and explicitly, naming the version (version-bound authorization preserved);
• creating or updating an ordinary pull request is not tag, release or publication authorization, and neither is merging — merge authorization authorizes only the merge;
• an approved independent review authorizes nothing beyond the review decision.

The verified on: release: types: [published] block, the pypa/gh-action-pypi-publish / id-token: write OIDC description, and the statement that opening a PR does not trigger the PyPI workflow are all retained unchanged.

One consistency-only wording change was made outside §12: §14's combined bullet "a GitHub tag or release" is split into "Git tag creation" and "GitHub release publication", so the two distinct actions are named consistently with §12. No meaning changed — an APPROVED review still authorizes neither. All other independently reviewed content is preserved.

Files changed

git diff --name-status 8a6c8e8a4ca6b847608a624d28fb1020eb1398c3 11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758
M       AGENTS.md

Whole-PR diff against the authorized base is unchanged in shape:

git diff --name-status 9d3aae2dc05fca3bcdf09236719145a1759a508c 11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758
A       AGENTS.md

No deletion, move or rename. No package, workflow, source, version, README or release-configuration file touched. Write budget (AGENTS.md only): PASS.

Validation

Check	Result
git diff --check	clean, exit 0
remediation diff from 8a6c8e8	M AGENTS.md only
whole PR diff from base	A AGENTS.md only
no wording claiming a standalone tag triggers/causes PyPI publication	verified by grep over AGENTS.md; no such wording remains
AGENTS.md still states release: published triggers the PyPI workflow	verified (§12)
tag / release / publication remain separately authorized actions	verified (§12, §14, §15)
python3 -m unittest thothlibrary.tests.test_rest thothlibrary.thoth-1_0_0.tests.tests	Ran 26 tests in 0.025s — OK (Python 3.11.6)

CI

Tests ran automatically on the push to the PR branch — success at head 11109c8 (run 31887808714). This is the expected automatic side effect of an authorized push to an open PR. No manual CI dispatch or rerun was performed.

Confirmations

• No Git tag was created or pushed.
• No GitHub release was created or published.
• No PyPI publication occurred; Publish to PyPI did not run for this branch (the only such runs in history are pre-existing release runs unrelated to this task).
• No package publication or build command was run; no build artefacts created.
• No manual CI action, live API call, GraphQL mutation or credential use occurred.
• PR CTRL-REPO-CLIENT-01: Repository-local agent controls for thoth-client #55 remains draft; not marked ready, not merged.

Deviations

NONE.

Remaining gate

REMEDIATION PUSHED - FRESH INDEPENDENT REVIEW REQUIRED.

The review of 8a6c8e8a4ca6b847608a624d28fb1020eb1398c3 is invalidated by this commit. Fresh independent review must bind to exact head 11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758. Merge is not authorized, and the implementing agent has not approved its own work.

[ja573]

CTRL-REPO-CLIENT-01 — fresh independent source review

Decision: APPROVED

Review is bound to exact head 11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758 on PR #55.

Verified independently:

• PR CTRL-REPO-CLIENT-01: Repository-local agent controls for thoth-client #55 is open, draft and mergeable, targeting develop;
• exact PR head is 11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758;
• live develop remains the authorized base 9d3aae2dc05fca3bcdf09236719145a1759a508c;
• remediation commit 11109c87... is directly parented by previously reviewed head 8a6c8e8a4ca6b847608a624d28fb1020eb1398c3 and changes only AGENTS.md (+19/-6);
• whole PR changes only root AGENTS.md;
• the previous tag/release/PyPI defect is corrected: standalone Git tag creation does not match release: published; publishing a GitHub release triggers the PyPI workflow; tag creation, release publication and PyPI publication remain separate controlled actions, with the latter two coupled operationally by the workflow;
• GraphQL mutation/PAT, REST/export compatibility, public-package/versioning, CI, build-artifact, secrets and exact-head review boundaries remain correct;
• current-head Run unit tests check succeeded (run 31887808714);
• no evidence of manual CI, tag, release, PyPI publication, package/runtime/workflow change, live API call or credential use was introduced by this remediation.

No blocking source, scope, authorization, compatibility, release/publication or CI finding remains.

Any later source commit invalidates this approval and requires fresh exact-head review.

Current gate: SOURCE APPROVED - MERGE AUTHORIZATION REQUIRED.

This approval does not authorize merge, tag, GitHub release, PyPI publication, deployment or production activation.

[ja573]

CTRL-REPO-CLIENT-01 - MERGE AUTHORIZATION

Gate: MERGE AUTHORIZED - IMMEDIATE INTEGRATION RECHECK REQUIRED

CTO explicitly authorized merge of PR #55 on 2026-08-15.

Authorization is bound to exact independently approved source head:

11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758

Target: develop.

Live pre-merge recheck confirmed PR #55 remains open, draft and mergeable, with head 11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758 and base develop @ 9d3aae2dc05fca3bcdf09236719145a1759a508c.

Marking the PR ready for review is authorized only as the mechanical prerequisite to execute this already-authorized merge and must not change source.

Before merge execution, recheck the PR head/base again. Use an expected-head-SHA guard. If the source head changes, STOP: the source approval and merge authorization are invalidated.

This authorization is merge-only. It does not authorize Git tag creation, GitHub release publication, PyPI publication, provider/runtime access, deployment or production activation.

[ja573]

CTRL-REPO-CLIENT-01 - MERGED

Gate: MERGED - REPOSITORY-LOCAL CONTROL AUTHORITATIVE ON develop

PR #55 merged successfully on 2026-08-15.

Approved source head: 11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758
Pre-merge develop:    9d3aae2dc05fca3bcdf09236719145a1759a508c
Merge commit:         d6ffdc67c48cbf64f8a716f26d7d82eb541d1ecf
Post-merge develop:   d6ffdc67c48cbf64f8a716f26d7d82eb541d1ecf

Verified merge parents, in order:

1. 9d3aae2dc05fca3bcdf09236719145a1759a508c
2. 11109c87e0d2cdc7bc8a0d8f5bbce9eeb3d8d758

The merge commit is GitHub-verified. The merge used an expected-head-SHA guard.

Source scope remains root AGENTS.md only. No manual CI, live API call, production credential use, provider/runtime mutation, package version change, Git tag, GitHub release, PyPI publication, deployment or production activation was performed.

This issue remains open only for programme-level reconciliation/closure under parent #818. No additional implementation or operational action is authorized by the merged state.