Status: draftCreated: 2026-06-30Last updated: 2026-07-05

Document Scope

This document governs how repository files are inspected, patched, refactored, verified, handed to Codex when appropriate, and preserved in durable project state across the modular workspace. It is written for human operators, future ChatGPT sessions, Codex sessions, AI-assisted development tools, automation workers, and future MCP or RAG systems that need to understand how controlled changes are made in the active repository named for a task.

The modular workspace contains multiple repositories under <workspace-root>, including known repositories such as <workspace-root>/app, <workspace-root>/site, <workspace-root>/admin, and <workspace-root>/server, plus future active repositories under <workspace-root>. This standard applies to scripts, monitoring tools, operations workers, report modules, platform adapters, configuration templates, migration files, CI/CD pipeline configuration, documentation, state records, and future services inside the named repository. It does not treat <workspace-root>/app as the whole project, and it does not authorize casual edits outside the repository named in a task prompt.

This document supersedes docs/2026.06.04_project_file_update_and_patching_workflow.html together with docs/runtime-validation-standard.md. This document does not replace product runbooks, database migration rules, production launch procedures, runtime validation rules, CI/CD pipeline standards, or provider-specific deployment manuals. It defines the controlled change workflow for the active repository. When another runbook requires stronger restrictions for a specific subsystem, the stricter rule controls.

1. Purpose

The purpose of this standard is to make repository changes understandable, repeatable, reviewable, and recoverable. The project uses a large and growing codebase with scripts that affect feed processing, Telegram posting, AI provider calls, operational reports, database state, monitoring, and future customer-facing services. A small change can be technically valid in isolation but unsafe in the broader system if it is not inspected, verified, and recorded.

This document preserves the older standard patch-helper and verify-helper workflow. That workflow remains valid and should continue to be used when it is the safest way to apply a deterministic change. This document also adds the bounded Codex-assisted implementation workflow as an additional approved process. Codex can make local file edits directly when the task is narrow, the allowed files are explicit, the validation commands are known, and a durable handoff is required.

Neither workflow removes the need for careful verification. Codex is not a substitute for inspection. Patch helpers are not a substitute for runtime checks. A future AI session must treat every change as untrusted until the repository state, diff, validation output, and handoff record have been reviewed.

2. Core Rule

The core rule is simple: the project uses user-supervised changes. Nothing should be silently edited, silently committed, silently deployed, silently promoted, or silently treated as safe.

A safe change has a visible scope, a reason, a file list, an implementation method, validation output, Architectural Impact Review where repository work is involved, and a final status. If any of those pieces is missing, the assistant should stay in inspection mode or ask for the missing information. The goal is not to slow the project down with ceremony. The goal is to keep the project recoverable while many tools, humans, and AI sessions collaborate across time.

This rule applies even when the change is small. A one-line compatibility wrapper, a documentation update, a verifier adjustment, or a config-template edit can still create confusing project history if it is not bounded and recorded.

3. Approved Workflows

There are two approved workflows for ordinary repository file changes.

The first approved workflow is the standard patch-helper and verify-helper workflow. In this process, an AI assistant inspects the repository, writes a deterministic patch helper under the repo-local tmp directory, writes a separate verification helper under the repo-local tmp, gives the user a short command block, and waits for pasted output. The patch helper modifies files. The verify helper checks that the patch landed correctly and should not modify project files.

The second approved workflow is the Codex-assisted bounded implementation workflow. In this process, Codex receives a prompt that names the repository, branch, required context files, exact task, allowed files, forbidden files and actions, validation commands, handoff-file requirements, and final status expectations. Codex may then edit the approved files directly, run approved validation commands, and create a durable handoff file under repo-local state when that repository has a state directory or when the task creates one with approval.

These workflows are complementary. The standard patch-helper workflow provides maximum deterministic control and is especially useful when the user wants to run every file mutation personally. The Codex workflow is useful when the implementation is bounded and local, and when Codex can inspect, edit, validate, and write a detailed state handoff in one controlled session.

3.1 Repository Classification Preflight

