CTRL-REPO-THOTH-01: Canonical shared doctrine and core repository controls

[ja573]

Parent: #818

CTRL-REPO-THOTH-01 - Canonical shared doctrine and core repository controls

Programme: Shared Engineering Control
Repository: thoth-pub/thoth
Task ID: CTRL-REPO-THOTH-01
Risk: MEDIUM governance
Reasoning: HIGH
Workflow: STANDARD
Original authorized base: develop @ ed32712766c8f5a1951bb53ec3192e18f067c7d2
Production/runtime effect: NONE

Objective

Reconcile the canonical Thoth engineering-delivery doctrine with the approved Control & Delivery model so GitHub is the durable live task ledger, mutation permissions are granular and non-transitive, cross-repository impact is assessed before substantive task scope is approved, and repository-local controls inherit a single shared contract without copying repository-specific assumptions.

Authoritative merged result

The core control work and its subsequent reconciliation/closeout stages are merged on develop:

1. PR docs(ai-delivery): CTRL-REPO-THOTH-01 canonical shared doctrine and core repository controls #820 - core shared doctrine / repository map
   • independently approved source head: f789f3b50576c40efa0fd6050f75aac51f711970
   • merge commit: ec7868a4a44b3d52da5638975995bb66a488b3b4
2. PR CTRL-DELIVERY-01: reconcile canonical repository map with re-verified live state #822 - canonical map reconciliation
   • independently approved source head: 08a700ecad7e4c9de8cfe561eaa08c23be0813cc
   • merge commit: e70fd5e04f9ee8d6b0dfb85ff14ef3b0622fdab2
3. PR CTRL-DELIVERY-01-CLOSEOUT-01: reconcile merged Shared Engineering Control rollout state #823 - final rollout/control-gap closeout reconciliation
   • independently approved source head: e304cf93e5c90d921dd535b9d72d1a2c85403516
   • merge commit / current authoritative develop: 0a33d553ef82140caf6c0378c1dfc5f48782361c

All three stages were documentation/control work. No runtime source, schema/migration, workflow implementation, provider configuration, release or deployment file was introduced by these changes.

Durable control result

The merged doctrine now establishes:

• GitHub issues/PRs/reviews/CI/merge records as the live lifecycle ledger;
• durable recovery without relying on chat history;
• deny-by-default granular non-transitive action authorization;
• exact authorized base and bounded write budgets;
• mandatory cross-repository impact analysis before substantive scope approval;
• downstream compatibility and merge/deployment ordering controls;
• one bounded task/branch/PR per repository;
• exact-head independent review;
• separate implementation, review, merge, migration, deployment and production-activation gates;
• explicit automatic-side-effect accounting.

The task specification, implementation handoff/report and independent-review templates carry those controls. The repository/contract map distinguishes verified owners and consumers, including the standalone Python thoth-pub/thoth-client from the internal Rust workspace member.

Cross-repository result

The six repository-local child controls were implemented only after the shared doctrine merged. Their authoritative integration heads are:

• App dev @ 7a4e7c6ceaec36fbdb201eaeb9ae36985a709889
• Dissemination develop @ 71ef7724326e9e75ccea2c004b5ca5be8197f27e
• standalone Client develop @ d6ffdc67c48cbf64f8a716f26d7d82eb541d1ecf
• Sphinx develop @ ff7de985d03f0c94d5ad8d60727f9cf85b6435cd
• Pyramid dev @ 2ee7a71f068db828a547fb60627d5a89243d209d
• Strapi develop @ 306220326189697252a708a203d6b4cc02f018cc

Final cross-repository integration review under parent #818 is APPROVED against those six heads plus thoth/develop @ 0a33d553ef82140caf6c0378c1dfc5f48782361c, with no unresolved P0/P1 findings. Parent integration approval is recorded in #818 comment 5303923636.

Acceptance criteria

• Shared doctrine separates repository read, source write, branch, commit, push, PR mutation, issue mutation, manual CI, provider read/write, migration, release/publication, merge, deployment and activation permissions.
• Permission for one action never implies another.
• GitHub holds live lifecycle state; committed docs retain durable doctrine/architecture.
• Substantive/contract-affecting tasks require cross-repository impact analysis before repository scope approval.
• Known consumers are assigned downstream work or explicitly evidenced as compatible.
• Implementation handoffs contain exact base/target/branch, write budget, authorized/prohibited actions, automatic side effects, acceptance, validation and HOLD/STOP conditions.
• Implementation reports record actual actions/effects against authorization.
• Independent review verifies exact head, actual diff, acceptance evidence, compatibility and action/write-budget compliance.
• Repository map includes verified standalone Client, Sphinx, Pyramid and Strapi records alongside the existing managed repositories.
• Standalone Python client is distinguished from the internal Rust thoth-client crate.
• Sphinx canonical state is reconciled without performing BR-SPHINX-01 or SPHINX-BOOT-01.
• No runtime, schema, migration, auth implementation, CI workflow, branch-protection or deployment behaviour change was introduced.

Separate follow-up work

Branch normalization, Sphinx bootstrap, Dissemination README/environment protection, Pyramid dev CI coverage, Strapi Docker/Node CI repair and Metrics-programme documentation/control work remain separate tasks. They do not reopen this completed core-control implementation unless a future change invalidates the shared doctrine itself.

Current gate

MERGED - RECONCILED - FINAL PROGRAMME INTEGRATION APPROVED - CLOSURE AUTHORIZATION REQUIRED.

No further source action is required for CTRL-REPO-THOTH-01. Issue closure remains a separate mutation requiring explicit authorization.

[ja573]

Implementation evidence

Task branch feature/engineering/ctrl-repo-thoth-01 created from the exact authorized base ed32712766c8f5a1951bb53ec3192e18f067c7d2 (verified identical to origin/develop at implementation start). Draft PR opened targeting develop:

#820

Head commit: 9b7f14798d59ca4a5b634eeb9d7f211f7b186c20

20 files changed (15 modified, 5 new), matching the authorized write budget exactly — verified by diffing the actual git diff --stat file list against the budget in this issue. No deletions, moves or renames.

