CTC Project Operations¶

Status: CANONICAL CURRENT
Owns: repository writes, one-writer integration, Git delivery, DB compatibility Gate, Wiki sync, external-effect separation, rollback/readback and branch parity
Does not own: Product/Process scope, Task activation, current Runtime/DB facts, restriction decisions or test content
New-System Roadmap: ../../new-system/docs/ROADMAP.md

1. Git Contract¶

qa = integration/review
master = release

QA_COMMIT_PUSH
-> MASTER_MERGE
-> MASTER_PUSH
-> RETURN_TO_QA
-> VERIFY_QA_CHECKOUT
-> PROMOTION_TAG

In this repository, deploy means the complete sequence above. An explicit user request to deploy authorizes the qa commit/push, the qa → master merge/push and return to the existing qa branch in the same delivery; do not stop after QA push or ask for another promotion confirmation. SHA/tree readback is internal verification, is not an additional deployment step or user requirement. deploy, deploy it and similar Git delivery wording do not authorize any New-System build, artifact or service command on a Production host.

For normal development delivery, complete the relevant repository/Task validation and scoped diff review before creating the delivery commit or pushing it. Do not use intermediate progress commits as a substitute for validation; the coordinated session change is one final scoped commit by default. The explicit deploy only/Production-incident exception below is for already-local changes and does not redefine the normal development workflow.

When the user requests deployment for an active Production incident or otherwise directs "deploy only", start the Git delivery sequence immediately. Do not insert investigation, implementation, lint, other tests, audit, documentation, task work, browser checks, or scope redesign before promotion. Perform only the minimum Git safety needed to send the already-local changes (current status, the exact-tree FOR UPDATE gate in Section 3, exact commit/push, and remote SHA readback); defer every other check or follow-up until after deployment unless it is needed to prevent pushing the wrong ref or rewriting history.

Use the current checkout. Do not create a branch, worktree or stash unless explicitly requested by the user; release isolation is not an exception. No force-push, hard reset, history rewrite or direct master-only source commit as routine delivery. If an explicitly authorized temporary branch, worktree or stash is used, its cleanup is a required same-delivery step: after qa/master parity, remove it, prune stale worktree metadata, and read back that the temporary ref and checkout are absent before reporting deployment complete. Never retain it for a future release unless the user explicitly asks to keep it.

1.1 Promotion tag¶

PROMOTION_TAG is the same-delivery step that names the exact master commit a promotion delivered, so "which commit was released, and when" stays answerable from the repository itself.

node scripts/ctc-release-tag.mjs            create locally, do not push
node scripts/ctc-release-tag.mjs --push     create, push, read back from the remote
node scripts/ctc-release-tag.mjs --dry-run  print the decision only

Naming: promotion/<master commit UTC>-<7-char SHA>, annotated. Derived only from the promoted commit, so it needs no human naming decision and cannot drift from what was actually released.
Idempotent: when master already carries a promotion tag, the step reports skip and creates nothing. One tag per promotion.
Forward only. Existing history is not back-tagged. Choosing which past merge was "the release" is a judgement this rule does not make; any past state is already recoverable from the repository.
Tags are never moved, retargeted, force-updated or deleted. A rollback is recorded as new state; it does not rewrite the release record.

A promotion tag is deliberately not any of the following:

not a semantic version. This repository has no version authority, so a vN.M.P line would manufacture one.
not approval, not Production state, not deployment completion, not DB or migration state.
not a branch alias and not a substitute for qa/master parity.

Creating and pushing the tag is a Git delivery effect only. Section 4 separation is unchanged: it authorizes no build, artifact, service, provider, DB, Wiki or Physical operation. It also does not authorize Production New-System work, which Section 6.1 keeps prohibited under its own separate authority.

If the tag step cannot complete, report it as its own incomplete item with the exact reason. Do not report a promotion as fully delivered while the naming step is outstanding, and do not let an unconfirmed tag become a reason to claim the release is unverified.

