docs: define durable fix branch workflow

2026-08-15 14:18:13 +07:00
parent 8be1b754e1
commit f013ad7707
6 changed files with 87 additions and 0 deletions
@@ -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.
 - 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.
 - 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.
@@ -62,6 +62,14 @@ npm ci
 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

 ### PostgreSQL 18.4
@@ -126,6 +126,12 @@ companion record under [`docs/tests`](docs/tests/README.md).
 | `work/attendance` | Policy, calendar, attendance workflows |
 | `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
 strict RED-to-GREEN TDD, add Javadoc during implementation, and update the
 matching Markdown evidence record before each milestone commit.
@@ -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
 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

 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.