Before either approved workflow begins, the assistant must identify the active repository and repository class. The task prompt, patch helper, verification helper, or Codex prompt must not treat <workspace-root> as one repository and must not assume that app, site, admin, server, ctx-*, or a utility repository have the same safety profile.

Repository classification controls allowed file scope, validation depth, CI/CD review, state-record requirements, supply-chain review, and whether deployment or infrastructure mutation is even eligible for the task. If the repository class is uncertain or the task appears to cross classes, the assistant must stop and ask before implementation.

4. CI/CD Pipeline Configuration Rule

CI/CD pipeline configuration is high-impact repository automation.

A pipeline file can run commands, consume secrets, publish artifacts, deploy services, modify infrastructure, run database migration commands, or mutate environments. It must not be edited casually by ChatGPT, Codex, patch helpers, or another AI-assisted tool.

A task that creates or changes pipeline configuration must explicitly define:

repository path,
branch,
pipeline file path,
allowed stages,
allowed jobs,
forbidden jobs,
whether deployment is allowed,
whether production is out of scope,
whether secrets or protected variables may be referenced,
expected runner environment,
validation method,
expected pipeline behavior after push.

If those details are missing, pipeline work is not ready for implementation.

4.1 Supply Chain Boundary for Patch and Codex Work

Patch helpers and Codex sessions may not introduce external artifacts unless the task explicitly includes supply-chain evaluation and the operator approves the artifact decision status.

Codex must not add packages, change lockfiles, pull container images, add CI/CD includes, download scripts, install local tools, add MCP servers, add AI models, copy external source, or mirror new reference material as an incidental implementation choice. If Codex discovers that a new artifact may be needed, Codex must stop and report the candidate artifact, the operational need, and the current approved-stack alternatives. The operator decides whether to start a supply-chain evaluation.

When a scoped task already includes an approved artifact, the Codex prompt must name the approved artifact, approved version or immutable reference where applicable, allowed files, required records, and validation commands.

For ordinary repository tasks, the assistant must still consider pipeline impact before commit readiness. The answer may be that no pipeline change is required, but the review must happen.

Architectural Impact Review Standard

Repository work must include an Architectural Impact Review before commit readiness. The review is broader than CI/CD. CI/CD pipeline impact remains mandatory, but it is one part of a larger checkpoint that asks whether the completed work changed, weakened, contradicted, or exposed anything else that should be fixed before the repository checkpoint is created.

The Architectural Impact Review is not merely an information-gathering exercise. After the review identifies an affected area, the assistant or coding agent must decide whether the issue can be addressed safely inside the current task scope before the commit. If it can be fixed safely and the file scope allows it, the fix should be made and validated before commit. If it cannot be fixed safely, is outside the approved file scope, requires operator approval, touches production, requires a separate branch, or would mix unrelated work into the checkpoint, it must be recorded as a generated follow-up task with enough context for a future human, AI session, automation worker, or operations database process to act on it.

Before commit readiness, ask the following questions in full and answer them based on the actual diff, validation output, repository class, and task scope:

Did dependencies, dependency groups, lockfiles, package manager configuration, Python version files, Node package files, or build-tool files change?
Did the approved Python runner, script execution method, project metadata, virtual environment assumptions, or local setup instructions change?
Did linting, formatting, type-checking, test discovery, test commands, test fixtures, or validation commands change?
Did package layout, module layout, imports, entry points, service boundaries, script locations, or runtime command paths change?
Did startup commands, worker commands, scheduler commands, service names, process names, ports, hostnames, tunnels, local preview routes, or health-check routes change?
Did configuration loading, settings models, environment identity, environment variables, example configuration files, secret names, protected variables, or ignored private files change?
Did database access, query behavior, transaction handling, schema, migration files, seed data, staging/production separation, or database safety assumptions change?
Did object storage behavior, report artifact paths, stable links, retention behavior, backup behavior, archive behavior, or recovery procedures change?
Did API routes, request models, response models, authentication checks, authorization checks, OpenAPI output, dashboard contracts, or frontend/backend integration expectations change?
Did frontend build behavior, static-site generation, public assets, internal dashboard behavior, browser-visible routes, accessibility behavior, or customer-facing copy change?
Did Telegram intake, processing, deduplication, AI rewriting, delivery, channel routing, customer-visible output quality, or provider-call behavior change?
Did email, alerting, notifications, operational reports, incident creation, remediation jobs, or AI-agent work queues change?
Did monitoring, Watchdog, Deep Audit, logs, metrics, operations records, health checks, failure reporting, or observability expectations change?
Did deployment behavior, release behavior, rollback behavior, staging behavior, production behavior, infrastructure mutation, or manual deployment gates change?
Did repository structure, documentation structure, context/reference library structure, generated documentation, README material, runbooks, handoff files, or operator procedures change?
Did CI/CD pipeline configuration, pipeline stages, jobs, images, caches, artifacts, runner assumptions, pipeline variables, protected variables, deployment gates, or expected pipeline behavior after push change?
Did Docker, Compose, container build assumptions, .dockerignore, image startup commands, container environment variables, mounted paths, exposed ports, health checks, or container validation need to be created or updated because of the work?
Did Kubernetes, service manifests, deployment manifests, secrets handling, config maps, ingress, jobs, cron jobs, probes, namespaces, or cluster deployment assumptions need to be created or updated because of the work?
Did the work create or reveal any security, privacy, access-control, secret-handling, production-safety, customer-impact, or data-retention concern?
Did the work create or reveal any documentation mismatch, stale standard, stale runbook, stale local command, stale Codex prompt template, stale validation command, or stale startup instruction?
Did the work reveal a repetitive manual step that should become a helper script, verifier, CI/CD job, documentation rule, runbook step, or future automation-worker task?
Did the work reveal a weakness, ambiguity, missing safeguard, or process gap in the project standards, repository workflow, validation model, commit-message model, or AI-agent operating instructions?
Which of the identified issues can be fixed safely before this commit without broadening the task improperly?
Which identified issues must be recorded as generated follow-up tasks, and what exact future action should be taken?
What should the operations database or future AI-worker layer be able to extract from this checkpoint?

Use this compact review format before commit readiness:

Architectural impact review:
- Repository class:
- Runtime behavior changed: yes/no.
- Validation behavior changed: yes/no.
- Configuration or secrets changed: yes/no.
- Database or persistent state changed: yes/no.
- API, frontend, dashboard, or customer-visible contract changed: yes/no.
- Monitoring, operations, reports, or AI-agent records changed: yes/no.
- CI/CD impact: yes/no.
- Docker impact: not adopted/no/yes/follow-up.
- Kubernetes impact: not adopted/no/yes/follow-up.
- Deployment or infrastructure impact: yes/no.
- Documentation or runbook impact: yes/no.
- Immediate fixes made before commit:
- Follow-up tasks generated:
- Reason unresolved items were deferred:

The review must be written in full, human-readable sentences when entered into a commit message, merge commit message, Codex handoff, or state handoff. Short labels may be used in the pre-commit working summary, but the durable record must preserve enough context for later recovery, operations database ingestion, and future AI-agent action.

Workflow Weakness and Safeguard Review

Every commit must explicitly answer this question:

Has this commit revealed a weakness, ambiguity, missing safeguard, or repetitive manual step in the project standards or workflows?

This answer must not be buried inside a generic risk section. It must be recorded as its own subsection in the commit message or merge commit message. If the answer is yes, the assistant or coding agent must identify what created the weakness, where it exists, why it matters, whether it was remediated before commit, and what follow-up remains. If the answer is no, the durable record must say that no workflow weakness, ambiguity, missing safeguard, or repetitive manual step was identified from this change.

When a weakness or repetitive manual step is identified, the assistant must immediately ask whether it can be safely fixed before commit. The default action is to fix it now when the fix is inside scope, low risk, validated, and does not mix unrelated work into the checkpoint. If the fix is not safe to include now, it must become a generated follow-up task, not an informal note.

5. When to Use the Standard Patch and Verify Helper Workflow