Live-evidence corrections applied

• thoth-sphinx was re-verified live 2026-08-15: both main and develop exist and remain identical (placeholder-only README.md, same initial commit). This differs from this issue's background note that the repository-map recorded a develop branch "not present in the live repository" — live evidence does not support that claim, so the repository-map entry was left correct on that point rather than "corrected" to match the stale assumption, per the instruction to trust live evidence over the prompt.
• thoth-client (standalone): default branch master, active development develop (feature PRs target develop; develop is 1 commit ahead of master via a release merge) — confirms the assumption in this issue.
• thoth-pyramid: default main, active dev; verified consumer of the Thoth GraphQL API and export API, and of thoth-strapi's content API (.env.example, codegen.ts).
• thoth-strapi: default main, active develop; Strapi 4 CMS with Thoth-ID-linkage content types; no verified dependency on the Thoth API itself.

Known automatic CI/external effect observed

Opening the PR triggered publish-to-dockerhub's classifier (.github/scripts/classify_ci_changes.py), which returned {"docs_only": "false", "run_docker": "true", ...} and started build_and_push_staging_docker_image. Root cause: the classifier only treats CHANGELOG.md and paths under docs/ as documentation; this PR also touches root-level AGENTS.md, which it does not recognize, so it did not classify the diff as docs-only. This is the disclosed automatic side-effect risk in this issue's "Automatic side effects" section, materializing via a classifier rule gap rather than a classification error. No manual workflow dispatch, rerun, or classifier/workflow modification was performed or is authorized; this is reported as observed, not remediated, since remediating the classifier is a CI-workflow-implementation change outside this task's write budget.

Independent exact-head review at 9b7f14798d59ca4a5b634eeb9d7f211f7b186c20 remains the next gate. This PR has not been merged and will not be merged by the implementing agent.

[ja573]

Remediation evidence

Independent review of head `9b7f14798d59ca4a5b634eeb9d7f211f7b186c20` returned `CHANGES REQUIRED`. Remediation pushed as a second commit to the same branch/PR (no new branch/PR):

• `f840fdf38b704494aa0290ae4f737e66f1ce0c64` - fixes the four findings (repository-agnostic branch-topology language in shared doctrine; standalone thoth-client GraphQL+REST/export contract coverage; thoth-pyramid -> metrics-widget package dependency; thoth-strapi PR-triggered automatic staging GHCR publication).

