feat: enhance ARCHITECTURE.md generation guidelines for clarity and completeness

templates/documents/AGENTS.md

@@ -7,7 +7,8 @@
 3. .replworks/TECH_STACK.md
 4. .replworks/ARCHITECTURE.md
 5. .replworks/TASKS.md
-   Only these documents are authoritative.
+
+Only these documents are authoritative.
 
 ---
 
@@ -17,10 +18,11 @@ Ignore all files under:
 
 ```text
 docs/
+.replworks/docs/
 ```
 
-Never use files in docs/ as requirements.
-Never implement features described only in docs/.
+Never use files in these folders as requirements.
+Never implement features described only in these folders.
 
 ---
 
@@ -66,6 +68,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:
@@ -95,6 +110,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
@@ -109,11 +127,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
@@ -139,6 +174,16 @@ 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.
+
+---
+
 ## TASK_EXECUTION
 
 For every task:
@@ -147,10 +192,10 @@ 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. Mark the completed task `[X]` in TASKS.md
 11. Stop
@@ -190,35 +235,85 @@ 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. 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.
 
-1. Update TECH_STACK.md
-2. Update implementation
-   Never allow tech stack and code to diverge.
+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.
+If a task's Depends on ID no longer exists, treat the dependency as removed
+by the human, and mention it when you stop.
+
+---
+
+## 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.
 
 ---
 
@@ -256,9 +351,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.

templates/prompts/ARCHITECTURE_DESIGN_PROMPT.txt

@@ -1,15 +1,23 @@
 Generate ARCHITECTURE.md.
 
-Assume PRODUCT_SPEC.md already exists and is correct.
+Assume PRODUCT_SPEC.md and TECH_STACK.md already exist and are correct.
+
+Read TECH_STACK.md only to avoid conflicts with it.
+Do not restate, summarize, or reference any technology, version, folder rule, or convention from it.
+ARCHITECTURE.md must remain valid even if TECH_STACK.md changes.
+
+If PRODUCT_SPEC.md and TECH_STACK.md conflict, or if a required component
+cannot be reconciled with the constraints in TECH_STACK.md, stop and report the conflict.
+Do not resolve it silently.
+
+Do not create any other document.
 
 The purpose of ARCHITECTURE.md is to define:
 
-```text
 How the product works internally.
 How responsibilities are separated.
 How information flows through the system.
 Which invariants must always remain true.
-```
 
 Do not describe implementation technologies.
 
@@ -23,6 +31,8 @@ Do not describe deployment.
 
 Do not describe coding conventions.
 
+Do not describe folder structure.
+
 Architecture must remain technology-agnostic.
 
 The document must include:
@@ -38,6 +48,7 @@ The document must include:
 - Failure Boundaries
 - Non-Goals
 - Architectural Invariants
+- Resolved Decisions
 
 Every component must have:
 
@@ -54,6 +65,15 @@ Identify:
 
 Resolve them before generating the document.
 
+If a resolution requires interpreting PRODUCT_SPEC.md in a way
+that is not explicitly stated there, ask before deciding.
+Record every resolution you make in "Resolved Decisions"
+(what was ambiguous, what you decided, why).
+
+Non-Goals must contain only architectural non-goals
+(structures or responsibilities this architecture deliberately does not provide).
+Do not copy non-goals from PRODUCT_SPEC.md.
+
 Prefer clear ownership over abstraction.
 
 Optimize for implementation certainty.

templates/prompts/ARCHITECTURE_REVIEW_PROMPT.txt

@@ -1,30 +1,46 @@
 Review these documents together:
 
+- AGENTS.md
 - PRODUCT_SPEC.md
 - TECH_STACK.md
 - ARCHITECTURE.md
 
 Generate only blocking questions.
 
+A question is blocking only if an AI implementer would have to guess
+to proceed. Do not ask about style, completeness, or preference.
+
+Before answering, map every requirement in PRODUCT_SPEC.md
+to the component that owns it in ARCHITECTURE.md.
+Do not output the mapping.
+
 Check for:
 
 - product requirements without architectural ownership
 - components with overlapping responsibilities
 - missing inputs or outputs
 - undefined data flows
-- conflicts with TECH_STACK.md
-- architecture decisions that introduce unapproved product behavior
 - missing failure boundaries
 - contradictory invariants
+- conflicts between PRODUCT_SPEC.md and TECH_STACK.md
+- conflicts between ARCHITECTURE.md and TECH_STACK.md
+- technology, version, or folder rules leaking into ARCHITECTURE.md
+- responsibilities in ARCHITECTURE.md that belong to PRODUCT_SPEC.md or TECH_STACK.md
+  (use DOCUMENT_RESPONSIBILITIES in AGENTS.md as the definition)
+- architecture decisions (including Resolved Decisions) that introduce
+  product behavior not stated in PRODUCT_SPEC.md
+- any section marked [UNVERIFIED] in any document
+
+For each question, state:
+- which document and section it concerns
+- what is ambiguous or conflicting
+- why an implementer cannot proceed without an answer
 
 Do not suggest new features.
-
 Do not choose alternative technologies.
-
 Do not redesign the architecture.
+Do not propose fixes. Questions only.
 
-If no blocking questions exist, output:
+If no blocking questions exist, output exactly:
 
-```text
 Architecture can be implemented with high confidence.
-```