docs(ai-delivery): CTRL-REPO-THOTH-01 canonical shared doctrine and core repository controls - #820
Merged
Merged
Conversation
…ore repository controls Reconciles the AI-led delivery controls with the approved Thoth Engineering Control & Delivery model: deny-by-default, granular, non-transitive action authorization; GitHub as the durable live task ledger; a formal cross-repository impact-analysis gate; extended task-specification, implementation-report and independent-review templates; a new implementation-handoff template; and a reconciled repository/contract map covering standalone thoth-client, thoth-pyramid and thoth-strapi. Closes/addresses #819 Parent programme: #818 Documentation and control records only. No runtime, schema, migration, GraphQL, authorization-implementation, CI-workflow, branch-protection or deployment change.
This was referenced Aug 15, 2026
Remediates CHANGES REQUIRED findings from independent review of 9b7f147 on PR #820: - Removes the implicit thoth-pub/thoth develop/master default from shared canonical doctrine (operating-model.md, task-specification-template.md, implementation-handoff-template.md, ai-delivery/README.md). Shared doctrine now speaks in terms of each repository's verified repository-local base/target/release branch, with develop/master given only as the thoth-pub/thoth worked example. Handoff/spec templates now explicitly distinguish a target repository's own AGENTS.md/local controls from thoth-pub/thoth's canonical shared doctrine, and no longer imply that docs/engineering/... exists in every target repository. - Corrects contracts.md and thoth-client.md: the standalone thoth-client verifiably consumes both the Thoth GraphQL API and the Thoth REST/export API (rest.py, rest_cli.py, rest_structures.py, README REST usage), not GraphQL alone. - Adds the verified thoth-pyramid -> metrics-widget (^2.0.1, thoth-pub/ metrics-widget) package/library interface dependency to contracts.md and thoth-pyramid.md, without starting any metrics-widget task. - Corrects thoth-strapi.md's CI/release description: build_docker.yml publishes an unconditional staging-pr-* image to GHCR on every PR open/update (no docs-only gating), separate from release-triggered publication in build_docker_release.yml and from workflow_dispatch, which remains a separate, unauthorized manual action. No runtime, schema, migration, GraphQL, authorization-implementation, CI-workflow, branch-protection or deployment change. No CI/workflow file modified. Addresses #819 Parent programme: #818 PR: #820
…cts.md Remediates remaining independent-review finding on f840fdf: two additional current consumers of the Thoth GraphQL API were missing from the repository map. - Adds thoth-pub/metrics-dashboard and thoth-pub/metrics-widget as verified current Thoth GraphQL consumers (config/index.ts defaults to https://api.thoth.pub/graphql in both repositories). - Distinguishes this current direct-GraphQL dependency from the approved future protected Metrics-GraphQL/BFF architecture without implying the future path is implemented. - Reinforces, without changing, the existing fact that the internal Rust thoth-client workspace crate is not published independently as part of the current release process (historical crates.io releases predate the current process). Does not modify metrics-dashboard.md or metrics-widget.md (outside #819's authorized write budget) and does not start any implementation/control task in either repository. No runtime, schema, migration, GraphQL, authorization-implementation, CI-workflow, branch-protection or deployment change. No CI/workflow file modified. Addresses #819 Parent programme: #818 PR: #820
ja573
commented
Aug 15, 2026
ja573
left a comment
ja573
left a comment
Member
Author
There was a problem hiding this comment.
Independent review - APPROVED
Task: CTRL-REPO-THOTH-01 / #819
Parent: #818
Reviewed PR: #820
Reviewed exact head: f789f3b50576c40efa0fd6050f75aac51f711970
Decision: APPROVED
Independent control-plane review inspected the owning specification/ledger, actual 20-file PR diff and remediation commits, repository-contract evidence, write/action-budget compliance, cross-repository consumers, branch/integration state, and CI classification/external side effects. No blocking source, scope, authorization, compatibility, migration, auth/security, runtime, or prohibited-write finding remains.
The task branch was correctly created from the authorized base ed32712766c8f5a1951bb53ec3192e18f067c7d2. During review, develop advanced through merged PR #817 to 8c0c54bd7b2e58a645ffe39abd8ceeee86e47686; GitHub produced a clean integration/merge ref and the only overlapping changed path (CHANGELOG.md) retains both changes. This base movement is treated as verified compatibility evidence, not an authorization violation. If develop moves again before merge, re-check the integration state before merge authorization/execution.
The remaining automatic publish-to-dockerhub staging-image job is explicitly non-blocking by CTO direction on 2026-08-15. Classification itself succeeded and returned docs_only=false, run_build=false, run_docker=true, run_migrations=false because root AGENTS.md is outside the documentation allow-list. No manual CI action is authorized or required.
This approval is source/stage approval only. It does not authorize merge, deployment, release, migration execution, publication, or production activation. Any new source commit invalidates this approval.
ja573
marked this pull request as ready for review
August 15, 2026 11:06
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
This was referenced Aug 15, 2026
ja573
added a commit
that referenced
this pull request
Aug 17, 2026
Codex raised a P1 on the tracker: it described BE-04 in transient workflow terms that merging PR #816 would immediately falsify, which is exactly what docs/engineering/AGENTS.md section 1.1 forbids in a committed file. Merging would have required an immediate corrective commit. The tracker now records the durable decision instead. BE-04's status becomes IMPLEMENTATION DELIVERED - RUNTIME INACTIVE in the summary paragraph, the task-table Status cell and the Acceptance cell. Present-tense lifecycle wording is removed throughout: "implementation candidate", "implementation branch", "IMPLEMENTATION CONTROLLED BY PR #816", the claim that the implementation is unmerged and that develop still lacks the distribution_job relations, and "merge would authorize". Repository authority is stated as an authority condition that attaches when the exact independently approved content is reachable from develop, and live review, approval, CI and merge state is left to GitHub under ADR-0005. Historical traceability is kept: delivery through PR #816, the baseline through PR #814, corrected Addendum 01 through PR #817, the doctrine merged through PR #820, and the authorizations recorded on issue #821 all remain. The wording is now true both before and after PR #816 merges. contracts.md registered thoth-pub/baboon as a verified consumer of the Thoth GraphQL and metadata export APIs on 2026-08-16, after this implementation report's consumer matrix was written, so BE-04 lacked the explicit Baboon impact assessment the cross-repository gate requires. Section 10.7 adds it as row 8, REMAINS COMPATIBLE, with the reasoning enumerated: the GraphQL change is additive, no existing field is removed, retyped, made stricter or given a required argument, no existing default changes incompatibly, the export format and export-availability semantics are untouched, the discovery fields Baboon queries are unmodified, and DISSEMINATION_WORKER governs only the new worker mutations. No Baboon source change or downstream task is required. The assessment is dated honestly: it was added during this review remediation after Baboon became a verified consumer, not during the original implementation. Baboon was read only through this repository's own repository-map records and was not modified. The matrix now covers every currently verified consumer, with thoth-sphinx kept separate as a planned future consumer rather than as compatible, and cc-license excluded on evidence as a crate this repository consumes. Section 1.9 records this episode: starting head baab314, incorporated develop 6f192ea, a two-file write budget, no new files, and no runtime, specification, GraphQL, migration or cross-repository source effect. baab314 is recorded as this episode's authorized starting state, an ordinary merge that pre-dates it and that this agent did not create. Episode counts, the authority table, the commit tables, the write-budget and action-authorization matrices and the confirmations are reconciled accordingly. The prior process-exception history is preserved unchanged: one authorized push, two unauthorized pushes, their two unauthorized automatic staging-pr-* publications, the CTO's acceptance, no retroactive authorization and no cleanup requirement. Documentation and control only. No runtime, source, test, migration, specification, ADR, CHANGELOG, workflow or contract-map change, and no downstream repository was touched.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements
CTRL-REPO-THOTH-01- canonical shared doctrine and core repository controls for the Shared Engineering Control programme.Closes/addresses #819
Parent programme: #818
What changed and why
Reconciles the AI-led delivery controls with the approved Thoth Engineering - Control & Delivery model so that:
AGENTS.mdanddocs/engineering/ai-delivery/operating-model.mdreplace generic "may branch/commit/push/PR" grants with an explicit action list (repository read, source write, new-file creation, delete/move/rename, branch, commit, push, PR mutation, issue mutation, manual CI dispatch, provider/runtime read/write, migration execution, release/publication, merge, deployment, production activation) where authorization for one action never implies another.operating-model.mdsection 3.2 defines task resumption from durable evidence (issue, spec, live branch/SHA, PR, review, CI);docs/engineering/AGENTS.mdretains the ADR-0005 durable/transient distinction.operating-model.mdsection 4.1, rootAGENTS.mdsection 6.1) before substantive/contract-affecting scope is approved, with a newdocs/engineering/repository-map/contracts.mdrecording verified ownership and consumer relationships.docs/engineering/ai-delivery/implementation-handoff-template.mdcarries exact base/target/branch, write budget, authorized new files, prohibited paths, action matrix, automatic side effects, preflight, acceptance, validation, HOLD/STOP conditions and the required completion report.task-specification-template.md,implementation-report-template.mdandindependent-review-template.mdadd owning-issue/programme-stage/exact-base-SHA identity, cross-repository impact/consumer-compatibility fields, write-budget compliance, authorized-vs-actual actions, and automatic/manual external effects. Exact-head binding for independent review is preserved.branching-and-release-workflow.mdis scoped explicitly tothoth-pub/thoth; other repositories' topology is authoritative in their own repository-map entries, not assumed from this document.thoth-pub/thoth-client(Python, PyPIthothlibrary),thoth-pub/thoth-pyramidandthoth-pub/thoth-strapi;contracts.mdexplicitly distinguishes the standalone Pythonthoth-clientfrom the internal Rustthoth-clientworkspace member in this repository.thoth-sphinx's branch state was independently re-verified live on 2026-08-15 (bothmainanddevelopexist and remain identical, placeholder-only).Cross-repository impact
This is a control-doctrine change consumed by
thoth-pub/thoth-app,thoth-pub/thoth-dissemination,thoth-pub/thoth-client,thoth-pub/thoth-sphinx,thoth-pub/thoth-pyramidandthoth-pub/thoth-strapi(see #818). Those repositories' own repository-local control tasks (#113,#95,#54,thoth-sphinx#1,thoth-pyramid#14,thoth-strapi#4) must not implement against this unmerged wording; they scope against the merged doctrine after this PR merges and is independently reviewed.Files changed / new files
20 files, all within the authorized write budget for this task (verified: actual
git diff --statfile list matches the budget exactly, no additions/deletions/renames outside it):Modified:
AGENTS.md,CHANGELOG.md,docs/engineering/AGENTS.md,docs/engineering/ai-delivery/README.md,docs/engineering/ai-delivery/branching-and-release-workflow.md,docs/engineering/ai-delivery/implementation-report-template.md,docs/engineering/ai-delivery/independent-review-template.md,docs/engineering/ai-delivery/operating-model.md,docs/engineering/ai-delivery/task-specification-template.md,docs/engineering/repository-map/README.md,docs/engineering/repository-map/branch-topology.md,docs/engineering/repository-map/repositories/thoth.md,docs/engineering/repository-map/repositories/thoth-app.md,docs/engineering/repository-map/repositories/thoth-dissemination.md,docs/engineering/repository-map/repositories/thoth-sphinx.md.New:
docs/engineering/ai-delivery/implementation-handoff-template.md,docs/engineering/repository-map/contracts.md,docs/engineering/repository-map/repositories/thoth-client.md,docs/engineering/repository-map/repositories/thoth-pyramid.md,docs/engineering/repository-map/repositories/thoth-strapi.md.No deletions, moves or renames.
No runtime/schema/migration/provider effect
Documentation and control records only. No runtime, schema, migration, GraphQL, authorization-implementation, CI-workflow, branch-protection or deployment change.
Validation performed
git diff --check- clean.git diff --stat/git status --short- actual diff matches the authorized write budget exactly (20 files: 15 modified incl. CHANGELOG.md, 5 new).thoth-sphynxspelling check - none found.thoth-clientvs internal Rustthoth-clientdistinction reviewed for consistency across all touched files.gh repo view,gh api .../branches,gh api .../compare,gh api .../contents,gh api .../commits) forthoth-app,thoth-dissemination,thoth-client(standalone),thoth-sphinx,thoth-pyramid,thoth-strapi.Known automatic PR/CI side effects (observed, not predicted)
Opening this PR triggered the
publish-to-dockerhubclassifier(
.github/scripts/classify_ci_changes.py), which returned{"docs_only": "false", "run_build": "false", "run_docker": "true", "run_migrations": "false"}and ranbuild_and_push_staging_docker_image,publishing a
staging-pr-820-tagged image toghcr.io/thoth-pub/thoth(job completed successfully). This was not a classifier failure or
misclassification: classification succeeded correctly per its own rule.
Root cause:
is_documentation_path()in that script only matchesCHANGELOG.mdand paths underdocs/; this PR also modifies root-levelAGENTS.md, which the classifier does not recognize as documentation, sodocs_onlywas correctly computed asfalsefor this diff given that rule.The remediation commit does not touch
AGENTS.mdat the classifier'stop-level-path granularity any differently, so the same automatic
staging-image publication recurred on the remediation push. No manual
workflow dispatch, rerun or cancellation was performed, and none is
authorized. Fixing the classifier's documentation-path allow-list is a
CI-workflow-implementation change outside this task's authorized write
budget; it is not attempted here and may warrant a separate, explicitly
scoped control-gap follow-up under #818/#819 if the CTO wants it addressed.
Remediation applied on this branch/PR
Independent review of head
9b7f14798d59ca4a5b634eeb9d7f211f7b186c20returnedCHANGES REQUIRED. Remediation was pushed as a second commit to this samebranch/PR (no new branch or PR opened):
thoth-pub/thothdevelop/masterdefault fromshared canonical doctrine (
operating-model.md,task-specification-template.md,implementation-handoff-template.md,ai-delivery/README.md); shared doctrine now speaks in terms of eachrepository's verified repository-local base/target/release branch, with
develop/mastergiven only as thethoth-pub/thothworked example, andhandoff/spec templates now explicitly distinguish a target repository's
own
AGENTS.md/local controls fromthoth-pub/thoth's canonical shareddoctrine.
contracts.mdandthoth-client.md: the standalonethoth-clientverifiably consumes both the Thoth GraphQL API and theThoth REST/export API (
rest.py,rest_cli.py,rest_structures.py,README REST usage), not GraphQL alone.
thoth-pyramid->metrics-widget(^2.0.1,thoth-pub/metrics-widget) package/library interface dependency tocontracts.mdandthoth-pyramid.md, without starting anymetrics-widgettask.thoth-strapi.md's CI/release description:build_docker.ymlpublishes an unconditional
staging-pr-*image to GHCR on every PRopen/update (no docs-only gating in that repository at all), distinct from
release-triggered publication in
build_docker_release.ymland fromworkflow_dispatch, which remains a separate, unauthorized manual action.New exact head after that round:
f840fdf38b704494aa0290ae4f737e66f1ce0c64.Second remediation round
Independent review of head
f840fdf38b704494aa0290ae4f737e66f1ce0c64againreturned
CHANGES REQUIRED. Remediation pushed as a third commit to this samebranch/PR (no new branch or PR opened):
to
contracts.mdandthoth.md:thoth-pub/metrics-dashboard(
config/index.ts,NEXT_PUBLIC_THOTH_API_URLdefaulting tohttps://api.thoth.pub/graphql) andthoth-pub/metrics-widget(
src/shared/config/index.ts,VITE_THOTH_API_URLdefaulting to the sameURL). Distinguished this current direct-GraphQL dependency from the
approved future protected Metrics-GraphQL/BFF architecture without
claiming that future path is implemented. Did not modify
metrics-dashboard.md/metrics-widget.md(outside CTRL-REPO-THOTH-01: Canonical shared doctrine and core repository controls #819's write budget)and did not start any implementation/control task in either repository.
the stale "
thoth-sphinxdevelop branch is absent" discovery premise withthe verified fact that both
mainanddevelopexist and are currentlyidentical, placeholder/bootstrap-only; and replaced the old
"classifier-failure-contingent" prediction of Docker publication with the
observed fact that classification succeeded and correctly returned
docs_only=falsebecause rootAGENTS.mdis outside the classifier'sCHANGELOG.md/docs/**documentation-path allow-list. Also corrected aninternal "four" vs "six" finding-count inconsistency in CTRL-REPO-THOTH-01: Canonical shared doctrine and core repository controls #819's own
Current-gate prose. Historical evidence comments on CTRL-REPO-THOTH-01: Canonical shared doctrine and core repository controls #819 were left
untouched (append-only).
thoth-clientworkspace crateremains stated as not published independently as part of the current
release process (historical
crates.ioreleases predate currentdelivery) — this fact was reinforced, not altered.
New exact head:
f789f3b50576c40efa0fd6050f75aac51f711970. The reviews of9b7f1479...andf840fdf3...do not carry forward.Remaining gate
Fresh independent exact-head review of
f789f3b50576c40efa0fd6050f75aac51f711970is required before any merge authorization. This PR must not be merged by the
implementing agent, and repository-local control tasks
#113,#95,#54,thoth-sphinx#1,thoth-pyramid#14,thoth-strapi#4remain blocked on thisdoctrine being independently reviewed and merged first.