Already-delivered code¶

Before creating a deployment commit, compare the exact scoped source with prior shared-Task delivery commits, remote qa/master and the actual serving file or artifact. Task numbers alone do not identify new deployable work. Preserve unrelated dirty changes; do not include them to manufacture a diff.

If the exact source and required dependencies are already delivered and verified for the requested runtime, do not recommit/cherry-pick, repeat migrations, redeploy or restart services for the same code. Record the original delivery commit, shared Task, candidate hash and fresh runtime readback in the child Task. On an explicit deployment request, verified existing delivery can complete that Task's COMMITED tracking; say that existing delivery was confirmed and no new deployment occurred. A review alone does not change DONE to COMMITED. No-effect work with no actual prior delivery remains DONE with delivery NOT_APPLICABLE.

Source equality alone does not prove DB migrations or a built/running artifact. Verify each required effect separately; if different or unverified, deliver only the authorized difference after its gates. For a verified no-op, there is no new commit/push candidate: do not claim a new Git promotion or bypass gates for unrelated changes. Still verify remote parity, current qa checkout and deployment-complete.

Mandatory return to qa¶

After a deployment the working branch must be qa. This is a user instruction that applies to every executor, including Codex and OpenCode, and not a recommendation. As the one exception to keeping the current checkout and to the ban on switching branches arbitrarily, the deployment request itself approves the return to the existing qa. It does not ask for separate confirmation and does not continue the next piece of work on master.

Confirm the deployed SHA of the remote qa/master. A successful remote push alone is not a declaration of deployment completion.
Return with git switch qa while preserving uncommitted, staged and untracked changes. Run the checks below even when already on qa.
Read git branch --show-current and git status --short again and confirm that the existing changes are preserved.
Run node .agents/harness/validate.mjs --deployment-complete at the repository root. This check judges the current branch only and does not replace remote deployment, DB or service verification.
Report deployment completion and start the next piece of work only after the check passes. Include current branch: qa in the final report.

On a return conflict or failure, or if the check fails, report git push complete / return to qa BLOCKED. A forced switch, and discarding changes with reset, clean or stash, or completing while omitting the check result, are not permitted. Resolve the return first.

QA branch/worktree cleanup¶

After pulling or updating qa, automatically inspect local refs and worktrees against the updated qa tip. Exclude master, the current qa checkout, and remote refs. For a local branch whose tip is already merged into qa, remove its linked worktree only when that worktree is clean, then delete the local branch with the non-force delete path. For a detached worktree whose HEAD is already merged into qa, remove it only when clean. Preserve and report any dirty worktree or branch; never use force deletion or git clean as part of automatic cleanup. Run worktree metadata pruning and read back the remaining branches/worktrees after cleanup. This cleanup does not delete remote branches and does not resolve or discard local source changes.

When a user explicitly requests pulling with local changes and that update cannot proceed otherwise, preserve them with one named temporary stash (including staged and untracked files), update the requested remote branch(es), then immediately restore it before any other work. Use git stash apply --index, inspect the working tree and staged diff, then git stash drop in the same delivery. Never create a stash for context switching, release isolation, work preservation or deferred recovery. If restoration conflicts, do not create another stash or continue other work: resolve the conflict while retaining the original stash, and drop it only after successful restoration and verification. Do not use git reset, git clean, force checkout or discard/overwrite local changes.

2. Startup Before Write¶

update local qa and master from their remotes before each qa commit/push and master merge/push; reconcile the exact scoped diff locally before committing/pushing;
read scoped AGENTS/current NS Task/Roadmap;
pin exact allowed paths and one writer;
inspect current source/concurrent changes;
classify restriction and current positive paths;
classify exact DB dependency;
classify Wiki/user-procedure impact;
classify config/provider/file/device/route/writer/service/physical effects;
define checks, readback, rollback and knowledge updates;
preserve unrelated work.

3. DB Compatibility Gate¶

Before qa push classify:

