60 lines
6.4 KiB
Markdown
60 lines
6.4 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
<release>/<TASK_ID>-<short-explanation>-<attempt-digit>
|
|
```
|
|
|
|
Example:
|
|
|
|
```text
|
|
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.
|