docs: define durable fix branch workflow

This commit is contained in:
sechmachine
2026-08-15 14:18:13 +07:00
parent 8be1b754e1
commit f013ad7707
6 changed files with 87 additions and 0 deletions
+1
View File
@@ -120,6 +120,7 @@ For a multi-branch iteration:
- Use one worktree and one named owner/subagent per branch. Tell every owner that other agents share the repository and it must not revert others' work. - Use one worktree and one named owner/subagent per branch. Tell every owner that other agents share the repository and it must not revert others' work.
- Before starting assigned module work, every owner verifies its worktree is clean, fetches or uses the taskmaster-verified latest `main`, and fast-forwards its persistent branch to that exact main SHA. Do not build new work on a stale pre-integration branch, and do not use a merge that would rewrite or discard branch history. - Before starting assigned module work, every owner verifies its worktree is clean, fetches or uses the taskmaster-verified latest `main`, and fast-forwards its persistent branch to that exact main SHA. Do not build new work on a stale pre-integration branch, and do not use a merge that would rewrite or discard branch history.
- A targeted repair uses a clean, isolated `work/fix/<feature>/<what-fix>` branch and worktree from the taskmaster-verified current `main`. Do not use `work/<feature>/fix/<what-fix>`: the persistent `work/<feature>` ref already occupies that Git ref prefix.
- Establish and commit the platform foundation before dependent persistence work. - Establish and commit the platform foundation before dependent persistence work.
- Exchange only full immutable SHAs from clean worktrees; never merge a moving branch or ambiguous short SHA. - Exchange only full immutable SHAs from clean worktrees; never merge a moving branch or ambiguous short SHA.
- Preserve branch ownership. Request a producer-owned service/DTO boundary instead of reading its tables from a consumer. - Preserve branch ownership. Request a producer-owned service/DTO boundary instead of reading its tables from a consumer.
+8
View File
@@ -62,6 +62,14 @@ npm ci
npm run build npm run build
``` ```
### Use an isolated repair branch
For a targeted repair, start a clean worktree from the taskmaster-verified
current `main` on `work/fix/<feature>/<what-fix>`. Keep it separate from the
five persistent `work/<feature>` branches. Do not use
`work/<feature>/fix/<what-fix>` because the persistent `work/<feature>` ref
already occupies that Git ref prefix.
## 3. Start the development containers ## 3. Start the development containers
### PostgreSQL 18.4 ### PostgreSQL 18.4
+6
View File
@@ -126,6 +126,12 @@ companion record under [`docs/tests`](docs/tests/README.md).
| `work/attendance` | Policy, calendar, attendance workflows | | `work/attendance` | Policy, calendar, attendance workflows |
| `work/reports-ui` | Shared UI, dashboards, reporting presentation | | `work/reports-ui` | Shared UI, dashboards, reporting presentation |
For a targeted repair, create a clean isolated branch and worktree from the
taskmaster-verified current `main` named
`work/fix/<feature>/<what-fix>`. Do not nest it as
`work/<feature>/fix/<what-fix>`: the persistent `work/<feature>` ref already
uses that Git ref prefix.
Iteration 2 work must start from the merged Iteration 1 `main`, continue with Iteration 2 work must start from the merged Iteration 1 `main`, continue with
strict RED-to-GREEN TDD, add Javadoc during implementation, and update the strict RED-to-GREEN TDD, add Javadoc during implementation, and update the
matching Markdown evidence record before each milestone commit. matching Markdown evidence record before each milestone commit.
+6
View File
@@ -120,6 +120,12 @@ Simple configuration or documentation changes use the smallest useful shell
check, followed by the affected Maven suite. Do not create an artificial Java check, followed by the affected Maven suite. Do not create an artificial Java
test only to check that a text file exists. test only to check that a text file exists.
Run that check from the clean targeted-fix branch named
`work/fix/<feature>/<what-fix>` when repairing one feature. Do not use
`work/<feature>/fix/<what-fix>`: a persistent `work/<feature>` ref already
occupies that Git ref prefix. Record the expected RED and the matching GREEN
shell output in the evidence record.
## 4. Useful commands ## 4. Useful commands
Run one test method: Run one test method:
@@ -0,0 +1,29 @@
# Access, Navigation, Icon, and Intern Picker Fix Plan
## Scope
Record the durable workflow for the targeted fixes in this plan. This plan does
not change product behavior, dependencies, schemas, or the five persistent
feature-branch ownership areas.
## Implementation steps
1. Prove RED: the contributor guides lack the realizable repair-branch name.
2. Add one branch rule everywhere contributors, coordinators, and requirement
reviewers rely on it: `work/fix/<feature>/<what-fix>` from verified `main`.
3. State why `work/<feature>/fix/<what-fix>` is invalid while its persistent
`work/<feature>` ref exists.
4. Regenerate the local SRS after amending the existing operational requirement;
do not add a requirement ID or a use case.
5. Prove GREEN with exact searches, requirement/use-case counts, local-link
resolution, and whitespace validation. Commit the tracked guidance locally;
do not push or merge.
## Exit criteria
- The tracked guides, design record, implementation plan, and evidence record
agree on the same repair-branch spelling.
- The local authoritative, explained, simple, and generated SRS catalogues keep
exactly 260 unique requirement IDs and the SRS keeps 14 use cases.
- The forbidden nested form is documented only as forbidden, not as a usable
branch name.
@@ -0,0 +1,37 @@
# Design Record: Durable Fix-Branch Workflow
- **Date:** 2026-08-15
- **Status:** Accepted
- **Related plan:** [Access, Navigation, Icon, and Intern Picker Fix Plan](../plans/2026-08-15-access-navigation-icon-intern-picker.md)
## Context
The repository keeps five persistent feature refs: `work/platform`,
`work/projects`, `work/tasks`, `work/attendance`, and `work/reports-ui`.
A proposed nested repair name such as `work/platform/fix/example` cannot coexist
with the existing `work/platform` ref because Git cannot use one ref as both a
leaf and a prefix.
## Decision
Use `work/fix/<feature>/<what-fix>` for each targeted repair. Create its clean,
isolated worktree from the taskmaster-verified current `main`. The `<feature>`
segment identifies the owning persistent area; it does not nest below that
persistent branch.
The forbidden form is `work/<feature>/fix/<what-fix>`. A repair owner preserves
other worktrees, records RED and GREEN evidence, commits locally, and does not
push or merge without separate authority.
## Consequences
- Persistent feature branches remain available for their iteration ownership.
- A repair can be reviewed and handed off as one immutable branch head.
- Contributor documentation, local coordination authority, and generated SRS
traceability use the same spelling.
## Validation
The documentation evidence record checks the required spelling, rejects the
nested form, verifies requirement counts and generated SRS use-case count, and
resolves local Markdown links.