cable8mm · Oct 6, 2026 · Oct 6, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -7,19 +7,21 @@
 3. .replworks/TECH_STACK.md
 4. .replworks/ARCHITECTURE.md
 5. .replworks/TASKS.md
-   Only these documents are authoritative.
+
+Only these documents are authoritative.
 
 ---
 
 ## IGNORE
 
 Ignore all files under:
 
-- `/docs/**/*`
-- `/templates/**/*`
+```text
+.replworks/docs/
+```
 
-Never use files in `/docs/**/*` and `/templates/**/*` as requirements.
-Never implement features described only in `/docs/**/*` and `/templates/**/*`.
+Never use files in these folders as requirements.
+Never implement features described only in these folders.
 
 ---
 
@@ -65,6 +67,19 @@ everything else
 
 ---
 
+## CONFLICT_HANDLING
+
+When documents conflict:
+
+1. Follow the higher-priority document.
+2. Report the conflict to the human.
+3. Fix the lower-priority document together with the human before continuing.
+
+Never resolve a conflict silently.
+Never leave a conflict in place after the task is complete.
+
+---
+
 ## DOCUMENT_RESPONSIBILITIES
 
 PRODUCT_SPEC.md defines:
@@ -94,6 +109,9 @@ What should be implemented next.
 
 Do not move responsibilities between documents.
 
+ARCHITECTURE.md must not contain technology, versions, or folder rules.
+TECH_STACK.md must not contain component responsibilities or data flows.
+
 ---
 
 ## EXTERNAL_BOUNDARY
@@ -108,11 +126,28 @@ third-party API
 browser runtime behavior
 ```
 
+Libraries that run inside this codebase's own process are not an external boundary.
+
+---
+
+## UNVERIFIED_MARK
+
+Add `[UNVERIFIED]` to the heading of the section that owns the gap.
+
+```text
+Gaps in what the product is or does          -> PRODUCT_SPEC.md
+Gaps in how the product must be implemented  -> TECH_STACK.md
+Gaps in how the product works                -> ARCHITECTURE.md
+```
+
+Clear the mark only after human confirmation.
+
 ---
 
 ## IMPLEMENTATION_RULES
 
 Implement only the selected task.
+Exception: HUMAN_OWNED_CHANGES.
 Do not implement:
 
 ```text
@@ -138,6 +173,13 @@ ARCHITECTURE.md
 
 ---
 
+## TASK_SELECTION
+
+Implement the task named by the human.
+If none is named, use the first unchecked task in TASKS.md, from top to bottom.
+
+---
+
 ## TASK_EXECUTION
 
 For every task:
@@ -146,12 +188,13 @@ For every task:
 2. Read TECH_STACK.md
 3. Read ARCHITECTURE.md
 4. Read task definition
-5. If the task touches a domain not covered by verified knowledge in PRODUCT_SPEC.md or ARCHITECTURE.md: stop. Mark the relevant section UNVERIFIED. Do not implement against an UNVERIFIED section. Require explicit human confirmation before continuing.
+5. If the task touches a domain that is not covered by verified knowledge in PRODUCT_SPEC.md, TECH_STACK.md, or ARCHITECTURE.md: stop. Mark the relevant section UNVERIFIED (see UNVERIFIED_MARK). Do not implement against an UNVERIFIED section. Require explicit human confirmation before continuing.
 6. Implement
 7. Write unit tests for internal logic
-8. If the task touches an EXTERNAL_BOUNDARY: write an E2E test against the live boundary. A mocked test alone does not satisfy this step.
+8. If the task touches an EXTERNAL_BOUNDARY: write an E2E test against the live boundary. A mocked test alone does not satisfy this step. If the live boundary is unreachable, stop and report. Do not mark the task `[X]`.
 9. Run all tests
-10. Stop
+10. Mark the completed task `[X]` in TASKS.md
+11. Stop
     Do not start another task automatically.
 
 ---