8 files changed (all previously-authorized-modify paths from #819's original write budget; no new files, no deletions/moves/renames): `docs/engineering/ai-delivery/README.md`, `docs/engineering/ai-delivery/implementation-handoff-template.md`, `docs/engineering/ai-delivery/operating-model.md`, `docs/engineering/ai-delivery/task-specification-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`.

Validation: `git diff --check` clean; `git diff --stat`/`git status --short` confirm write-budget compliance; link review clean; no `thoth-sphynx` spelling; no CI/workflow files touched.

The classify job on the original head (`9b7f1479...`) returned `{"docs_only": "false", "run_docker": "true", ...}` because root `AGENTS.md` is outside `.github/scripts/classify_ci_changes.py`'s documentation-path allow-list (only `CHANGELOG.md` and `docs/**` match) — not a classifier failure, a correct classification under that rule's scope. The disclosed staging-image build/push (`staging-pr-820` to `ghcr.io/thoth-pub/thoth`) ran and completed successfully on the original head, and recurred identically on the remediation push for the same root-`AGENTS.md` reason. No manual dispatch/rerun/cancellation was performed. Fixing the classifier is a CI-workflow-implementation change outside this task's write budget and is not attempted here.

PR #820 body updated accordingly. New exact head requiring fresh independent review: `f840fdf38b704494aa0290ae4f737e66f1ce0c64`.

[ja573]

Second remediation round evidence

Independent review of head `f840fdf38b704494aa0290ae4f737e66f1ce0c64` returned `CHANGES REQUIRED` again. Remediation pushed as a third commit to the same branch/PR (no new branch/PR):

• `f789f3b50576c40efa0fd6050f75aac51f711970`

Fixes:

1. Added `thoth-pub/metrics-dashboard` and `thoth-pub/metrics-widget` as verified current Thoth GraphQL consumers to `contracts.md` and `thoth.md` (both default to `https://api.thoth.pub/graphql\` in their config), distinguished from the approved future protected Metrics-GraphQL/BFF architecture. Did not touch `metrics-dashboard.md`/`metrics-widget.md` (outside write budget) and started no implementation/control task in either repository.
2. Reconciled this issue's own body: replaced the stale "thoth-sphinx develop branch absent" premise with the verified current fact (both `main`/`develop` exist, identical, bootstrap-only); replaced the outdated "classifier-failure-contingent" Docker-publication prediction with the observed fact (classification succeeded correctly; root `AGENTS.md` is outside the docs-only allow-list); fixed a "four" vs "six" finding-count inconsistency in the Current-gate prose.
3. Confirmed unchanged: the internal Rust `thoth-client` workspace crate is not published independently as part of the current release process — reinforced, not altered.

2 files changed in this round (both previously-authorized paths, no new/deleted files): `docs/engineering/repository-map/contracts.md`, `docs/engineering/repository-map/repositories/thoth.md`.

Validation: `git diff --check` clean; write-budget compliance confirmed (only previously-authorized paths touched); no CI/workflow files changed; no `thoth-sphynx` spelling; standalone-vs-internal thoth-client distinction, Pyramid->metrics-widget edge, Strapi GHCR description and Sphinx branch evidence all confirmed intact and unchanged.

PR #820 body and #818's Current gate updated accordingly. New exact head requiring fresh independent review: `f789f3b50576c40efa0fd6050f75aac51f711970`.

[ja573]

INDEPENDENT REVIEW - APPROVED

Task: CTRL-REPO-THOTH-01
PR: #820
Reviewed exact head: f789f3b50576c40efa0fd6050f75aac51f711970
Decision: APPROVED

Fresh independent control-plane review found no blocking source, scope, authorization, compatibility, migration, auth/security, runtime, or prohibited-write issue. The review inspected the actual 20-file diff, remediation history, consumer/contract evidence, write/action-budget compliance, issue/PR ledger, current integration state and automatic CI side effects.

develop advanced after task-branch creation through PR #817 to 8c0c54bd7b2e58a645ffe39abd8ceeee86e47686; the resulting GitHub integration state was reviewed as clean, including the overlapping CHANGELOG.md path. Re-check the integration state before merge if develop moves again.

By CTO direction on 2026-08-15, the remaining automatic staging-image CI is non-blocking for this governance task. No manual CI mutation is authorized or required.

This approval is source/stage approval only and does not authorize merge, release, deployment, migration execution, publication or production activation. Any new source commit invalidates this approval.

Next gate: explicit CTO merge authorization bound to f789f3b50576c40efa0fd6050f75aac51f711970.

[ja573]

MERGE AUTHORIZED

Task: CTRL-REPO-THOTH-01
PR: #820
Authorized reviewed head: f789f3b50576c40efa0fd6050f75aac51f711970
Target: develop
Integration target verified immediately before merge: develop @ 8c0c54bd7b2e58a645ffe39abd8ceeee86e47686
Observed GitHub merge ref: f4f0966e4c52fe89dc4aa043f7264540438853d0 (f789f3b5... integrated into 8c0c54bd...)
Mergeability: clean / mergeable

The CTO explicitly authorized merge of PR #820 at the exact reviewed head above into develop, subject to this immediate live integration-state recheck. The recheck passed: the source head is unchanged, develop has not moved since the approved integration review, and GitHub's current merge ref remains clean.

The remaining automatic staging-image CI is explicitly non-blocking by prior CTO direction. This authorization permits the merge only; it does not authorize deployment, release, migration execution, provider changes, or production activation.

[ja573]

MERGED

Task: CTRL-REPO-THOTH-01
PR: #820
Approved source head: f789f3b50576c40efa0fd6050f75aac51f711970
Target immediately before merge: develop @ 8c0c54bd7b2e58a645ffe39abd8ceeee86e47686
Merge commit: ec7868a4a44b3d52da5638975995bb66a488b3b4
Merged at: 2026-08-15 11:06:28 UTC
Post-merge develop: ec7868a4a44b3d52da5638975995bb66a488b3b4

Post-merge verification confirms the merge commit has exactly these parents:

1. 8c0c54bd7b2e58a645ffe39abd8ceeee86e47686 - the live develop head verified immediately before merge;
2. f789f3b50576c40efa0fd6050f75aac51f711970 - the independently reviewed and CTO-authorized PR head.

PR #820 is closed as merged. The remaining automatic staging-image CI was explicitly non-blocking by CTO direction and was not manually mutated.

Current gate: core shared doctrine is MERGED and repository-authoritative on develop. No deployment, release, migration, provider change or production activation followed from this merge.

The repository-local control tasks in #818 are no longer blocked by an unmerged shared-control contract. Each still requires its own repository-local live preflight, exact base authorization, bounded write/action budget, implementation, and independent review; this merge does not automatically authorize those mutations.

[ja573]

CTRL-DELIVERY-01 reconciliation - execution HOLD

CTO authorization for the bounded thoth-pub/thoth reconciliation task was received on 2026-08-15.

Authorized task:

• base/target: develop @ ec7868a4a44b3d52da5638975995bb66a488b3b4
• branch: feature/engineering/ctrl-delivery-01-reconciliation
• write budget only:
  • docs/engineering/repository-map/branch-topology.md
  • docs/engineering/repository-map/repositories/thoth-sphinx.md
  • docs/engineering/repository-map/repositories/thoth-strapi.md
  • CHANGELOG.md
• authorized actions: repository/GitHub reads, local documentation validation, commit, push, draft PR to develop, append-only issue evidence
• all other source paths, workflow changes, provider/runtime actions, release, deployment, activation and merge remain unauthorized

Execution is currently HOLD - PUBLISH TOOLING UNAVAILABLE IN CONTROL-PLANE ENVIRONMENT.

Mandatory publish preflight failed before any repository mutation because the current control-plane environment does not have GitHub CLI installed: gh: command not found. The required GitHub publish workflow explicitly requires gh and prohibits bypassing that prerequisite by performing source mutations through the GitHub connector.

No task branch was created, no source file was edited, no commit or push occurred, and no PR was created or updated. No workflow/provider/runtime/release/deployment effect occurred.

The authorized task remains valid but unexecuted in this environment. A publish-capable environment must re-run the full preflight, including exact-base verification against ec7868a4a44b3d52da5638975995bb66a488b3b4, before creating the branch. If develop has moved at that point, return HOLD rather than rebasing or broadening scope.

[ja573]

CTRL-DELIVERY-01 — canonical repository-map reconciliation: implementation evidence

Base

Authorized base:  develop @ ec7868a4a44b3d52da5638975995bb66a488b3b4
Actual base:      ec7868a4a44b3d52da5638975995bb66a488b3b4

origin/develop was verified to equal the authorized base at preflight and
re-verified unchanged after the final push. The base did not move.

Branch, head, commits

Task branch:  feature/engineering/ctrl-delivery-01-reconciliation
Final head:   f66ce2c7ed4dd4318d2fc944e8f66d7b51509ffc
Commits:      03dbf27f2967a27d95e21e82f14c3bb2eff8de42
                CTRL-DELIVERY-01: reconcile canonical repository map with live state (#819)
              f66ce2c7ed4dd4318d2fc944e8f66d7b51509ffc
                CTRL-DELIVERY-01: reference PR #822 in the changelog entry (#819)

The second commit exists only to satisfy root AGENTS.md section 13
("reference the PR number when available"), which requires the PR number that
does not exist until the PR is opened.

Draft PR

#822 → develop. DRAFT. Not marked ready. Not merged. Not
self-approved.

Exact four-file scope

Whole-branch diff against ec7868a4a44b3d52da5638975995bb66a488b3b4:

M	CHANGELOG.md
M	docs/engineering/repository-map/branch-topology.md
M	docs/engineering/repository-map/repositories/thoth-sphinx.md
M	docs/engineering/repository-map/repositories/thoth-strapi.md

Four files, all modifications, nothing else. No additions, deletions, moves or
renames.

Objective 1 — thoth-sphinx, re-verified live 2026-08-15

Fact	Observed
main	0896e4061e06bc640f917f1aaf25c14b6e25269a — original placeholder-only branch, README.md alone
develop	7d6d4a24fde1ee0473f2ac66387167998f67ebb1 — root AGENTS.md plus the unchanged placeholder README.md
main vs develop	not identical: compare/main...develop = ahead_by: 5, behind_by: 0, status: ahead; AGENTS.md the only changed file
README.md blob	ba19f1ba2a27adc8640691aea407aeb51b1a6f32 — identical on both branches, i.e. unchanged
Workflows	zero (actions/workflows → total_count: 0)

Three stale claims corrected: that the branches are identical; that both contain
only the placeholder README; and that SPHINX-BOOT-01 must add a root
AGENTS.md.

Recorded: main remains the original placeholder-only branch; develop has
diverged solely through the completed CTRL-REPO-SPHINX-01
repository-control work; develop contains the root AGENTS.md plus the
unchanged placeholder README; no runtime/bootstrap/CI/provider implementation
exists; the repository remains bootstrap-only and non-implementation-ready;
BR-SPHINX-01 remains separate; SPHINX-BOOT-01 remains separate; bootstrap
must preserve and use the existing root AGENTS.md rather than treat it as
absent. branch-topology.md updated consistently.

No branch normalization performed.

Objective 2 — thoth-strapi, trigger vs outcome

Verified from .github/workflows/build_docker.yml on develop: on: pull_request for every open/head-update event, no path filter and no docs-only
exemption; logs into ghcr.io; docker/build-push-action@v5 with push: true; configured tag staging-pr-<PR number>.

Therefore PR creation/update in that repository is a publication-capable
external side effect that triggers an automatic publication attempt.
Successful runs publish the staging image; a run may fail before
publication; the actual publication result must be observed, not assumed.

Supporting observation — both pull_request runs for thoth-strapi PR #5:

Run	Conclusion	Login to Container registry	Build and push	Image digest
31897054063	failure	success	failure	skipped
31898765737	failure	success	failure	skipped

Attempt automatic in both cases; neither reached publication.

The authorization requirement for PR creation/update is unchanged and not
weakened — it remains explicitly required under the granular, non-transitive
model in root AGENTS.md section 6. Manual workflow_dispatch, release
publication, provider actions, deployment and activation remain distinct,
separately authorized actions.

Validation

Check	Result
git diff --check	clean, exit 0
Whole-branch git diff --name-status vs authorized base	exactly the four authorized paths
Relative links and backticked *.md path refs in all four changed files	all resolve
Repository/branch names, status terminology (docs/engineering/AGENTS.md §5–6)	conform
Changelog under ## [Unreleased] / ### Changed, no duplicate heading	conform
Workflow modification	none
Manual CI dispatch or rerun	none

One pre-existing shorthand reference (repository-map/README.md) in an
unrelated historical CHANGELOG.md entry does not resolve. It predates this
branch, is not introduced here, and was left untouched as out of scope.

Automatic CI / external effects (observed only)

Opening the draft PR and pushing the head update automatically triggered
thoth-pub/thoth's own on: pull_request workflows. Nothing was dispatched,
rerun or cancelled.

Final head f66ce2c7:

Run	Workflow	Conclusion	Jobs
31901138695	build-test-and-check	success	classify success; build, test, lint, format_check skipped
31901138648	run-migrations	success	classify success; run_migrations skipped
31901138652	publish-to-dockerhub	success	classify success; build_and_push_staging_docker_image skipped
31901138661	check-changelog	success	success

Intermediate head 03dbf27f produced the same four workflows with identical
conclusions and the same skip pattern.

Publication outcome, observed rather than assumed: the documentation-only
classifier (PR #771) skipped build_and_push_staging_docker_image on both
heads, so no staging image was published to Docker Hub by this PR. This is
the same trigger-vs-outcome distinction Objective 2 records, and it holds here
because this repository's PR workflow does have a docs-only classifier —
unlike thoth-pub/thoth-strapi's, which does not.

No provider, registry or runtime state was acted on.

Unauthorized actions

None. No path outside the four authorized files was written. No delete,
move or rename. No workflow or CI change. No branch settings or normalization.
No provider/runtime action. No secrets accessed. No release, tag or
publication. No deployment or activation. No merge. No mutation of parent #818.
No self-approval. PR left as draft.

Deviations

1. No implementation-report file. Root AGENTS.md section 14 requires the
   implementation-report-template.md structure before review, but
   docs/engineering/ai-delivery/implementation-reports/ is not an authorized
   write path for this task. The equivalent evidence is recorded in this
   comment and in the PR body instead of creating an unauthorized file.

2. Two extra commits rather than one. As noted above, the second commit
   only inserts the PR number into the changelog entry, which cannot be known
   before the PR exists.

3. Residual stale statements left outside the write budget — flagged, not
   fixed, because correcting them would require write paths this task does not
   authorize:

   • docs/engineering/repository-map/control-gaps.md — CG-03 still states
     "main and develop exist and contain only a placeholder README";
   • docs/engineering/agent-instructions/rollout-plan.md — the thoth-sphinx
     row still states "placeholder-only README; no verified AGENTS.md" with
     required action "add AGENTS.md …".

   Both are now inaccurate for the same reason Objective 1 corrects the
   repository map, and both need a separately scoped, separately authorized
   task. Historical implementation reports containing point-in-time statements
   are correctly left unchanged.

Gate

RECONCILIATION IMPLEMENTATION COMPLETE - FRESH INDEPENDENT REVIEW REQUIRED

This is an implementing-agent self-assessment only. It issues no approval
decision. Independent review and merge authorization remain with the reviewer
and the CTO.

[ja573]

CTRL-DELIVERY-01 canonical repository-map reconciliation — independent review

Decision: CHANGES REQUIRED

Reviewed exact head: f66ce2c7ed4dd4318d2fc944e8f66d7b51509ffc

Fresh independent review verified the implementation branch was created from exact authorized base ec7868a4a44b3d52da5638975995bb66a488b3b4, current thoth/develop remains at that exact base, PR #822 remains open/draft/mergeable, the whole PR changes exactly the four authorized paths, and the two-commit ancestry is clean (03dbf27f... directly from the authorized base; f66ce2c7... directly from 03dbf27f...). Final-head automatic CI is green; publish-to-dockerhub classified the diff as documentation-only and skipped build_and_push_staging_docker_image, so no staging-image publication occurred from this PR. The second commit that inserts PR #822 into CHANGELOG.md is not a blocking finding.

Four blocking findings remain:

1. Sphinx observed-state facts became stale before review

The source candidate records thoth-sphinx/develop as 7d6d4a24fde1ee0473f2ac66387167998f67ebb1 with compare/main...develop at ahead_by: 5. That was valid at implementation preflight, but is no longer current: Sphinx reconciliation PR #4 has since merged, and live thoth-sphinx/develop is now ff7de985d03f0c94d5ad8d60727f9cf85b6435cd; main remains 0896e4061e06bc640f917f1aaf25c14b6e25269a; compare is now ahead_by: 8, behind_by: 0, status: ahead. The only branch-content difference remains root AGENTS.md; the placeholder README remains unchanged and the repository still has zero workflows/no runtime/bootstrap/provider implementation.

Because this task exists specifically to reconcile canonical current-state records, the exact source head cannot be approved while branch-topology.md, repositories/thoth-sphinx.md, CHANGELOG.md, the PR body and #819 evidence retain the superseded 7d6d4a24 / ahead_by: 5 snapshot. Update the already-authorized source paths to the current post-PR-#4 state and record that the divergence consists of completed repository-control/reconciliation work, not runtime/bootstrap/branch normalization.

2. Additional required active-control paths were discovered, triggering the task's HOLD condition

The implementation correctly discovered two active, non-historical control documents outside the authorized write budget that still contradict the reconciled Sphinx state:

• docs/engineering/repository-map/control-gaps.md — active CG-03 still says main and develop contain only a placeholder README;
• docs/engineering/agent-instructions/rollout-plan.md — status IN PROGRESS; the Sphinx row still says placeholder-only README/no verified AGENTS.md and instructs adding AGENTS.md during bootstrap.

The CTO authorization for this reconciliation explicitly stated that an additional required write path is HOLD. No unauthorized file write occurred, which is good, but proceeding to IMPLEMENTATION COMPLETE instead of HOLD means the approved scope is now known to be insufficient for coherent programme reconciliation.

Required disposition: obtain explicit write-budget expansion for exactly those two paths (recommended) or an explicit CTO decision to leave those known active contradictions unresolved. Until then: HOLD ON MERGE.

3. Strapi pull_request trigger wording is over-broad

The trigger/outcome distinction is substantively correct and the publication-capable control is preserved, but the canonical candidate repeatedly says on: pull_request means "every PR open/update" or "opening or updating any PR" triggers the workflow. With no types: list, GitHub's pull_request event defaults to the opened, synchronize, and reopened activity types; it does not run on every possible PR metadata update.

Narrow the durable wording to the verified semantics, e.g. "opening/reopening a PR or updating/synchronizing its head triggers the publication-capable workflow; there is no path/docs-only exemption." Preserve push: true, staging-pr-*, trigger-vs-outcome, and the explicit authorization requirement. No workflow change is required or authorized.

4. Implementation-report evidence is incomplete, rather than requiring a new report file

Root AGENTS.md section 14 requires the implementation-report structure to be completed before review, including rollout and rollback. It does not require that evidence to live in a newly committed report file. Recording the equivalent report durably in the PR/#819 ledger is therefore acceptable under the bounded write budget, but the current #819 evidence omits explicit rollout and rollback fields.

Append evidence covering at minimum:

• rollout: merge of documentation/control records to develop only; no runtime/provider/deployment/activation effect;
• rollback: bounded repository revert of the documentation merge under separate authorization; no runtime rollback required;
• migration/database/API/auth-security effects: none for this documentation-only task.

Non-blocking verified evidence

• current thoth/develop is still the exact authorized base;
• PR CTRL-DELIVERY-01: reconcile canonical repository map with re-verified live state #822 is draft/open/mergeable at exact reviewed head;
• whole PR scope is exactly the four currently authorized files;
• no prohibited source path has been written;
• no manual CI, provider/runtime, release, deployment, activation or parent-CTRL-DELIVERY-01: Thoth-wide engineering task ledger and repository-local agent controls #818 mutation occurred;
• all four final-head automatic PR workflows completed successfully; heavy build/test/migration jobs were skipped by classification where applicable and the staging-image job was skipped;
• the Strapi trigger-vs-publication-outcome model itself is correct once the activity-type wording is narrowed.

Any source remediation creates a new exact head and invalidates this review.

Current gate: CHANGES REQUIRED — HOLD ON MERGE — WRITE-BUDGET EXPANSION / CTO DISPOSITION REQUIRED.

This review does not authorize source changes, write-budget expansion, PR ready-state transition, merge, manual CI, provider/runtime action, release, deployment or activation.

[ja573]

CTRL-DELIVERY-01 - review remediation

Previous reviewed head:
f66ce2c7ed4dd4318d2fc944e8f66d7b51509ffc

Review decision:
CHANGES REQUIRED - HOLD ON MERGE

Review comment:
5303663689

Remediation was performed on the existing task branch and PR #822 under explicit
CTO authorization expanding the write budget from four to six paths.

Finding 1 - Sphinx post-reconciliation live state

RESOLVED

Current verified state, independently re-verified before editing:

main     = 0896e4061e06bc640f917f1aaf25c14b6e25269a
develop  = ff7de985d03f0c94d5ad8d60727f9cf85b6435cd
ahead_by = 8
behind_by = 0
status   = ahead
content difference = root AGENTS.md only
README.md blob = ba19f1ba2a27adc8640691aea407aeb51b1a6f32 (identical on both)
workflows = 0

The superseded 7d6d4a24… / ahead_by: 5 snapshot is removed from all
committed records. Exact corrections:

• docs/engineering/repository-map/repositories/thoth-sphinx.md - the current
  state block now records main as the GitHub default branch still at the
  original placeholder commit with README.md alone, develop as the active
  development branch at ff7de985… carrying root AGENTS.md plus the
  unchanged placeholder README, and ahead_by: 8, behind_by: 0, status: ahead
  with AGENTS.md the only content difference. The divergence is recorded as
  completed repository-control and reconciliation work, explicitly not
  branch normalization, with no master branch established by it and no
  runtime/bootstrap/Cargo/CI/provider implementation on either branch. The
  BR-SPHINX-01 note about main being behind develop is updated to name the
  reconciliation commits too.
• docs/engineering/repository-map/branch-topology.md - the section 3.1
  re-verification note is corrected to the same current state and semantics. The
  observed-state row already described main as placeholder-README-only with
  develop ahead by the repository-control root AGENTS.md only, which remains
  accurate, and is left unchanged.
• CHANGELOG.md - the existing PR CTRL-DELIVERY-01: reconcile canonical repository map with re-verified live state #822 entry is updated in place to
  ff7de985 / ahead by eight commits, behind_by: 0.

Preserved semantics: main default and at the original placeholder commit;
develop active and carrying AGENTS.md plus the unchanged README; AGENTS.md
the only content difference; branches not identical; divergence is
repository-control/reconciliation history and not BR-SPHINX-01; no master
established; no runtime/bootstrap/Cargo/CI/provider implementation; repository
bootstrap-only and non-implementation-ready; BR-SPHINX-01 and
SPHINX-BOOT-01 separate and unimplemented; future bootstrap must
preserve/use/update the existing AGENTS.md rather than treat it as absent.

Exact SHAs are used only as verified current-state evidence; the records remain
durable state statements, not a chronological task log.

Finding 2 - additional active control files

RESOLVED

docs/engineering/repository-map/control-gaps.md:
CG-03 no longer states that main and develop contain only a placeholder
README. It now records the divergence (placeholder-only main; develop
carrying repository-local AGENTS.md plus the unchanged placeholder README),
that the repository still has no Cargo workspace, implementation, CI/workflow,
protections or runtime, and that BR-SPHINX-01 and SPHINX-BOOT-01 remain
required separate work. CG-03 is explicitly recorded as OPEN and is not
marked resolved: the presence of agent instructions satisfies none of its
closure criteria, and its programme-readiness meaning (complete both tasks
before WP6 or driver work) is preserved. The heading is corrected from
"is placeholder-only" to "is bootstrap-only"; it has no inbound cross-references
elsewhere in the repository.

The directly adjacent CG-05 listed Sphinx among repositories whose instructions
remain outstanding, which the merged repository-local AGENTS.md falsifies.
Only that Sphinx item is corrected, for internal consistency of the same
authorized file, with an explicit note that it closes the instruction item only
and closes neither CG-03 nor implementation readiness. App, dashboard, widget,
cc-license and Dissemination are untouched, and no other control gap is edited.

docs/engineering/agent-instructions/rollout-plan.md:
The thoth-sphinx row no longer says "placeholder-only README; no verified
AGENTS.md" and no longer instructs "add AGENTS.md". It now records that the
repository-local root AGENTS.md is merged onto develop and verified live,
that README.md remains the placeholder on both branches, that repository-local
instruction rollout is complete with no instruction-creation action remaining,
that SPHINX-BOOT-01 must preserve and build on the existing AGENTS.md rather
than add it as though absent and must replace or expand the placeholder README,
and that BR-SPHINX-01 remains separate. Rollout-sequence step 4 ("Add
thoth-sphinx instructions as part of its no-production bootstrap task") is
reconciled to match. The overall rollout programme, the other repository rows
and the remaining sequence steps are unchanged.

Finding 3 - Strapi trigger wording

RESOLVED

build_docker.yml was re-read on thoth-strapi develop and still declares
on: pull_request with no explicit types: list, plus workflow_dispatch
separately, ghcr.io login, docker/build-push-action@v5, push: true and the
staging-pr-* tag, with no paths/paths-ignore and no docs-only classifier.

The default pull_request activity types therefore apply: opened,
reopened, synchronize. All over-broad wording is replaced with durable
wording equivalent to:

Opening or reopening a pull request, or synchronizing/updating its head,
automatically triggers the publication-capable build_docker.yml workflow.

The record now states the verified activity types explicitly and declines to
claim that every possible PR metadata event triggers the workflow. A sweep of
the six files for "every PR", "every PR update", "every PR event", "any PR
update", "every pull request update", "PR open/update" and "every open/update"
returns zero matches.

Preserved control consequences: documentation-only head changes are not exempt;
no path filter exists; every qualifying event automatically starts the workflow;
push: true and staging-pr-* are configured; the run is publication-capable;
successful runs publish; a run may fail before publication; the publication
result must be observed rather than assumed; pull-request-mutation authorization
is still required; manual workflow_dispatch is distinct; release publication
is distinct; provider/runtime action is distinct; deployment and activation are
distinct. No workflow file was modified in any repository.

Finding 4 - implementation-report completeness

RESOLVED

No implementation-report file was created; no such path is authorized. The
required structure is recorded durably in the PR #822 body and here.

• database/migration: NONE
• API/GraphQL/runtime contract: NONE
• auth/security implementation: NONE
• rollout: after merge, the corrected canonical control documentation becomes
  repository-authoritative on develop. No deployment, migration, runtime
  activation, provider action or branch normalization follows automatically. The
  documentation does not itself authorize BR-SPHINX-01, SPHINX-BOOT-01,
  Strapi CI repair or any other follow-up.
• rollback: before any downstream reliance requiring the corrected record,
  rollback is a normal repository revert of this documentation-only PR under
  separate normal authorization and review. There is no runtime rollback,
  migration rollback, provider rollback or data repair, because this task
  changes no runtime or external state.
• known limitations / deferred work: BR-SPHINX-01 remains separate and
  unimplemented; SPHINX-BOOT-01 remains separate and unimplemented; the
  thoth-strapi Docker/Node CI defect remains a separate concern, recorded and
  not repaired; no provider or runtime deployment state was verified or changed
  by this task; historical implementation reports remain historical and are not
  rewritten; docs/metrics/README.md also carries a "placeholder-only" Sphinx
  phrasing but is outside the authorized write budget and is left untouched,
  flagged here for separate scoping.
• automatic/manual effects: recorded under "Automatic CI" below. Automatic PR CI
  only; no manual CI; no provider or registry action.

Repository state

Authorized base:
ec7868a4a44b3d52da5638975995bb66a488b3b4

Previous head:
f66ce2c7ed4dd4318d2fc944e8f66d7b51509ffc

New head:
08a700ecad7e4c9de8cfe561eaa08c23be0813cc

New commit:
08a700ecad7e4c9de8cfe561eaa08c23be0813cc docs: reconcile control map after Sphinx closeout (#819)

Both earlier commits are preserved unchanged:

03dbf27f  CTRL-DELIVERY-01: reconcile canonical repository map with live state (#819)
f66ce2c7  CTRL-DELIVERY-01: reference PR #822 in the changelog entry (#819)
08a700ec  docs: reconcile control map after Sphinx closeout (#819)

No amend, rebase, squash, history rewrite or force-push. origin/develop was
re-verified as still exactly ec7868a4a44b3d52da5638975995bb66a488b3b4
immediately before the push, and the push was a fast-forward
f66ce2c7..08a700ec.

Files changed

Remediation diff (f66ce2c7 -> 08a700ec) and whole task diff
(ec7868a4 -> 08a700ec) are the same six paths:

M  CHANGELOG.md
M  docs/engineering/agent-instructions/rollout-plan.md
M  docs/engineering/repository-map/branch-topology.md
M  docs/engineering/repository-map/control-gaps.md
M  docs/engineering/repository-map/repositories/thoth-sphinx.md
M  docs/engineering/repository-map/repositories/thoth-strapi.md

New files:
NONE

Deleted/moved/renamed:
NONE

No workflow files. No source or runtime files. No seventh source path.

Validation

git diff --check
  -> clean, exit 0

git diff --name-status f66ce2c7ed4dd4318d2fc944e8f66d7b51509ffc HEAD
  -> exactly the six authorized paths, all M

git diff --name-status ec7868a4a44b3d52da5638975995bb66a488b3b4 HEAD
  -> exactly the same six paths, all M; no A, D or R entries

git status --porcelain (post-commit)
  -> clean

• Markdown link/path check across all six files: every relative markdown link
  resolves, including the new ./repositories/thoth-sphinx.md reference added
  in control-gaps.md. The only unresolved references are pre-existing bare
  basename shorthands inside historical CHANGELOG.md entries (for example
  operating-model.md, release-gates.md, repository-map/README.md); these
  are that file's established convention rather than links, predate this branch
  and are untouched.
• Stale-Sphinx sweep of the six files for 7d6d4a24, ahead_by: 5, "ahead by
  five", "branches identical", "both contain only", "no verified AGENTS",
  "add AGENTS", "placeholder-only README": zero blocking matches. Every
  remaining "identical" match was classified as a corrected current statement -
  "main and develop are therefore not identical", the "identical
  README.md blob" evidence, and the supersession notes that name the earlier
  claim in order to correct it. No historical evidence was blindly removed.
• Over-broad Strapi sweep of the six files: zero matches for "every PR", "every
  PR update", "every PR event", "any PR update", "every pull request update",
  "PR open/update", "every open/update". Current normative wording uses
  opened/reopened/head-synchronize semantics.
• Line-wrap check: no hyphen-broken compound words introduced.

No Rust gate was run: the diff contains no Rust, schema, migration, workflow or
manifest change, and root AGENTS.md section 8 prescribes git diff --check
plus link/terminology/changelog/CI review for documentation-only changes.

Automatic CI

The push triggered normal automatic pull_request CI at head 08a700ec. Four
runs, all completed success:

Run ID	Workflow	Status	Conclusion	Jobs
31902120964	build-test-and-check	completed	success	classify success; lint skipped; test skipped; build skipped; format_check skipped
31902120950	run-migrations	completed	success	classify success; run_migrations skipped
31902120910	publish-to-dockerhub	completed	success	classify success; build_and_push_staging_docker_image skipped
31902120913	check-changelog	completed	success	check-changelog success

Build, test, lint, format and migration jobs were skipped: this remediation
diff touches only CHANGELOG.md and paths under docs/, so
classify_ci_changes.py classified it as documentation-only. (This differs from
CTRL-REPO-THOTH-01, whose diff also touched root AGENTS.md and therefore did
not classify as documentation-only.)

build_and_push_staging_docker_image: SKIPPED.

External publication:
NONE. Evidenced by the skipped build_and_push_staging_docker_image job
conclusion in run 31902120910, not inferred from the workflow trigger. No
registry or provider interface was queried.

Manual CI:
NONE. No dispatch, no rerun, no cancellation, no workflow change.

Provider/runtime action:
NONE.

No unexpected external effect occurred.

Authorization compliance

Actions used: repository and GitHub reads; modification of the six authorized
paths only; local documentation validation; one new commit on the existing task
branch; one push of the existing task branch; update of the existing draft PR
#822; this append-only evidence comment on #819; observation of the automatic PR
CI through GitHub evidence only.

Unauthorized actions:
NONE

Deviations:
NONE

Specifically not performed: seventh source path; new files; delete/move/rename;
rebase; amend; squash or history rewrite; force-push; branch normalization;
workflow or CI implementation change; manual workflow dispatch; manual CI
rerun/cancel; provider/runtime read or write; registry query or action;
release/tag/publication action beyond the automatic PR workflow effect;
deployment; migration execution; production activation.

Parent #818 mutated:
NO

PR ready-state transition:
NO - PR #822 remains OPEN and DRAFT, base develop, head 08a700ec.

Merge:
NO

Previous evidence comments were not edited; this comment is appended.

Gate

RECONCILIATION REMEDIATION COMPLETE - FRESH INDEPENDENT REVIEW REQUIRED

The prior review was bound to head f66ce2c7… and is invalidated by the new
commit. No approval is claimed and none is self-issued. Programme #818 is not
claimed complete and is not mutated.

[ja573]

CTRL-DELIVERY-01 reconciliation - fresh independent review

Reviewed exact head: 08a700ecad7e4c9de8cfe561eaa08c23be0813cc

Decision: APPROVED

This approval is bound only to the exact reviewed source head above. Any new source commit invalidates it.

Scope / ancestry

• PR CTRL-DELIVERY-01: reconcile canonical repository map with re-verified live state #822 is open, draft and mergeable, targeting develop.
• PR head is exactly 08a700ecad7e4c9de8cfe561eaa08c23be0813cc.
• Live thoth/develop remains exactly the authorized base ec7868a4a44b3d52da5638975995bb66a488b3b4.
• Remediation commit 08a700ec... is a direct child of previously reviewed head f66ce2c7ed4dd4318d2fc944e8f66d7b51509ffc; no rebase/history rewrite is evidenced.
• Whole PR diff is exactly six modified files and no additions/deletions/renames:
  • CHANGELOG.md
  • docs/engineering/agent-instructions/rollout-plan.md
  • docs/engineering/repository-map/branch-topology.md
  • docs/engineering/repository-map/control-gaps.md
  • docs/engineering/repository-map/repositories/thoth-sphinx.md
  • docs/engineering/repository-map/repositories/thoth-strapi.md

Finding 1 - Sphinx current state

RESOLVED. Fresh live verification confirms:

main     = 0896e4061e06bc640f917f1aaf25c14b6e25269a
develop  = ff7de985d03f0c94d5ad8d60727f9cf85b6435cd
ahead_by = 8
behind_by = 0
status   = ahead
workflows = 0

The reviewed records correctly state that main remains the original placeholder branch, develop carries root AGENTS.md plus the unchanged placeholder README, the root AGENTS.md is the only content difference, and the divergence is repository-control/reconciliation history rather than BR-SPHINX-01 normalization or SPHINX-BOOT-01 implementation. No runtime/Cargo/CI/provider/bootstrap state is falsely claimed.

Finding 2 - additional active control files

RESOLVED for the authorized Sphinx reconciliation. control-gaps.md CG-03 now accurately records Sphinx as bootstrap-only and remains OPEN; CG-05 no longer treats Sphinx instructions as outstanding. agent-instructions/rollout-plan.md now records the merged Sphinx root AGENTS.md and correctly requires future bootstrap to preserve/build on it rather than add it as absent.

Finding 3 - Strapi event semantics

RESOLVED. Live thoth-strapi/develop still has build_docker.yml with on: pull_request and no explicit types, no path filter/docs-only classifier, workflow_dispatch separately, GHCR login, docker/build-push-action@v5, push: true, and staging-pr-* tags. Current GitHub Actions documentation confirms that with no types: the default pull_request activity types are opened, synchronize, and reopened. The reviewed wording now uses those exact semantics rather than claiming every possible PR metadata update triggers the workflow, while preserving the publication-capable/trigger-vs-outcome authorization rule.

Finding 4 - implementation-report evidence

RESOLVED. The PR/#819 evidence now explicitly records database/migration, API/GraphQL/runtime, authorization/security, automatic/manual effects, rollout, rollback, limitations/deferred work, validation and authorization compliance. No unauthorized implementation-report file was created.

CI / automatic effects

Exact-head automatic PR CI is complete:

• 31902120964 build-test-and-check: success; classifier success; lint/test/build/format skipped.
• 31902120950 run-migrations: success; migration job skipped.
• 31902120910 publish-to-dockerhub: success; build_and_push_staging_docker_image skipped.
• 31902120913 check-changelog: success.

No staging-image publication occurred from this exact head because the publication job itself was skipped. No manual CI action, provider/runtime action, release, deployment, migration execution or activation is evidenced.

Non-blocking findings outside this exact remediation

1. docs/metrics/README.md still says thoth-sphinx is "placeholder-only". That is now stale as an observed-state description. It belongs to the distinct Metrics programme and was outside this task's authorization; it must be separately scoped/reconciled before Metrics work relies on that programme control surface. It is not folded into this Shared Engineering Control PR.

2. The older shared control-gaps.md / agent-instructions/rollout-plan.md contain broader pre-existing rollout-status drift unrelated to the authorized Sphinx/Strapi remediation: App repository-local control is already merged/authoritative (thoth-app#113 / PR Feature/publications pagination #114), and Dissemination repository-local control is already merged/authoritative (thoth-dissemination#95 / PR Connect with IFLA and LIBER to discuss non-Latin script metadata input #96), while those old status records still describe App instructions as outstanding and Dissemination controls/instructions as incomplete. This exact PR did not introduce those statements and the CTO remediation authorization was specifically bounded to current Sphinx state plus Strapi event semantics, so they do not invalidate the reviewed source change. They must, however, be reconciled or the old status records explicitly superseded before parent CTRL-DELIVERY-01: Thoth-wide engineering task ledger and repository-local agent controls #818 is closed, so the parent programme is not yet closure-ready solely because CTRL-DELIVERY-01: reconcile canonical repository map with re-verified live state #822 is approved.

Decision / gate

APPROVED at exact source head 08a700ecad7e4c9de8cfe561eaa08c23be0813cc.

This is source/stage approval only. It does not authorize marking PR #822 ready, merge, parent #818 mutation/closure, child-issue closure, branch deletion, release, deployment, provider action, migration execution or production activation.

Next gate for PR #822: explicit CTO merge authorization bound to exact reviewed head 08a700ecad7e4c9de8cfe561eaa08c23be0813cc, subject to immediate live integration-state recheck.

Programme closeout remains separate: after any authorized merge of #822, reconcile/supersede the broader stale shared rollout-status records and separately route the Metrics README correction through the Metrics programme before deciding #818 closure.