NOT_REQUIRED
APPLIED_AND_VERIFIED
REQUIRED_NOT_APPLIED
REQUIRED_STATUS_UNKNOWN
BACKWARD_COMPATIBLE_STAGED

If a required Production migration is absent/unknown, return DB_MIGRATION_CONFIRMATION_REQUIRED before qa push.

No known schema-incompatible source reaches master without the exact migration/readback decision.

Before creating a source delivery commit, assemble the exact intended Git tree, including its base and only its scoped changes, and run php scripts/tests/unit/no_for_update_runtime_contract_test.php against a snapshot of that tree. An earlier repository-wide cleanup, a PASS from a shared dirty working tree, or a check of changed files alone does not certify the candidate. If the base already fails, repair and validate that violation in its own scope before promoting a dependent candidate; never label it an accepted baseline or silently include unrelated repairs in a table Task.

After the commit, run the same gate against the committed HEAD tree before qa push. If either exact tree fails, stop that candidate's commit/promotion, record the offending paths, and fix the owning scope. This no-exception SQL prohibition includes Legacy, New-System and executable maintenance/migration scripts. Do not remove scans or alter test expectations to accept the clause.

4. Effect Classes¶

Separate:

repository source/doc change
Git delivery
restriction policy
DB compatibility decision
DB schema/data
tenant/config/account
provider/file/device
Wiki sync/publication/access
NS5 route/canary
NS5 command writer
New Web/Worker service/release
Legacy retirement
physical operation

One class never authorizes another.

5. New-System Knowledge Gate¶

A New-System source change is not ready for final integration when affected Process/module/page/data/interface docs, structured catalog, Source Registry or Task context would be stale or misleading.

Generated projections may be regenerated after source integration, but they do not replace reviewed updates.

6. Deployment¶

Current PHP Production pulls master on the established two-minute cycle; routine PHP restart/manual pull remains NOT_APPLICABLE.

New Web/Worker/UI Catalog build/start/stop/reload/artifact/reverse-proxy/canary is a separate exact infrastructure/release effect.

6.1 Production New-System command moratorium¶

Until the user separately and explicitly authorizes an exact Production New-System operation in a later current message, every Production-host New-System build and deployment command is PROHIBITED. This includes next build, pnpm build, dependency installation, artifact creation/copy, release symlink switching, release-environment edits, and service start/stop/restart/reload. Keep the currently running artifact and service untouched.

Do not derive this authority from deploy, deploy it, do it all, keep going, an active Task, handoff, runbook, old approval, earlier deployment, or the existence of release tooling. Only a new direct user instruction that separately names the Production New-System operation can lift this moratorium for that exact operation. This section supersedes any Task or handoff text that previously treated Git delivery as authority for Production artifact installation.

6.2 QA Logistics Workspace External Access¶

When the user explicitly requests access through the existing QA host ctc-qa.duckdns.org/logisticsWorkspace, that single request authorizes the additive QA route mapping, the trusted local proxy protocol header, the existing QA Web service reload, and read-only /health//ready DB and migration verification. Do not ask again for those same scoped steps. This standing scope does not authorize Production exposure, schema/data writes, credential changes, or unrelated service changes.

7. Wiki¶

User-facing normal steps/inputs/results/errors/retry/recovery/role/handoff changes classify exact Wiki impact and follow the current Wiki policy. Internal technical/catalog updates are not user Wiki publication.

8. Completion Report¶

State:

work track, Task and actual evidence level;
deployment commit and remote push result;
promotion tag name and remote readback result (skip when master was already tagged);
final checkout qa, deployment-complete check result and preserved local changes;
changed paths/owners;
checks;
restriction and positive paths;
DB dependency/migration;
Wiki/knowledge updates;
route/writer/service/provider/physical effects;
Runtime/role/field evidence;
rollback/residual risks.

Do not report above established evidence.¶

Source: .agents/rules/PROJECT_OPERATIONS.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.