Use the standard patch-helper and verify-helper workflow when deterministic local patching is the safest control surface. This is still the preferred workflow when Codex is unavailable, when the user wants fully controlled local patch files, when an assistant is operating through a normal chat session without direct file-edit access, or when a dangerous area needs exact scripted anchors.

This workflow is also appropriate for tiny changes where a small anchored helper is clearer than a longer Codex task prompt. In <workspace-root>/app, for example, it is useful for modifying a large file such as scripts/feed_processor.py, where a broad manual edit can accidentally change unrelated behavior. It is especially useful when the patch must fail loudly if an anchor is missing, duplicated, or changed by another session.

The older automatic-patching guidance remains valid for this workflow. The assistant should inspect current files, derive anchors from the actual file contents, write helper files into tmp, and use explicit success strings such as PATCH_PASS and VERIFY_PASS. The assistant should not invent anchors from memory or rely on stale documentation when the live file can be inspected.

6. Standard Patch and Verify Helper Workflow

The standard patch and verify helper workflow begins with repository preflight. The assistant or user confirms the working tree and branch before writing or running any helper.

cd <workspace-root>/<repository>
git status --short
git branch --show-current
git log --oneline -5

If the status output shows unexpected files, the work pauses. The assistant must identify whether those files are part of the current task, previous user work, generated artifacts, or a problem. It must not hide unexpected files by staging, committing, deleting, or overwriting them.

After preflight, the assistant inspects the target files. Searches should be focused. A good inspection command looks for the exact functions, constants, markers, or configuration keys involved in the intended change. The following command is an app-repository example for <workspace-root>/app, not a universal command for every repository.