@@ -188,35 +231,83 @@ Stop.
 Do not invent requirements.
 ```
 
-Update PRODUCT_SPEC.md, and clear the UNVERIFIED mark only after human confirmation, before implementation continues.
+1. Propose the change to the human.
+2. Update PRODUCT_SPEC.md only after human confirmation.
+3. Clear the UNVERIFIED mark only after human confirmation.
+4. Continue implementation.
 
 ---
 
 ## TECH_STACK_CHANGES
 
-If implementation requires tech stack changes:
+If implementation requires tech stack changes, or a TECH_STACK.md section is marked UNVERIFIED:
 
-1. Update TECH_STACK.md
-2. Update implementation
-   Never allow tech stack and code to diverge.
+1. Stop. Propose the change to the human.
+2. If the change conflicts with PRODUCT_SPEC.md, see CONFLICT_HANDLING.
+3. Update TECH_STACK.md only after human confirmation.
+4. Clear the UNVERIFIED mark only after human confirmation.
+5. Update implementation.
+
+Never allow tech stack and code to diverge.
 
 ---
 
 ## ARCHITECTURE_CHANGES
 
 If implementation requires architecture changes, or an ARCHITECTURE.md section is marked UNVERIFIED:
 
-1. Update ARCHITECTURE.md
-2. Clear the UNVERIFIED mark only after human confirmation
-3. Update implementation
-   Never allow architecture and code to diverge.
+1. Stop. Propose the change to the human.
+2. If the change conflicts with PRODUCT_SPEC.md or TECH_STACK.md, see CONFLICT_HANDLING.
+3. Update ARCHITECTURE.md only after human confirmation.
+4. Clear the UNVERIFIED mark only after human confirmation.
+5. Update implementation.
+
+Never allow architecture and code to diverge.
 
 ---
 
 ## TASK_CHANGES
 
-If implementation invalidates a task:
-Update TASKS.md.
+If implementation invalidates a task, or PRODUCT_SPEC.md changes:
+
+1. Propose the TASKS.md change to the human.
+2. Update TASKS.md only after human confirmation.
+
+Never change an existing task ID.
+Never regenerate TASKS.md from scratch.
+
+These rules bind the AI. The human may edit TASKS.md directly at any time.
+Human edits are authoritative.
+
+---
+
+## HUMAN_OWNED_CHANGES
+
+Content and visual design are human-owned.
+They are not specified in PRODUCT_SPEC.md and are not tracked in TASKS.md.
+
+```text
+Content:       wording, copy, translations, images, data text
+Visual design: styling, spacing, colors, typography, imagery, visual polish
+```
+
+Not human-owned: which screens and elements exist, their purpose,
+their arrangement relative to each other, their states, and their interactions.
+These are specified in PRODUCT_SPEC.md.
+
+When the human explicitly asks for such a change in the session:
+
+1. Make only that change.
+2. Do not change behavior, screens, elements, states, or interactions
+   defined in PRODUCT_SPEC.md.
+   If the change would, stop (see PRODUCT_SPEC_CHANGES).
+3. Do not record the change in TASKS.md or any other document.
+4. Run the verification commands defined in TECH_STACK.md.
+5. Stop.
+
+Never make such changes on your own initiative.
+If a task needs content or styling and none is provided,
+use neutral placeholders and report them when you stop.
 
 ---
 
@@ -254,9 +345,11 @@ Task is complete only when:
 - product requirements satisfied
 - architectural requirements satisfied
 - tech stack constraints satisfied
-- acceptance criteria satisfied
+- the task's acceptance criteria in TASKS.md satisfied
 - no UNVERIFIED sections remain in scope for this task
+- no unresolved document conflicts remain
 - code runs
 - unit tests pass
 - E2E tests pass for any EXTERNAL_BOUNDARY code touched
-  Then stop.
+
+Then stop.
diff --git a/templates/documents/AGENTS.md b/templates/documents/AGENTS.md
@@ -17,7 +17,6 @@ Only these documents are authoritative.
 Ignore all files under:
 
 ```text
-docs/
 .replworks/docs/
 ```
 
@@ -177,10 +176,7 @@ ARCHITECTURE.md
 ## TASK_SELECTION
 
 Implement the task named by the human.
-If none is named, use the first unchecked MVP task in TASKS.md
-whose dependencies are all marked `[X]`.
-
-Do not select tasks from the Future section unless the human names them.
+If none is named, use the first unchecked task in TASKS.md, from top to bottom.
 
 ---
 
@@ -282,8 +278,6 @@ Never regenerate TASKS.md from scratch.
 
 These rules bind the AI. The human may edit TASKS.md directly at any time.
 Human edits are authoritative.
-If a task's Depends on ID no longer exists, treat the dependency as removed
-by the human, and mention it when you stop.
 
 ---