@innofeight/global-workflow 0.0.1 → 0.0.2

package/rules/SHARED_WORKFLOW_RULES.md

@@ -0,0 +1,653 @@
+- Every imported/reconstructed ticket must pass `ENTRY REVIEW` before `IN PROGRESS`; repository architecture and requirements remain authoritative over ticket wording.
+- Only genuine Human QA uses the native ClickUp checklist named `Human QA Acceptance Criteria`; Task Acceptance Criteria remain description-only.
+- An agent must not move or recommend a ticket to `READY FOR REVIEW` until every applicable criterion, verification, evidence, and durable-documentation requirement is satisfied or an explicit not-applicable exception is recorded.
+- `BLOCKED`, `READY FOR MERGE`, and `READY FOR RELEASE` are Active. They do not clear dependencies, and `READY FOR MERGE` never authorizes an agent merge.
+- `COMPLETE` is the only closed and dependency-clearing status.
+- An execution-authorizing prompt permits the stated operations after safety inspection; it is not answered with a preflight-only response unless an actual unsafe or contradictory state blocks execution.
+
+These workflow states do not override human approval gates for architecture, dependency admission, milestone acceptance, merge, release, publication, security, or scope changes.
+## Repository-local scratch and neutral validation
+
+Normal agent-authored project scratch belongs under the active repository's
+ignored `.codex-tmp/` hierarchy. Agent-created neutral or disposable validation
+workspaces also belong under `.codex-tmp/`, using a fresh isolated subdirectory.
+Do not use `/tmp`, `/private/tmp`, `$TMPDIR`, Desktop, Downloads, or another
+external location merely for convenience.
+
+This rule improves filesystem and sandbox ergonomics; it is not permission
+bypass authority and does not weaken sandboxing, filesystem controls, or shell
+approval. Tool-owned internal temporary lifecycles remain permitted when a
+package manager, compiler, test framework, library, or OS API owns creation and
+cleanup, including legitimate `os.tmpdir()`, `mkdtemp()`, or equivalent use.
+
+Repository-local scratch is disposable, non-authoritative, and Git-ignored. It
+must not contain credentials, secrets, signing material, or sensitive PII.
+Promote durable findings and evidence into proper repository or ClickUp
+authority.
+
+Neutral-validation isolation still applies. Do not silently use another real
+customer, product, personal, or engineering repository merely because it is
+available or convenient. A neutral workspace must not inherit unrelated source,
+project-specific `AGENTS.md`, existing project context, or unrelated task
+history.
+
+A downstream project may use another already-authorized ignored
+repository-local scratch directory only when its own authoritative policy
+explicitly defines it. Otherwise, `.codex-tmp/` is the shared default.
+
+## Git and review
+
+- Work on `codex/*` branches. Never modify or push directly to `main`.
+- Codex task branches use `codex/CU-<real-clickup-task-id>-<short-kebab-slug>`; ClickUp's suggested name does not override the `codex/` namespace.
+- A ticket pickup inspects the current branch and worktree before switching. Dirty files, untracked files, conflicts, unsafe Git operations, stale/divergent `main`, or branch collisions require a stop; never stash, clean, reset, discard, commit, resolve, or reuse automatically.
+- Canonical-contract `AC READY` means Task AC is coherent, Human QA applicability and any required canonical HQA criteria are settled, and no known human-governance decision prevents pickup. A complete human-issued `grab ticket <task-id>` prompt then authorizes normal work through `READY FOR REVIEW`. Before branch creation, use the repository acceptance helper to revalidate canonical Task AC and HQA applicability from a complete connector-readable task description; a truncated read never authorizes pickup. Task AC remains description-only and never requires a native checklist or reusable mirror evidence. Only required HQA is mirrored in the sole native checklist named `Human QA Acceptance Criteria`; HQA `NONE` or `NOT APPLICABLE` correctly permits zero native checklists. Reuse unchanged valid HQA mirror evidence without another human stop. Missing, inaccessible, changed, malformed, or unconfirmed required HQA evidence stops Phase 1 for one complete fenced repair block containing the exact checklist name and all exact HQA items, followed by the exact reply `checklist added`. Historical `TASK_AC` mirror records remain readable audit history but never authorize or block new pickup. Every normal start prompt also supplies the exact previous governed ticket from fresh authority; Codex verifies but never guesses/substitutes it, and branch creation requires positive predecessor `COMPLETE` or completion of that exact safely resumable automatic closeout. After branch creation/push, always stop before Entry Review for human GitHub-panel verification and exact reply `branch confirmed`. Mandatory `ENTRY REVIEW` then occurs before `IN PROGRESS`; when it passes without a genuine human-controlled decision, blocker, scope conflict, missing artifact, or unsafe state, continue in the same governed run without a third routine authorization. PR merge is never automatic.
+
+- Preserve unrelated and user-authored work. Do not discard, overwrite, stage, or reformat it.
+- Do not merge, self-approve, publish production artifacts, or change repository security rules without explicit human approval.
+## Regression-first investigation
+
+When a previously accepted feature regresses:
+
+1. Identify the exact last-known-good SHA and freeze the current failing worktree.
+2. Diff the last-known-good tree against the current worktree, including uncommitted changes and generated output as well as generator source.
+3. Classify relevant changes and produce ranked causal hypotheses before changing implementation code.
+4. For each hypothesis record its ID, exact changed files/diff, causal mechanism, fit to the observed platform/workflow matrix, predicted additional behavior, confidence, smallest falsifiable secondary experiment, and whether it was previously attempted or ruled out.
+5. Do not treat correlation as causation or repeat a disproven approach without new evidence.
+6. Do not close the regression until prevention coverage exists.
+When ticket wording conflicts with repository authority, surface the discrepancy. Do not silently rewrite project requirements to match the ticket, and do not silently rewrite the ticket in a way that conceals the conflict.
+
+## Approved ClickUp statuses
+
+| Group       | Status                       | Meaning                                                                                                                   |
+| ----------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Not Started | `TO DO`                      | Known backlog work. Entry review has not begun.                                                                           |
+| Active      | `ENTRY REVIEW`               | The ticket is being checked and refined against current authority before execution.                                       |
+| Active      | `IN PROGRESS`                | Authorized execution is underway.                                                                                         |
+| Active      | `READY FOR QA`               | Every fail-closed engineering and tester-readiness gate for required Human QA has passed.                                 |
+| Active      | `IN QA`                      | The human tester has started the governed Human QA battery.                                                               |
+| Active      | `QA FAILED`                  | The human tester stopped on a mismatch; evidence is preserved and remediation remains.                                    |
+| Active      | `QA PASSED`                  | The human tester attested the complete required Human QA contract passed.                                                 |
+| Active      | `READY FOR REVIEW`           | Every applicable Acceptance Criteria item and the review-entry gate are satisfied.                                        |
+| Active      | `IN REVIEW`                  | Human/ChatGPT review of work, PR, verification, evidence, and Acceptance Criteria is active.                              |
+| Active      | `READY FOR ADMIN COMPLETION` | Independent administrative review passed for an eligible no-merge class; only trusted human finalizer invocation remains. |
+| Active      | `READY FOR MERGE`            | Review and merge-gate evidence are complete; explicit human merge remains.                                                |
+| Active      | `READY FOR RELEASE`          | An actual human-controlled release or publishing operation remains.                                                       |
+| Active      | `BLOCKED`                    | Work cannot proceed without an identified decision, action, permission, or state change.                                  |
+| Closed      | `COMPLETE`                   | Every requirement applicable to the ticket is actually finished.                                                          |
+
+`COMPLETE` is the only closed status. `READY FOR ADMIN COMPLETION`, `READY FOR MERGE`, and `READY FOR RELEASE` remain Active and do not satisfy or clear downstream dependencies.
+
+## Lifecycle
+
+For tickets with no Human QA requirement, the normal lifecycle is:
+
+`TO DO → ENTRY REVIEW → IN PROGRESS → READY FOR REVIEW → IN REVIEW → READY FOR MERGE → COMPLETE`
+
+For tickets with required Human QA, the success lifecycle is:
+
+`TO DO → ENTRY REVIEW → IN PROGRESS → READY FOR QA → IN QA → QA PASSED → READY FOR REVIEW → IN REVIEW → READY FOR MERGE → COMPLETE`
+
+The Human QA failure loop is:
+
+`IN QA → QA FAILED → IN PROGRESS → READY FOR QA → IN QA`
+
+An engineering agent may set `READY FOR QA` only after the fail-closed readiness
+contract below passes. Only the human tester may set `IN QA`, `QA PASSED`, or
+`QA FAILED`; an agent may never self-attest those states. After `QA FAILED`,
+engineering may return the ticket to `IN PROGRESS`, must preserve failed
+evidence, and must rerun affected QA against a new exact candidate after all
+readiness gates pass again. `QA PASSED` is not merge, architecture, milestone,
+dependency, release, or publication approval.
+
+Use `READY FOR RELEASE` between the reviewed/merged state and `COMPLETE` only when the ticket has a real release or publishing gate. A ticket may enter `BLOCKED` from an Active state and return only to the appropriate Active state after its recorded unblock condition is satisfied.
+
+Review may return a ticket from `IN REVIEW` to `IN PROGRESS` or `BLOCKED` when remediation or a decision is required. Status movement does not override architecture, dependency, security, acceptance, publication, or human-approval gates.
+## Mandatory ENTRY REVIEW
+
+Every reconstructed or imported ticket must pass `ENTRY REVIEW` before execution. It may not move from `TO DO` through `ENTRY REVIEW` into `IN PROGRESS` until the review confirms or refines, as applicable:
+
+- a human-readable task title;
+- objective;
+- current scope;
+- explicit out-of-scope boundaries;
+- authoritative architecture and requirement references;
+- dependencies and blockers;
+- Acceptance Criteria;
+- required evidence;
+- verification requirements;
+- agent authorization;
+- operations the agent may perform;
+- human approval gates;
+- stop conditions;
+- whether an imported backlog assumption has become stale.
+
+Entry review must compare the ticket with live repository/project state and current authority. Imported wording may be clarified or corrected for execution, but it cannot approve a product requirement, architecture change, dependency admission, milestone acceptance, merge, release, or other human-controlled decision.
+
+If the review finds a conflict or missing human decision, record it and move or keep the ticket in the appropriate non-executing state. Do not begin implementation under an ambiguous authorization.
+
+## Acceptance Criteria checklist contract
+
+### Task Acceptance Criteria
+
+Every normal executable ticket defines canonical, agent-readable Task Acceptance Criteria in its description. Each criterion has a stable ID (`TAC-01`, `TAC-02`, and so on), concrete ticket-specific wording, and evidence evaluable through source/diff inspection, automated or generated verification, CI, dependency/architecture checks, repository state, documentation/evidence review, or exact authoritative GitHub/ClickUp facts.
+
+Codex implements against Task AC. Independent ChatGPT review accounts for every item explicitly as `PASS`, `FAIL`, `NOT APPLICABLE`, or `REQUIRES HUMAN EVIDENCE`, with evidence and any exception reason. The human does not perform a second engineering review merely to decide which Task AC boxes deserve checking.
+
+### Human QA Acceptance Criteria
+
+Human QA AC exists only when repository or automated evidence is insufficient and a person must physically observe, operate, or judge something, such as physical-device behavior, visual UX, permission prompts, editor behavior, hardware, an inaccessible external UI, or explicitly required subjective acceptance.
+
+Each Human QA criterion uses a stable ID (`HQA-01`, `HQA-02`, and so on) and defines the concrete tester action, exact expected observation, required evidence when applicable, and stop condition. Agents may prepare instructions and evaluate supplied evidence but may not self-attest a human observation.
+
+### Governance gates are separate
+
+Merge, architecture approval, dependency admission, milestone acceptance, release authorization, security decisions, and other declared human governance decisions are not Task AC or Human QA AC. Criteria may require evidence that a gate occurred, but a checklist cannot grant or replace the decision.
+
+### Canonical descriptions and the Human QA checklist
+
+The task description is the canonical acceptance contract. Task Acceptance Criteria are evaluated by the implementing agent and independent reviewer directly from that description. They do not use a native ClickUp checklist mirror. Only applicable Human QA criteria are mirrored, in exactly one native checklist named `Human QA Acceptance Criteria`. HQA `NONE` or `NOT APPLICABLE` requires no HQA fingerprint or checklist, so zero native checklists is a valid normal state. A native HQA mirror does not replace or redefine the canonical description.
+
+Entry Review validates canonical Task AC and Human QA applicability. When HQA applies, it also compares the canonical HQA criteria with the native HQA checklist. Connector-observed exact name/body/state is the strongest normal evidence. When connector inspection is unavailable, matching fingerprint-bound durable HQA evidence may preserve an earlier human attestation without asking the human to repeat it. Checklist existence or count alone is never HQA acceptance evidence. Independent review supplies an explicit item-by-item Task AC disposition; no Task AC checkbox reconciliation follows. Any suspected HQA mismatch stops lifecycle advancement until the canonical description and HQA mirror are reconciled without silently changing meaning.
+
+When ChatGPT asks the human to create or replace the HQA checklist, provide the exact checklist name and every complete `HQA-xx` criterion in one fenced code block for one-shot bulk paste, then request the exact reply `checklist added`. Keep explanation outside the block; never request or repair a Task AC checklist.
+
+The Mechanical Documentation Fast Path still uses its explicit completion contract instead of normal Task AC. Outside that exception, zero native checklists is also correct whenever Human QA applicability is `NONE` or `NOT APPLICABLE`.
+For each acceptance kind, extract complete stable-ID paragraphs from its exact level-two canonical heading through the next same-or-higher-level heading. HQA `NONE` or `NOT APPLICABLE` is declared under the exact level-two `Human QA Applicability` heading; nested explanatory headings do not create HQA. Normalize CRLF and CR to LF, remove trailing whitespace from every line and blank lines surrounding each criterion, preserve all remaining IDs/text/punctuation/Markdown/case/order, join criteria with exactly `LF LF`, and SHA-256 the UTF-8 bytes as lowercase hexadecimal prefixed by `sha256:`. Connector output containing a truncation marker is invalid canonical input and fails closed.
+
+Preferred durable storage is an append-only ClickUp task comment, but only when the comment action succeeds and the record can be read back through the authoritative connector. Time entries are timing records only and MUST NOT store reusable acceptance-mirror authorization or evidence.
+`HUMAN_QA_AC`, `Human QA Acceptance Criteria`, and `HQA-xx` IDs form the only reusable native-checklist evidence record in the current workflow. Valid strengths are `CONNECTOR-OBSERVED` and `HUMAN-ATTESTED`; never upgrade the latter. Historical Task AC records, including legacy label `AC`, remain readable audit history under the v1 parser but are never reused, repaired, or newly required by normal pickup.
+
+### Mandatory pre-start canonical acceptance readiness
+
+Before ChatGPT gives the human a Codex ticket-start command (`grab ticket <task-id>`, `fast fix <task-id>`, or a successor), it reports one compact readiness result. This pre-start result concerns the canonical acceptance contract and prerequisite human governance decisions. A missing, stale, mismatched, incomplete, or unconfirmed required HQA checklist does not prevent ChatGPT from issuing the initial normal `grab ticket`; Codex intentionally validates and, when necessary, repairs that HQA checklist during Phase 1 before creating a branch.
+
+- `AC READY` — canonical Task AC is present and coherent; Human QA applicability is decided; any required canonical Human QA criteria are present; and no known architecture, dependency, security, scope, or other human-governance decision prevents pickup. When HQA is `NONE`, zero native checklists is valid. When HQA is required, this result does not claim that its native HQA checklist is already confirmed.
+- `AC NOT READY` — the canonical Task AC is missing or ambiguous, Human QA applicability is unresolved, required canonical Human QA criteria are missing, or another prerequisite human-governance decision prevents pickup. Identify the blocker and shortest human action; do not issue the start command yet. Native-mirror repair by itself is not `AC NOT READY`.
+- `FAST-PATH AC READY` — the task contains an explicit mechanical completion contract and appears eligible; no native checklist should be added. Codex must still prove every fast-path condition after pickup.
+
+ChatGPT may report a known HQA mirror gap as useful setup context, but still issues the initial normal `grab ticket` prompt when the canonical contract is `AC READY`. After that instruction, Codex revalidates description-only Task AC and Human QA applicability. If HQA applies, it computes the HQA fingerprint and inspects connector evidence plus durable v1 HQA records. A current valid HQA record reuses the unchanged mirror without `checklist added` or a human wait. If canonical criteria or applicability are missing or ambiguous, Codex stops and never invents them. If required HQA has no current connector proof or matching valid record, Codex stops before branch creation and returns one exact HQA-only repair block. After `checklist added`, it rereads the task and records new connector-observed or human-attested fingerprint-bound HQA evidence. Task AC never triggers checklist repair.
+
+If Codex requests a synthetic checklist for a positively eligible fast fix, treat that as a workflow defect to investigate rather than asking the human to add one automatically.
+
+The ticket description carries execution context such as:
+
+- Objective;
+- Scope;
+- Guardrails and exclusions;
+- Output and required evidence;
+- Traceability and requirement references;
+- estimation notes where useful.
+
+The canonical Task AC and any Human QA AC state the concrete conditions that must be satisfied. Criteria should be independently checkable and identify required evidence or verification when that is not obvious.
+
+If a criterion is genuinely not applicable, document the exception and reason explicitly. Do not silently skip, delete, or treat it as satisfied.
+
+## Governed ticket pickup and task branches
+
+After ChatGPT reports `AC READY`, the human-issued complete prompt containing
+`grab ticket <clickup-task-id>` authorizes all three normal phases through
+`READY FOR REVIEW`, subject to the two declared preflight stops, mandatory Entry
+Review, and every genuine stop gate below. It does not require a third routine
+implementation-authorization prompt after branch confirmation.
+
+### Phase 1 — acceptance checklist preflight
+
+2. Revalidate canonical description-only Task AC and explicit Human QA applicability. If HQA applies, compute its current fingerprint and evaluate connector proof plus durable v1 HQA evidence. HQA `NONE` needs neither fingerprint nor checklist.
+3. Reuse unchanged valid HQA evidence without a stop. Fail closed before branch creation for canonical ambiguity or for missing, malformed, changed, or unconfirmed required HQA. Checklist count alone never passes. Return the exact HQA checklist name and all HQA items in one fenced repair block, followed by the exact reply `checklist added`. Task AC never enters this repair path. At that yield boundary, end AET and preserve the human-wait interval as specified below.
+4. After `checklist added`, reread and revalidate the task, record new fingerprint-bound connector-observed or human-attested HQA evidence, and proceed only when it passes. The completed human-wait and resumed occupied segment remain append-only v1 events.
+
+### Phase 2 — branch and ClickUp linkage preflight
+
+5. Inspect the **current** repository branch, index, worktree, and Git operation state before switching anything.
+6. Stop for tracked, staged, or untracked changes; conflicts; detached HEAD; merge, rebase, cherry-pick, or revert state; the wrong repository; or another unsafe condition. Never automatically stash, clean, reset, discard, commit, amend, resolve, delete, or force push.
+7. Fetch `origin`, switch safely to clean `main`, and compare it with `origin/main`.
+8. Continue when the refs are equal. When local `main` is strictly behind, update only with `git merge --ff-only origin/main`. Stop when local `main` is ahead, divergent, unsafe, or cannot fast-forward.
+9. Normalize the title and derive `codex/CU-<real-clickup-task-id>-<short-kebab-slug>`. The task ID is unchanged. The slug uses Unicode NFKD, lowercase ASCII alphanumerics, hyphens for other character runs, collapsed/trimmed hyphens, a 48-character maximum with a trailing hyphen removed, and `task` when empty.
+10. Check both local and remote branch collisions before creation. Do not silently reuse an existing branch.
+11. Create the task branch from verified current `main`, record the exact branch-cut timestamp and baseline SHA, push normally, and configure its upstream. Never create a top-level `CU-...` Codex task branch.
+12. Establish or allow the normal ClickUp/GitHub association and attempt automated/indexed verification. A valid-looking branch name is not itself linkage evidence.
+13. Always stop before Entry Review. Give the human the exact readable task title, direct ClickUp link, and exact branch; ask them to inspect the task's GitHub panel and reply exactly `branch confirmed`. The original complete prompt remains the authorization for Phase 3.
+### Phase 3 — continuous governed engineering
+
+15. With the resumed AET-v2 segment open, perform mandatory `ENTRY REVIEW`, including canonical Task AC, its exact native mirror, and the need for and presence of any Human QA AC/mirror.
+The declaration intentionally may appear after already-persisted pickup segments and pre-Entry-Review waits in append order; semantic Calendar Cycle still begins at pickup, and no earlier interval is reconstructed. If Entry Review never succeeds, preserve the partial v1 evidence and fail closed from complete reporting and clean calibration rather than fabricating a declaration. If Entry Review passes and discovers no genuine stop gate, move `ENTRY REVIEW → IN PROGRESS` and continue the same governed run through implementation, verification, commit/push, Draft PR, exact-head CI, Task AC reconciliation, durable knowledge promotion, and `READY FOR REVIEW`.
+A passing Entry Review is not itself a stop gate. Stop when progress requires an
+unsafe Git/worktree repair; resolution of repository/task authority conflict;
+reconciliation of missing or changed acceptance artifacts; an architecture,
+dependency, security, acceptance-contract, milestone, release, publication, or
+scope decision; Human QA or physical-device work/evidence; credentials or
+permissions; an external blocker requiring human action; or another declared
+human-only decision. The original `grab ticket` authorization never overrides
+those boundaries.
+Legacy tickets do not require a mass rename. Normalize one when it is next materially touched or before the human must act on it. If a requested ticket is hidden because it is a subtask or filtered from the current ClickUp view and the cause is already clear, give the shortest actionable UI fix first instead of continuing unnecessary investigation.
+
+Opaque IDs remain required where machines need them: Codex execution prompts such as `grab ticket <task-id>` and `fast fix <task-id>`, connector calls, branch names, PR traceability, and optional secondary references. A human-facing instruction may include the ID parenthetically, but the readable title and link remain primary.
+
+### Orchestration roles and single-agent optimization
+
+ChatGPT is the project orchestrator and independent reviewer. Codex is the governed ticket-pickup and repository-implementation agent. After `AC READY`, the human owns authorization of the complete normal `grab ticket <exact ClickUp task ID>` run through `READY FOR REVIEW`, plus merge, milestone acceptance, release, physical-device execution, and every other declared human gate. Codex performs acceptance-artifact preflight, stops for `checklist added` only when repair is required, creates the branch, always stops for `branch confirmed`, and then performs Entry Review and continuous engineering without a third routine authorization. ChatGPT must not silently substitute itself for Codex implementation merely because it can reach GitHub or ClickUp.
+
+The current optimization phase is deliberately single-agent. Make normal single-agent work predictable and efficient across several measured tickets before proposing concurrency. Multi-agent and overnight execution are deferred and require separate governed approval; no current task may infer authorization for them.
+
+Front-loading checklist and branch-confirmation gates allows predictable setup to be cleared before a future unattended window. That is design rationale only: it does not authorize parallel agents, concurrent task branches, multi-agent orchestration, or overnight execution under current policy.
+### Merge-to-complete safety
+
+Any merge automation must require all three facts: the linked PR was merged, its base is `main`, and the task's current status is `READY FOR MERGE`; only then may it set `COMPLETE`. If native ClickUp automation cannot positively express the status condition, it is insufficient. Human-controlled completion after merge is the safe default. Do not add a secret-backed alternative or activate automation without separate human approval.
+
+## READY FOR REVIEW hard gate
+
+An agent must not move or recommend moving a ticket to `READY FOR REVIEW` unless every Task AC item is accounted for with an evidence-backed result and every applicable item is satisfied or has an explicit approved exception. Native Task AC reconciliation may remain a clerical human action when connector limitations prevent agent inspection or mutation, but the review report—not human guesswork—determines the substantive result.
+
+Before `READY FOR REVIEW`, also confirm:
+
+- required verification has run;
+- required evidence exists and is referenced;
+- documentation changes associated with the work are present;
+- known failures and blockers are surfaced;
+- no material requirement, decision, blocker, acceptance boundary, or hard-won project fact remains only in chat.
+## IN REVIEW
+
+`IN REVIEW` means a human/ChatGPT review is actively evaluating the work, PR, verification, evidence, and Acceptance Criteria.
+
+Independent review reports every Task AC stable ID as `PASS`, `FAIL`, `NOT APPLICABLE`, or `REQUIRES HUMAN EVIDENCE`. It identifies Human QA AC separately and never promotes missing human observation into agent evidence.
+
+Review may return the ticket to:
+
+- `IN PROGRESS` when authorized remediation is required; or
+- `BLOCKED` when a decision, approval, permission, external state, or other unblock action is required.
+
+A review finding does not itself authorize remediation beyond the ticket's approved scope.
+
+## BLOCKED
+
+`BLOCKED` is Active, not complete. Its durable task record must state:
+
+- the exact blocker;
+- evidence demonstrating the blocker where applicable;
+- who or what can unblock it;
+- the required decision or action;
+- the next authorized action once unblocked.
+
+Agents may not conceal or silently work around a blocker. Work may resume only when the recorded unblock condition and any applicable authorization boundary are satisfied.
+
+## READY FOR MERGE
+
+`READY FOR MERGE` means:
+
+- implementation/documentation review is complete;
+- required verification and merge-gate evidence are satisfied;
+- no known review blocker remains;
+- every required Human QA AC has passed with its human evidence recorded, unless a later milestone/acceptance gate is explicitly its governed destination;
+- the work is ready for explicit human merge.
+
+It does not authorize an agent to merge. It remains Active and does not make the ticket—or downstream dependent work—complete.
+
+## READY FOR RELEASE
+
+Use `READY FOR RELEASE` only for tickets with an actual release or publishing gate. It means implementation and merge requirements are satisfied but the required human-controlled release/publish operation remains.
+
+It remains Active and is not completed work. Tickets without a release gate may proceed from the appropriate reviewed/merged state toward `COMPLETE` without using this status.
+
+## COMPLETE and dependency clearing
+
+`COMPLETE` is the only closed project status. A ticket may become `COMPLETE` only when every applicable requirement is actually finished, including as applicable:
+
+- Acceptance Criteria;
+- required human review;
+- PR merge;
+- required release;
+- acceptance evidence;
+- milestone or acceptance records;
+- project-state updates;
+- durable documentation updates.
+
+Only `COMPLETE` satisfies or clears a dependency relationship. A green build, `READY FOR REVIEW`, `READY FOR ADMIN COMPLETION`, `READY FOR MERGE`, or `READY FOR RELEASE` does not.
+
+## Agent execution-prompt contract
+
+Prompts must distinguish planning/advisory work from authorized execution work. Planning may inspect, analyze, recommend, or draft, but it does not imply permission to mutate repository or external state.
+
+For normal ticket execution, the complete human-issued prompt must visibly
+contain `grab ticket <exact-task-id>` and explicitly authorize the governed run
+through `READY FOR REVIEW`, subject to acceptance-artifact preflight, the
+mandatory `branch confirmed` stop, mandatory Entry Review, and genuine stop
+gates. It should establish:
+
+1. exact task identity and objective;
+2. explicit operations the agent may perform;
+3. hard scope boundaries;
+4. dependency, security, and governance constraints;
+5. verification requirements;
+6. genuine stop conditions;
+7. exact return and evidence expectations.
+
+The prompt predeclares that a missing/stale native checklist produces one
+one-shot replacement block and resumes only after exact reply `checklist added`;
+after branch creation it always stops and resumes only after exact reply
+`branch confirmed`. Those short replies clear the predictable setup gates. They
+do not replace the original authorization or create a third implementation
+handoff.
+
+The generic phrase `EXECUTE THIS TASK NOW` is neither required nor sufficient
+for normal pickup. Descriptive preamble outside the complete copy/paste block is
+allowed; the executable prompt itself must remain self-contained.
+
+Safety preflight is allowed. When the prompt already authorizes execution, safety inspection must not become a preflight-only response. Continue into the authorized work unless an actual unsafe, contradictory, or blocked repository state prevents execution; then report the exact blocker and stop.
+
+Execution authorization never overrides repository governance. Preserve:
+
+- no self-merge;
+- no self-approval of architecture;
+- no self-approval of dependency admission;
+- no self-approval of milestone acceptance;
+- no verification bypass;
+- no speculative dependency mutation;
+- no hidden remediation outside the authorized task;
+- no silent expansion of task scope.
+
+### Complete replacement prompts
+
+Whenever ChatGPT modifies, extends, corrects, or supersedes a Codex prompt that the human is expected to paste, ChatGPT must provide the complete replacement prompt in one fenced code block and state that it supersedes the earlier prompt. The replacement carries forward every still-valid instruction and all modifications.
+
+Do not ask the human to append, insert, replace individual paragraphs, combine an addendum with an earlier prompt, or otherwise assemble prompt fragments. Do not provide only a delta when the next action is copy/paste into Codex. This keeps authorization boundaries auditable and prevents omissions and copy/paste assembly errors across current and future sessions.
+Do not infer unavailable boundaries from chat, Git, CI, PR, ClickUp, browser, or other activity timestamps. When only a human-attested duration or bound exists, record exactly that weaker evidence. Report raw Calendar Cycle Time unchanged; any availability-adjusted value is secondary calibration only. A separately labeled availability contingency may inform wall-clock forecasts but never changes engineering estimates, actuals, Human Attention, billable labor, or commercial effort calibration.
+
+The pre-merge gate freshly verifies the exact
+task-bound PR, base, open/non-Draft/unmerged state, reviewed head, successful
+exact-head `verify` check, independent-review PASS, canonical Task AC, HQA PASS
+or `NONE`, live `READY FOR MERGE`, and absence of a genuine unresolved human
+gate. Human merge is the only merge operation.
+
+The trusted push workflow then resolves the exact merged PR and task from
+immutable GitHub facts. It freshly requires successful `verify` and independent
+review PASS on the actual merged head before the first completion mutation.
+Only the exact task still at `READY FOR MERGE` may be written to `COMPLETE`;
+the result is positively reread, an uncertain write is reread before one
+bounded retry, and an exact already-`COMPLETE` replay is idempotent. AET,
+estimates, calibration, packet graphs, staging records,
+eligibility records, terminal timing, and finalizer records are telemetry or
+historical audit evidence and never gate this transition.
+Every normal start prompt names both `NEXT GOVERNED TASK` and the exact
+`PREVIOUS GOVERNED TICKET`. ChatGPT establishes that predecessor from fresh
+repository, GitHub, and ClickUp authority before emitting the prompt. Unknown
+identity stops prompt construction; it is never guessed from chat recency or
+delegated to Codex. A no-predecessor case must be positively stated as `NONE`.
+
+Before branch creation, Codex freshly verifies the supplied predecessor. An
+already-`COMPLETE` task permits pickup. An exact merged
+`AUTO_AFTER_MERGE` candidate may first resume its trusted idempotent closeout
+and must be reread `COMPLETE`. Wrong, stale, conflicting, human-gated, or
+unsafe state stops with one exact reason/action; Codex never substitutes a
+different predecessor. Any missing, ambiguous, inaccessible, inconsistent, out-of-location, non-main,
+unmerged, or non-`READY FOR MERGE` state causes no mutation. Merge alone never
+changes task status. An automatic candidate reaches `COMPLETE` only through
+the complete durable finalizer chain. The workflow never merges a PR.
+When policy is `AUTO_AFTER_MERGE`, the same pre-merge gate creates and
+positively rereads closed `POST_MERGE_AUTOMATIC_ELIGIBILITY_V1`. It binds the
+exact reviewed head, acceptance fingerprint, HQA, remaining human-gate
+classification, debt, next action, and request template. Any live
+identity/head/CI/acceptance/HQA/debt/gate drift invalidates readiness. Unknown
+classification defaults to `POST_MERGE_HUMAN_GATE`, never automatic.
+Every automatic-path evidence write uses deterministic content and bounded
+read-before-retry behavior: an uncertain mutation response triggers exhaustive
+authoritative readback, exact state is reused, absent state is retried only
+after reread, and conflict or persistent provider failure remains non-COMPLETE.
+Pre-existing automatic authorization does not bypass lifecycle admission. The
+trusted finalizer applies the same fresh task/status, exhaustive closed-world,
+typed-authority, eligibility, staging, packet, and authorization check before
+each missing terminal or finalized write. Exact partial states may resume only
+while the task remains `READY FOR MERGE`; a human `BLOCKED` or other unexpected
+Active transition stops before new terminal evidence is written.
+Trusted post-merge paths exhaust task-comment history using ClickUp `start` and
+`start_id`; newest-page evidence is never complete history. The request is
+closed-world over every valid task AET-v2 event before finalization, so an
+omission or newly arrived event makes it stale. Typed calibration and durable
+reconciliation bind comment ID, fingerprint, task, and asserted result. Retry
+success revalidates packet, staging, authorization, deterministic terminal
+events, finalized outcome, and live `COMPLETE` as one exact chain.
+Every independent clock is itself closed-world: measured and unknown
+classifications retain the complete known event-ID set, while `NOT APPLICABLE`
+requires none. Local preparation canonicalizes the supplied event set through
+the same serializer as trusted ClickUp reconstruction.
+# Engineering Time and Efficiency
+
+> Timing, estimates, calibration, and AET-v2 are operational telemetry. Missing,
+> malformed, incomplete, or conflicting telemetry must be reported truthfully
+> but never blocks an otherwise valid governed merge-to-`COMPLETE` transition.
+> Historical finalizer-specific instructions below remain measurement/audit
+> compatibility, not normal completion authority.
+
+## Purpose
+
+This document defines the project's durable estimation and timing model. It separates active engineering effort from human interaction and elapsed delivery time so estimates, reviews, and commercial calibration do not compare unlike measurements.
+
+## Measurement regimes
+
+### AET-v2 — Agent-Occupied Engineering Time
+
+`AET-v2` is the prospective authoritative agent-effort metric. In the current
+single-agent model it is elapsed wall-clock time while the engineering agent
+retains the governed execution slot and is occupied by the ticket. It includes
+orientation, reading, search, reasoning, investigation, implementation,
+generation, verification, documentation, review/remediation, commit/PR work,
+and post-merge reconciliation.
+
+An enclosing AET-v2 segment stays open across synchronous commands, tests,
+package-manager operations, builds, native compilation, simulator/emulator
+preparation, diagnostics, and log collection when the agent cannot use its
+execution slot for another governed ticket. CPU or tool runtime does not turn
+occupied capacity into External/System Wait.
+
+Close the segment only when the agent actually yields for a human decision,
+branch/checklist gate, credential or permission, physical Human QA, human
+merge/release action, or a genuinely unattended external wait with no useful
+authorized work remaining. If useful engineering continues during an external
+wait, that interval remains AET-v2. Never double-count overlapping segments.
+
+## Three clocks
+
+### Agent Engineering Time (AET-v2 for new work)
+
+Use the AET-v2 definition above. The older active-effort definition is retained
+only to interpret explicitly labeled AET-v1 history.
+
+### Human Attention Time
+
+The amount of the human's actively consumed working session attributable to the ticket. It includes active interaction with ChatGPT or Codex; ChatGPT-to-Codex handoffs; reading agent output; copying/pasting governed prompts and results; reviewing PRs, diffs, CI, or test results; ClickUp, GitHub, and editor interaction; decisions, answers, and authorization; physical QA; merge/release actions; and normal short sequential waits when the human remains tied to the ticket and cannot reasonably disengage.
+
+It excludes explicit breaks, meals, sleep, deliberate work on another project, periods when the human is genuinely free to disengage, and long external waits requiring no human attention. Do not infer Human Attention Time from message timestamps when it was not actually measured.
+
+### Calendar Cycle Time
+
+Elapsed wall-clock time from governed pickup to the ticket's required terminal outcome. It includes work, CI, reviews, pauses, and waiting. Report it separately; it is not engineering effort.
+
+## Reported elapsed-time categories
+
+The three clocks above remain the primary measures. The following categories explain portions of raw Calendar Cycle Time without redefining or subtracting from it.
+
+### External/System Wait Time
+
+Waiting caused by CI, provider systems, permissions, unavailable resources, or another external constraint after the agent has yielded. It is not AET-v2 unless active engineering continues, and it is Human Attention Time only for a short attended wait that keeps the human tied to the ticket.
+
+### Distraction / Human-Unavailable Time
+
+Known time when the human is unavailable for reasons unrelated to active ticket attention: a planned break, meeting, personal call, household interruption, unrelated conversation or work, meal, or other disengagement. Record a reason/category and the evidence strength.
+
+Distraction / Human-Unavailable Time remains inside raw Calendar Cycle Time, is excluded from Human Attention Time, and does not reduce Agent Engineering Time when an agent continues independently. Report it separately when known so availability latency is not mistaken for engineering or process inefficiency.
+### Human Attention Time segments
+
+Measure Human Attention Time with explicitly bounded append-only intervals, independently of Agent Engineering Time:
+
+1. Preserve the exact Human Attention start boundary when the human begins actively working the ticket with ChatGPT or Codex. Establish a new start boundary when the human returns with `I am back` or `resume`, or begins an active review, merge, release, editor-confirmation, or physical-QA interaction on an already-running ticket.
+2. Keep a short sequential wait inside the segment when the human remains tied to the ticket and cannot reasonably disengage.
+3. Preserve the exact Human Attention end boundary and reason when the human says `I am taking a break` or `take a break`, explicitly disengages for other work, enters a long unattended external wait, reaches a point where no human attention is currently required, or finishes the active merge, release, completion, review, or QA session.
+5. A later re-engagement establishes a new start boundary; it does not reopen or rewrite the previous interval. Sum only explicitly bounded completed intervals.
+6. Agent Engineering Time may continue while no Human Attention interval is open. Conversely, human review or QA may consume Human Attention while AET-v2 is closed.
+7. Historical human-attention intervals without contemporaneous boundaries remain unknown. Do not reconstruct them from chat, comment, commit, CI, or task-update timestamps.
+
+Human-unavailable and attention boundaries are both preserved, then emitted as completed `AET_V2_NON_AET_RECORDED` JSON through `record-non-aet`: the unavailable start coincides with the applicable attention end, and re-engagement after the unavailable end begins a new attention interval. Legacy `HUMAN_UNAVAILABLE_*`, `HUMAN_ATTENTION_*`, and `HUMAN_BREAK_*` records remain historical aliases only. An unavailable period may end without starting attention when the human has not re-engaged.
+
+### Human-unavailable recording
+
+Record unexpected or planned human unavailability append-only:
+
+1. Preserve the exact unavailable-start timestamp when known, category (`planned break`, `unexpected distraction`, `unrelated work`, `meeting`, or `other`), reason, and evidence classification. End any active Human Attention interval at the same boundary.
+3. If contemporaneous boundaries were not recorded, preserve only the human-attested duration, approximate bound, reason/category, and evidence strength. Never derive exact boundaries from chat, comments, commits, CI, PR, task, browser, or other activity timestamps.
+4. Agent Engineering Time continues independently when authorized. An agent closes its segment only upon reaching its own human or external blocker.
+
+## Authoritative AET-v2 execution ledger
+
+The authoritative event model is:
+
+- `AET_V2_LEDGER_DECLARED`: task identity, Work Class, frozen Original
+  Execution Estimate, and calendar start;
+- `AET_V2_SEGMENT_STARTED`: task, execution/session identity, exact timestamp,
+  category, reason, and evidence source;
+- `AET_V2_SEGMENT_ENDED`: matching start, exact timestamp, and end reason;
+- `AET_V2_ESTIMATE_REVISED`: append-only scope delta, revised total, reason,
+  approval source, and timestamp; it never replaces the original estimate;
+- `AET_V2_NON_AET_RECORDED`: explicitly bounded Human Attention, HQA,
+  Human-Unavailable, human-wait, or unattended External/System Wait evidence;
+- `AET_V2_MILESTONE_RECORDED`: first PR-ready, merge, or completion evidence;
+- `AET_V2_CORRECTION_RECORDED`: append-only replacement of one earlier event,
+  retaining the target event ID and recording the reason/source. Never delete
+  or rewrite the original record.
+
+Corrections may repair segment, wait, or milestone evidence, but they cannot
+target `AET_V2_LEDGER_DECLARED`; the frozen Original Execution Estimate is
+immutable. Estimate changes use `AET_V2_ESTIMATE_REVISED`, preserving the
+complete estimate history.
+The transition command captures one current boundary by default and uses it as
+both the wait's `endedAt` and the resumed segment's `timestamp`. It accepts
+`--boundary-at`, `--wait-event-id`, `--start-event-id`, and
+`--recorded-at` for deterministic fixtures or connector reconciliation. The
+other commands accept explicit `--event-id` and `--recorded-at` values for
+deterministic fixtures or connector reconciliation; otherwise the CLI creates
+those envelope values.
+
+The closed event shapes reject unknown properties and deliberately minimize
+the evidence surface. Allowed text fields still accept caller-supplied text:
+never place credentials, tokens, raw sensitive URLs, logs, secrets, or
+client-sensitive content in `source`, `reason`, `evidence`, `taskTitle`,
+`approvalSource`, or any other ledger field.
+When repeated merge or completion records exist, the report selects the latest
+timestamp of the applicable milestone, independent of ledger order. Any
+completion record supersedes merge as the reporting boundary. The report
+exposes both `mergedAt` and `completedAt`; a stale earlier event can never
+shorten required coverage. A completion timestamp before the latest merge is
+an invalid lifecycle order and fails closed.
+
+One lifecycle domain governs both completeness and aggregation. Semantic task
+evidence may not precede `calendarStartedAt`. First PR-ready cannot follow the
+first merge; completion requires merge and cannot precede the latest merge.
+When completion exists it is terminal: occupied segments, non-AET intervals,
+estimate revisions, and lifecycle milestones outside
+`calendarStartedAt..completedAt` fail closed. A nonterminal ordinary report
+extends its boundary through its latest semantic evidence. A final
+`--post-merge` report aggregates exactly the continuously covered
+pickup-through-completion domain, so pre-start or post-terminal evidence can
+never affect a report that claims complete measurement.
+
+Ordinary reports remain available before completion and state their evidence
+strength through `lifecycleStatus`, `lifecycleFinal`, and
+`reportingBoundaryAt`. A merge-only ordinary report is
+`intermediate-post-merge`, never a final closeout. `measurementComplete` means
+the stated aggregation boundary is continuously covered; only
+`lifecycleFinal: true` means the terminal completion domain is present. Open
+segments are always rejected—there is no relaxed complete-report mode.
+
+Estimate reporting preserves two distinct comparisons. The legacy
+`estimateRatio` and `estimateVarianceMilliseconds` fields, plus explicit
+`originalEstimateRatio` and `originalEstimateVarianceMilliseconds`, compare
+actual AET-v2 with the immutable Original Execution Estimate. The report also
+uses the latest approved revision by timestamp to expose
+`latestApprovedEstimateMinutes`, `latestApprovedEstimateRatio`, and
+`latestApprovedEstimateVarianceMilliseconds`. Thus original-estimate
+accountability remains stable while an approved scope revision remains
+operationally visible. Revisions are ordered by timestamp and event ID, and
+each scope delta must reconcile the preceding approved total to the new total.
+
+ClickUp native timers/time entries may be convenience mirrors only. Timer
+disagreement or outage never changes the JSON event ledger or computed AET-v2.
+Time entries remain timing evidence and never acceptance-mirror storage.
+
+## Durable ClickUp execution ledger
+
+The ClickUp task record is the recoverable, append-only execution ledger. Prefer append-only task comments and time entries; when those are unavailable, append a timestamped task-description section without rewriting earlier events. Preserve exact timestamps, event type, reason, and relevant SHA or estimate. Never overwrite history merely to produce cleaner totals.
+
+Legacy records keep these event names where applicable:
+
+- `PICKUP_STARTED`, `BRANCH_CREATED`, `BASELINE_SHA`, `ORIGINAL_ESTIMATE`;
+- `AGENT_SEGMENT_STARTED`, `AGENT_SEGMENT_ENDED`;
+- `HUMAN_ATTENTION_STARTED`, `HUMAN_ATTENTION_ENDED`;
+- `HUMAN_UNAVAILABLE_STARTED`, `HUMAN_UNAVAILABLE_ENDED` (with category, reason, and evidence classification);
+- `HUMAN_WAIT_STARTED`, `HUMAN_RESPONSE_RECEIVED`;
+- historical `HUMAN_BREAK_STARTED`, `HUMAN_BREAK_ENDED` as planned-break aliases;
+- `PR_READY`, `REVIEW_STARTED`, `REVIEW_FINDINGS`, `REMEDIATION_STARTED`;
+- `READY_FOR_MERGE`, `MERGED`, `COMPLETE`.
+
+A future session reconstructs new-ticket measured totals from the AET-v2 event
+wire contract. Legacy events/time entries remain AET-v1 evidence unless a
+contemporaneous explicit AET-v2 record says otherwise. Report gaps as unknown;
+never translate aliases or incomplete history into synthetic AET-v2 segments.
+Contemporaneous prose explicitly labeled AET-v2 but not conforming to the wire
+contract is bootstrap/manual AET-v2 boundary evidence only—not AET-v1 and not
+validator-consumable v1 JSON.
+
+## Immutable estimate history
+
+Never overwrite the original estimate. When scope materially expands, append:
+
+- original estimate;
+- scope delta;
+- revised total estimate;
+- reason and approval/source for the expansion;
+- timestamp of the revision.
+
+Ordinary variance within the approved scope is not a scope expansion; explain it in the completion comparison.
+
+## Review and completion reporting
+
+An AET-v2 review/completion report includes:
+
+- original and every revised estimate;
+- actual-versus-original and actual-versus-latest-approved estimate variance
+  and ratio as distinct comparisons;
+- total and category AET-v2, measurement completeness, ledger gaps, and correction events;
+- estimate variance and ratio only when the ledger is complete;
+- number/cost of review-remediation cycles;
+- the main cause of material variance;
+- Human Attention Time when measured or explicitly supplied;
+- raw Calendar Cycle Time;
+- Distraction / Human-Unavailable Time and External/System Wait Time separately when known, including evidence strength;
+- waiting categories separately from active engineering;
+- first PR-ready and merge timing when useful, without mislabeling either as final task effort;
+- next calibration disposition.
+
+Commercial calibration starts a fresh cohort containing only complete,
+representative AET-v2 tickets. Do not mix AET-v1 samples, partial ledgers, or
+stale ClickUp timers into AET-v2 ratios. Do not automatically rescale the
+remaining backlog when the mechanism first becomes live; wait for enough
+representative completions under one regime.
+
+Raw Calendar Cycle Time is always the canonical elapsed measure. An availability-adjusted interval may be shown only as secondary calibration or planning information; it never replaces raw Calendar Cycle Time, Agent Engineering Time, Human Attention Time, or engineering labor.
+
+Wall-clock forecasts may include a separately labeled human-availability/distraction contingency. That contingency must not modify Estimated Agent Engineering Time, Agent Engineering actuals, Human Attention actuals, billable engineering labor, or commercial engineering-effort calibration.
+
+## Per-ticket and Problem / Outcome Resolution metrics
+
+Per-ticket metrics measure one governed ticket: original and revised estimates, Agent Engineering Time, Human Attention Time, Calendar Cycle Time, and review/remediation cycles. They do not necessarily measure how long the underlying problem took to solve.
+
+Problem / Outcome Resolution metrics span from the initial governed pickup or recorded problem start through accepted resolution. Report the outcome start, every ticket required, cumulative measured Agent Engineering Time, cumulative measured Human Attention Time, total outcome Calendar Cycle Time, and final accepted-resolution timestamp.
+
+Review findings that are defects, omissions, contradictions, or incomplete implementation inside the original objective stay on the same ticket and, wherever reasonably possible, the same branch and PR. Preserve its original estimate history and continue all three clocks and the outcome clock. Do not create a remediation ticket merely to close the original sooner, improve apparent cycle time, reduce estimate variance, or hide review cost.
+
+A new ticket is justified only for genuinely out-of-scope work: a new feature, separate architecture/dependency/security decision, separately governed human decision, or independently valuable work that should not be silently absorbed. If the original outcome depends on that ticket, each ticket retains its own metrics while the overall outcome stays open or blocked and accumulates the required tickets' measured effort and elapsed time until accepted resolution.
+
+## Review efficiency
+
+Independent ChatGPT review should be exhaustive wherever reasonably possible before returning a remediation handoff. Consolidate known findings into one evidence-backed review rather than intentionally serializing fix → CI → rediscovery loops. New findings discovered after remediation remain valid, but earlier review should not be described as exhaustive if material areas were knowingly deferred.
+
+## Single-agent phase
+
+The current calibration phase measures and improves normal single-agent execution. Multi-agent concurrency and overnight execution are deferred. They require separate governance, measurement definitions, and human approval before use; results from concurrent agents must not be mixed into the single-agent baseline.