cd <workspace-root>/<repository>
Select-String -Path .\scripts\feed_processor.py `
  -Pattern "rewrite_with_ai|call_openai_chat_completions|record_ai_token_usage_event" `
  -CaseSensitive:$false `
  -Context 4,12

The patch helper belongs under the repo-local tmp directory. It should be named for the target and change. A useful name is specific enough that a future cleanup pass can understand it.

tmp\patch_summary_wrapper_name.py
tmp\verify_summary_wrapper_name.py

A patch helper must read the exact target file, check that the intended old text or anchor exists, fail loudly if the anchor is missing or duplicated unexpectedly, make only the intended change, write the target file, and print a clear pass marker. It should not silently skip a failed patch. If idempotence is useful, it may print a clear SKIP message only when the target state already exists.

from pathlib import Path

root = Path("<workspace-root>/<repository>")
target = root / "scripts" / "example.py"
text = target.read_text(encoding="utf-8-sig")

old = "def old_name("
new = "def new_name("
count = text.count(old)
if count != 1:
    raise SystemExit(f"PATCH_FAILED: expected 1 anchor, found {count}")

target.write_text(text.replace(old, new, 1), encoding="utf-8")
print("PATCH_PASS: renamed example function")

The verify helper must independently inspect the changed files. It should confirm required markers, confirm forbidden markers are absent when relevant, compile or parse changed code when possible, and print VERIFY_PASS or VERIFY_FAIL. It should exit nonzero on failure.

from pathlib import Path
import py_compile

root = Path("<workspace-root>/<repository>")
target = root / "scripts" / "example.py"
text = target.read_text(encoding="utf-8-sig")

required = ["def new_name("]
missing = [item for item in required if item not in text]
if missing:
    print("VERIFY_FAIL: missing markers")
    for item in missing:
        print(item)
    raise SystemExit(1)

py_compile.compile(str(target), doraise=True)
print("VERIFY_PASS: example function rename verified")

After the helpers run, the assistant should ask for or inspect the output, then run the appropriate project checks. For Python code, py_compile is a minimum check, not a full proof of safety. For active feed processor or AI changes, the runtime contract verifier or another targeted verifier is usually required. For SQL migrations, staging database verification is required before any production consideration. For pipeline configuration changes, verify expected stages, jobs, runner assumptions, protected-variable references, and whether deployment is disabled, manual, or explicitly in scope. For database, storage, report gateway, scheduler, worker, or alerting changes, use docs/runtime-validation-standard.md to choose targeted runtime checks. For documentation-only work, existence checks, required-phrase checks, git diff --check, and git status --short may be sufficient.

A normal verification block includes the changed files, syntax checks, targeted validation, diff hygiene, and final status. The following command block is an app-repository example for <workspace-root>/app; other repositories should substitute their own runtime checks.

cd <workspace-root>/<repository>
.\.venv\Scripts\python.exe -m py_compile .\scripts\example.py
.\.venv\Scripts\python.exe .\monitoring\verify_feed_processor_runtime_contract.py
git diff --check
git diff --stat
git status --short

The assistant must not tell the user to commit until the patch and verification output support a safe checkpoint.

7. When to Use Codex

Use Codex for bounded implementation tasks where the target is known, the file list is small, and the prompt can describe the exact allowed and forbidden behavior. Codex is appropriate when it can inspect required context, make the narrow edit, run validation commands, and create a durable handoff record without broad interpretation.

Good Codex tasks include adding a compatibility wrapper, renaming an internal function while preserving the old entry point, updating a verifier to cover one new behavior, creating a state handoff file, or making a narrow documentation update. These tasks have obvious boundaries and can be verified with explicit commands.

Bad Codex tasks include broad refactors, moving core modules, changing database schema without a staged migration plan, changing production config, changing CI/CD deployment behavior without explicit scope, changing feed output quality gates without full review, or vague instructions such as clean up everything. If the prompt cannot list the allowed files and forbidden actions, the task is not ready for Codex implementation.

Codex should also be avoided when the repository already has unexplained changes, unless the first task is to inspect and report those changes. It should not blend unrelated work into a single patch just because it notices adjacent cleanup opportunities.

8. Codex Prompt Requirements

Every Codex prompt must be self-contained enough that a future reader can understand why the changes happened. The prompt should not rely on hidden chat context. It must name the repository path, branch, required source files to read, exact task, exact allowed files, exact forbidden files and actions, whether pipeline configuration may be changed, validation commands, required handoff path, and expected final status.

A reusable prompt template follows.

Repository: <workspace-root>/<repository>
Branch: feature-or-fix-branch-name

Task:
Describe the exact bounded task in full sentences.

Required context before editing:
1. Read state/README.md.
2. Read any relevant inventory or handoff files.
3. Read each source file required for this change.
4. Confirm current branch.
5. Confirm working tree status before editing.

Allowed files:
- path/to/allowed-file.py
- path/to/allowed-verifier.py
- state/codex_handoff_specific_task_YYYY-MM-DD.md

Hard restrictions:
- Do not commit.
- Do not stage files.
- Do not move files.
- Do not rename files.
- Do not touch config/config.txt or config/secrets.txt.
- Do not run Watchdog unless explicitly required.
- Do not run Deep Audit unless explicitly required.
- Do not mutate databases.
- Do not touch production resources.
- Do not create or modify CI/CD pipeline configuration unless this prompt explicitly allows it.
- Do not add deployment jobs unless this prompt explicitly allows deployment work.

Required code or documentation change:
1. Specific change.
2. Specific compatibility behavior to preserve.
3. Specific verifier or documentation requirement.

Validation commands Codex must run:
cd <workspace-root>/<repository>
git status --short
git branch --show-current
specific validation command
git diff --check
git diff --stat
git status --short

Required handoff file:
Create state/codex_handoff_task_name_YYYY-MM-DD.md.

The handoff file must include:
- task completed
- source files read
- files changed
- functions or sections changed
- behavior preserved
- validation commands and exact output
- checks not run
- risks and assumptions
- Architectural Impact Review, including CI/CD, Docker, Kubernetes, deployment, documentation, and workflow-safeguard impact
- final git status

Expected final state:
No commit.
Nothing staged.
Working tree may contain only:
- allowed file
- allowed verifier
- required handoff file

The prompt should be stricter when the task touches active runtime behavior, database state, provider configuration, Telegram posting, scheduler assumptions, or production resources.

9. Codex Handoff Requirements

A Codex handoff that includes Git work must state how the commit and merge records will be preserved. If the work will be merged into main, the handoff must identify whether the merge will be performed locally, through GitLab CLI, through GitLab API, or by another controlled method. The handoff must warn against GitLab UI default merges when the merge commit body cannot be controlled.

The handoff must also state that the final merge commit body must be inspected with:

git show --no-patch --format=full HEAD

If the body is incomplete or corrupted and has not been pushed, it must be amended before push. If it has already been pushed to protected main, the repair path is a corrective documentation or audit commit, not a casual history rewrite.

Every Codex implementation task must create a handoff file under repo-local state when that repository has a state directory or when the task creates one with approval. The handoff is not optional project decoration. It is the durable record that allows the human operator, another ChatGPT session, a later Codex session, or a future automation worker to understand what happened without replaying the whole conversation.

The standard model is state/codex_handoff_summary_wrapper_2026-06-30.md. A handoff must include the task completed, files changed, functions or sections changed, behavior preserved, validation commands and exact output, checks not run, CI/CD pipeline impact, risks and assumptions, and final Git status. If a validation command initially fails and then passes after a corrected rerun, both facts should be recorded.

A handoff must explain unexpected files. If the final working tree contains anything outside the approved file list, the handoff must say why. If Codex could not run a check because of sandbox permissions or missing dependencies, it must say that plainly and record any approved rerun.

State handoffs should be written in full sentences. They should be concise enough to read but detailed enough to serve as operational memory.

10. Assistant Verification After Codex

Assistant verification after Codex must include Git-record verification when Codex produced or prepared a commit. The assistant must inspect the staged diff, the final commit message, and any merge commit message before treating the patch as ready. If the task includes CI/CD work, the assistant must also confirm branch pipeline status before merge and main pipeline status after merge.

Codex output is never accepted blindly. The assistant or human operator must review the repository state and the actual diff before deciding whether the work is ready to commit.

The review should begin with Git state.

cd <workspace-root>/<repository>
git status --short
git diff --stat
git diff --check
git diff

The reviewer should compare the changed file list against the prompt. Unexpected files must be explained before commit. Generated cache files, logs, local config, secrets, temporary helpers, virtual environments, database files, and provider-local cache files should not be staged unless the user explicitly approves and the project standard allows it.

The reviewer should run or confirm the validation commands listed in the handoff. For code changes, this usually includes syntax or compile checks and a targeted verifier. For AI/feed processor changes in <workspace-root>/app, monitoring/verify_feed_processor_runtime_contract.py is often required. For documentation-only changes, git diff --check, file existence checks, required marker checks, and final status may be sufficient.

The reviewer should also confirm that the Codex handoff is internally consistent. If the handoff claims only three files changed, git status --short should show only those three files. If the handoff says no Watchdog was run, there should not be new watchdog artifacts unless another process created them and the handoff explains that.

11. State Directory Standard

Repo-local state, when present or approved for creation, stores durable project-state outputs that are useful across sessions. It is the correct home for environment-state reports, inventory reports, test-state reports, assistant-generated state snapshots, and temporary-but-important working records that should not be lost when tmp is cleaned.

The repo-local docs directory is for human-facing documentation, standards, SOPs, architecture notes, and public or internal guides. The state directory is for durable machine/project state. A Codex handoff belongs in repo-local state, not repo-local docs, because it records the result of a specific task rather than serving as a general human-facing standard.

The repo-local tmp directory remains the correct place for disposable patch helpers, verify helpers, one-off generated inspection scripts, local logs, and temporary artifacts that can be cleaned after the results are committed or preserved elsewhere. Do not use global scratch folders for repo-specific output when a repo-local tmp folder exists.

12. Documentation Updates

Documentation is part of the implementation. If a change alters a workflow, operator command, safety boundary, runtime behavior, file placement rule, Git standard, CI/CD pipeline behavior, database process, or AI-provider expectation, the relevant documentation should be updated in the same branch or a clearly linked follow-up.

A state handoff is sufficient when the work is a bounded implementation record and no general standard has changed. A docs update is required when the process itself changes or when future operators need a durable guide, not merely a record of one task.

Older HTML documents can remain as historical source material unless a task explicitly retires them. When a new Markdown document supersedes an older HTML guide, the older guide should not be deleted or edited casually. The supersession should be recorded in the new document and in the task handoff.

13. Safety Boundaries

Production restrictions are strict. Do not mutate production databases, production storage, production scheduler definitions, production customer resources, or production Telegram channels without explicit approval. If a command can change production state, classify it before running it and require explicit confirmation.

Configuration and secrets restrictions are also strict. Do not edit config/config.txt or config/secrets.txt unless a task explicitly names those files and the user approves the change. Config templates and examples may be edited when in scope, but they still require careful review because future operators may copy them.

CI/CD pipeline work requires scoped planning. Do not create automatic production deployment, expose secrets, or change protected deployment behavior unless the task explicitly authorizes it.

Database work requires staged planning. Schema changes belong in migration files and should be tested against staging before any production promotion. Data repair is not the same as schema migration. Cleanup SQL that is safe for staging must not be copied into production without separate inspection.

Watchdog and Deep Audit are not generic validation commands to run casually. They may write logs, query systems, enqueue operations, or report health based on current runtime state. Run them only when the task requires them or the user approves. If they are not run, the final report should say they were not run.

Do not perform destructive cleanup without explicit approval. This includes deleting files, resetting history, discarding uncommitted changes, removing state records, clearing logs that are still needed for recovery, or pruning local/cloud artifacts.

14. Output Summary Standard

Patch, verification, inspection, and validation commands should end with a compact output summary when the user needs to paste terminal output back into another assistant. The summary should include important exit codes, generated file paths, changed file paths, validation results, CI/CD pipeline impact, git diff --stat, and git status --short.

The summary should not paste thousands of unrelated log lines unless the log itself is the evidence needed to diagnose a failure. A useful summary gives the next session enough detail to continue without hiding important failures.

A typical terminal summary block looks like this.

Write-Host ""
Write-Host "===== OUTPUT SUMMARY ====="
Write-Host "PATCH_EXIT=$patchExit"
Write-Host "VERIFY_EXIT=$verifyExit"
Write-Host "PATCH_LOG=$patchLog"
Write-Host "VERIFY_LOG=$verifyLog"
Write-Host "KEY_RESULTS:"
Select-String -Path $verifyLog -Pattern "VERIFY_PASS|VERIFY_FAIL|RUNTIME_CONTRACT_PASS|RUNTIME_CONTRACT_FAIL"
Write-Host "GIT_DIFF_STAT:"
git diff --stat
Write-Host "GIT_STATUS:"
git status --short
Write-Host "===== END SUMMARY ====="

When Codex writes a handoff file, the handoff is the durable version of this summary. It should paste exact command output for the required validation commands, including empty output where that matters.

15. Future AI Session Instruction Block

Future AI sessions may copy the following instruction block when working on repository changes.

You are working in a named repository inside the modular workspace. Confirm the repository path, branch, and working-tree state before editing, staging, committing, pushing, or recommending recovery actions.

Start in inspection mode. Confirm the repository path, branch, and `git status --short` before editing. Treat `docs/patch-codex-workflows-standard.md` as the controlling workflow standard for repository patching and Codex-assisted implementation.

Use one of two approved workflows. For deterministic chat-driven patches, create a patch helper and separate verify helper under the repo-local `tmp` directory. Use exact anchors from the current file, fail loudly, print pass/fail markers, run syntax checks, run targeted validation, and inspect Git diff/status before recommending a commit.

For bounded Codex work, require a prompt that names the repository, branch, context files, exact task, allowed files, forbidden actions, validation commands, required repo-local `state` handoff file, and expected final status. Do not commit or stage unless the user explicitly asks.

Never silently edit, commit, deploy, promote, mutate databases, touch production resources, modify secrets, or change CI/CD pipeline configuration. Do not run Watchdog or Deep Audit unless the task explicitly requires them or the user approves.

After Codex work, review `git status --short`, `git diff --stat`, `git diff`, `git diff --check`, CI/CD pipeline impact, the validation outputs, and the Codex handoff. Unexpected files must be explained before any commit.