corp-v1-channel-delivery/references/repository-entry-and-visibility.md

the adopted project Repository Entry and Visibility

Load this reference before claiming a Task, creating its application branch, opening its PR, or resuming its worktree.

All local repository entry happens inside corp-v1-<code>-delivery/workspace/<TASK_ID>/. During preparation, create only the required repository clones: application/ and documentation/. Optional Task-local review/, cache/, tmp/, logs/, or artifacts/ folders may be added later only when a concrete Task activity needs them. Reusable installed toolchains and technical dependencies are the sole exception: place them in corp-v1-<code>-delivery/cache/, never in a Task workspace. A repository branch, clone, Task evidence file, or other Task-local support folder outside the selected Task directory does not satisfy this gate.

Implementation Entry Gate

Before claiming a Task for Feature implementation, verify in project documentation:

• Feature ID and parent Epic;
• exact Approved for Implementation evidence from the primary Architecture owner the active project authority or the active project authority as backup;
• linked FRs/NFRs and accepted solution/ADR context;
• task breakdown and dependencies;
• target version and status;
• acceptance evidence expected from delivery;
• exact Task READY_FOR_DELIVERY evidence, which itself records Focus admission by the active project authority; and
• an approved UI/UX package from the active UI/UX authority or the active project authority as backup when the task changes user-facing design.

Delivery must verify the Feature decision and exact Task READY_FOR_DELIVERY state before initial coding, then claim the Task by moving it directly to IN_PROGRESS. Continue claimed work in IN_PROGRESS while retaining the original handoff evidence. Do not require a second Focus admission after READY_FOR_DELIVERY or infer missing evidence from broad delegation, silence, CI, a Board wave, or a planning status. When a record is absent, route the exact owning action to Scope, Architecture, or Kanban rather than creating an out-of-scope lifecycle or flow mutation inside an implementation change.

Immediate Wave-Start Visibility Gate

Before any implementation or repository content change begins on a newly claimed the adopted project Task, establish and verify all of these Gitea checkpoints:

1. Create the dedicated local branch with the required Task branch name, create an empty kickoff commit if needed, and push that exact branch immediately.
2. Open a visible pull request from that exact branch to test before editing a repository file. Do not wait for implementation, tests, review, or a finished diff.
3. Put the Task ID, wave, planned scope, and current Task state in the PR so the active project authority and the team can monitor progress from the beginning.
4. Read the PR and remote ref back, then prove that the local branch name exactly equals the remote branch and PR head ref, the local kickoff commit equals the remote branch head, and the PR base is test.
5. Only after the remote branch and visible pull request already exist and all identities match may Delivery edit tests, source, configuration, documentation, or other repository content.

No repository file may be edited before this gate passes. A differently named local convenience branch that merely tracks the PR branch does not pass, because it hides the branch identity during status reporting and makes accidental publication to the wrong ref easier. When resuming an existing worktree, fetch the PR head explicitly, require the current local branch name to equal the PR head ref, and fast-forward before editing; if the names differ, repair the local branch identity without force-pushing or creating a competing PR.

One Task requires one dedicated branch and one visible PR unless the adopted project Architecture or the active project authority explicitly approves a different grouping. Do not hide several independently deliverable Tasks behind a shared wave branch. If Gitea refuses a no-diff PR, create and push an empty kickoff commit—never a filler file change—then open the PR. A locally created worktree, unpushed branch, compare URL, or push without PR readback does not satisfy this gate.

Branch and pull-request naming contract

For every the adopted project delivery Task, use this exact source-branch shape:

<release>/<TASK_ID>-<short-explanation>-<attempt-digit>

Example:

0.1.0/TASK-0049-persist-simulation-metadata-1

• <release> is the Task's exact target release, without a leading v. Do not derive it from a package manifest, invent it, or replace it with unreleased, next, or a wave label.
• <TASK_ID> is the exact Task ID, preserving its uppercase spelling.
• <short-explanation> is a concise lowercase ASCII kebab-case description (a-z, 0-9, and single hyphens only).
• <attempt-digit> is an unpadded positive decimal attempt number. Start at 1; increment it only when a new branch/PR attempt is required. Never reuse an attempt number for the same release, Task, and explanation.
• The complete branch must pass git check-ref-format --branch, contain exactly one /, and remain a valid Gitea branch ref. Spaces, repeated separators, .., @{, backslash, control characters, and the Git-forbidden characters ~ ^ : ? * [ are not allowed.
• Resolve collisions against freshly fetched local and remote refs before creating the branch. Never force-push or repurpose an earlier attempt.

The Gitea pull-request title must exactly equal the source branch name. Gitea's PR API treats the title as a string rather than a Git ref, but using the exact branch value provides one unambiguous release/Task/attempt identity across the branch list, PR list, API, CI, and evidence records. Do not prepend feat:, fix:, an emoji, a wave label, or other prose to the title.

Before creating the PR, verify the Gitea technical prerequisites: the source branch is pushed, the base branch is exactly test, head and base differ, the branch contains a commit not already in test, and no open PR already exists for the same head/base pair. Create the PR with explicit title, head, base, and body fields. The body must record the Task ID, release, attempt, wave, planned scope, Task state, validation plan, and requirement/ADR links. Read the PR back and require exact title, head ref/SHA, and test base; a compare URL or successful API response alone is not evidence that the PR contract is satisfied.