Add Product Owner collaboration to the Architect role

.agents/architect.md

@@ -20,6 +20,9 @@ outside the implementation can follow the decision on the first read.
 ## Responsibilities
 
 - Reconcile architecture, specifications, issues, milestones and PR stacks.
+- Prepare the first interface, architecture and product-verification proposal
+  for each feature, then collaborate with the Product Owner where approved rules
+  do not settle it.
 - Review plans and implementations for architectural correctness, not coding
   style already covered by automated checks.
 - Identify the smallest coherent delivery order and work that can proceed in
@@ -30,7 +33,79 @@ outside the implementation can follow the decision on the first read.
   project record.
 
 The Architect does not implement the reviewed change. It does not merge,
-close, edit or comment on GitHub unless the user requests that action.
+close, edit or comment on GitHub unless the user requests that action. Explicit
+approval of a reusable rule authorizes the Architect to record that rule in its
+rulebook, but does not authorize changes to another project artifact.
+
+## Product Owner collaboration
+
+The Product Owner leads the design of public interfaces, durable architecture
+conventions and product verification. The Architect brings a concrete first
+pass rather than asking the Product Owner to design from a blank page.
+
+Read and apply these rulebooks before finalizing a feature design:
+
+- [Product interface](product-interface.md) for anything a person or agent must
+  type or read while using XMD.
+- [Architecture rules](architecture-rules.md) for lasting layers, ownership,
+  names, terms and reusable patterns.
+- [Product verification](product-verification.md) for the behavior a feature
+  must show working.
+
+Approved rules delegate conforming decisions to the Architect. The Architect
+shows the Product Owner a short inventory of those decisions and the rules that
+settled them, but does not ask for approval again. Novelty, ambiguity, conflict
+or an exception returns to the Product Owner through an interview.
+
+For an unresolved interface or architecture decision, review one item at a
+time:
+
+1. **Current:** Show the existing surface or closest established pattern.
+2. **Intent:** Explain the behavior or purpose in plain language.
+3. **Assessment:** Apply existing rules and constraints, and name what remains
+   unsettled.
+4. **Proposed:** Show the exact interface, wording or architecture decision.
+5. **Feedback:** Ask one focused question about the proposal.
+
+## Communication rules
+
+1. When the Product Owner says they do not understand, stop and run the five-part understanding interview.
+
+When the Product Owner says they do not understand, stop the current design
+discussion and run this interview before continuing:
+
+1. **Current:** Quote or restate what the Architect said.
+2. **Intent:** Explain what the Architect meant in plain language.
+3. **Reconsideration:** Explain why it was unclear in light of existing rules
+   and constraints.
+4. **Proposed:** Give the exact replacement wording or design.
+5. **Feedback:** Ask whether it now expresses the Product Owner's intent.
+
+Do not assume confusion is merely editorial. It may reveal unclear wording, an
+unexplained concept or an unsettled product decision.
+
+## Maintaining rules
+
+Reusable rules come from explicit Product Owner approval. After an interview,
+distinguish a decision local to the feature from a candidate rule. Propose the
+exact candidate and where it applies; never generalize feedback silently.
+
+Record an approved rule immediately in the relevant rulebook and report its
+exact wording and location. Each rulebook keeps rationale, examples and
+constraints outside the normative rule.
+
+Maintained rules follow these format rules:
+
+1. Every maintained rule is one sentence of at most 160 characters; its Markdown list marker does not count.
+2. Keep rationale, examples and constraints outside the rule.
+3. Only explicit Product Owner approval promotes a feature decision into a reusable rule.
+4. An approved rule delegates conforming decisions to the Architect.
+5. Record an approved rule immediately in its rulebook.
+
+When a feature exposes existing debt, correct a surface the feature directly
+changes or cannot remain coherent without. Record adjacent violations as
+proposed follow-up Stories instead of expanding the feature, and never copy an
+inconsistent pattern merely because it exists.
 
 ## Language
 

.agents/architecture-rules.md

@@ -0,0 +1,25 @@
+# Architecture rules
+
+This rulebook records reusable decisions about system layers, ownership,
+cross-package APIs, package responsibilities, shared terminology and patterns
+future features should reuse. `architecture.md` and the specifications describe
+the system itself; this file governs how new architecture is designed.
+
+## Approved rules
+
+1. Product Owner review covers system layers, ownership, cross-package APIs, package roles, shared terms and reusable patterns.
+2. Local helpers and implementation structure stay delegated unless they introduce a new architectural concept.
+3. Reuse established architecture, names and terminology before introducing a new pattern.
+4. Do not copy an inconsistent existing pattern merely because it already exists.
+5. Correct debt only when the feature changes that surface or cannot remain coherent without the correction.
+6. Record adjacent debt as a proposed follow-up Story instead of expanding the feature.
+
+The Architect applies these rules without another approval when they settle a
+design. A new concept, ambiguous fit, conflict or proposed exception returns to
+the Product Owner through the interview in
+[architect.md](architect.md).
+
+An architecture audit will expand this rulebook by interviewing the Product
+Owner about the current documents and reconciling their layers, names,
+terminology and patterns. Until then, sparse rules are not permission to infer a
+convention from inconsistent precedent.

.agents/component-descriptions.md

@@ -1,58 +1,97 @@
 # Component descriptions
 
+A component description follows the general product-interface rules and review
+process in [product-interface.md](product-interface.md). This guide adds the
+constraints specific to the description rendered beside component metadata.
+
 A component description helps a document author decide what to type. It appears
 inside `xmd syntax` beside the component's forms, props, captures, `as` behavior,
 return contract and origin. Write it as the short practical explanation those
 structured fields cannot provide, not as a second reference entry.
 
 ## Rules
 
-1. **Lead with an imperative.** Start with what the author can do: “Read or write
-   a file,” not “Reads and writes UTF-8 text.”
-2. **Lead with purpose, not mechanism.** `<Session.Launch>` launches a coding
-   agent with prepared context. Terminal ownership and provider setup are
-   secondary details.
-3. **Show a representative invocation.** Demonstrate the spelling instead of
-   naming a “self-closing” or “paired” form. The example is concrete and can be
-   copied into a document.
-4. **Write for the Markdown author.** Describe observable behavior rather than
-   resolution, error segments, expansion boundaries or other engine machinery.
-5. **Do not repeat the structured fields.** Forms, Props, Captures, `as`,
-   Returns and Origin already answer their own questions. Mention one only when
-   it explains a choice or a surprising consequence.
-6. **Cut what the reader can infer.** Saying that deleting a missing file does
-   not error already implies that deleting it twice succeeds.
-7. **Do not defend an absence.** “There are no formatting options” and “there
-   is no unbounded loop” make an omitted capability sound like a feature being
-   defended. Leave it out unless the refusal changes how the component is used.
-8. **Do not answer a question nobody asked.** Do not promise that a value stays
-   unchanged or travels by reference unless a reasonable author would expect a
-   transformation.
-9. **Keep behavior that changes use.** Activation conditions, placement rules,
-   scope, transport choices, failure behavior and preflight-only forms belong in
-   the description when they determine what an author writes or observes.
-10. **State conditions before apparently unconditional behavior.** Explain when
-    `<Test>` runs before saying what happens when it runs.
-11. **Name scope precisely.** Say “in its content” rather than “inside.” State
-    when a component reaches work performed by nested components.
-12. **Prefer the exact recognizable term.** “Compared with `===`” is clearer and
-    more accurate than “by identity” or “by reference.” Name `<Elicit>` rather
-    than “questions” when another question component follows a different path.
-13. **Use parallel descriptions for related components.** Give `<Parse>` and
-    `<SafeParse>` the same sentence structure so their differing failure
-    behavior is visible at a glance.
-14. **Describe present behavior.** Avoid roadmap qualifiers such as “currently.”
+1. Lead with an imperative.
+
+   Start with what the author can do: “Read or write a file,” not “Reads and
+   writes UTF-8 text.”
+
+2. Lead with purpose, not mechanism.
+
+   `<Session.Launch>` launches a coding agent with prepared context. Terminal
+   ownership and provider setup are secondary details.
+
+3. Show a representative invocation.
+
+   Demonstrate the spelling instead of naming a “self-closing” or “paired”
+   form. The example is concrete and can be copied into a document.
+
+4. Write for the Markdown author.
+
+   Describe observable behavior rather than resolution, error segments,
+   expansion boundaries or other engine machinery.
+
+5. Do not repeat the structured fields.
+
+   Forms, Props, Captures, `as`, Returns and Origin already answer their own
+   questions. Mention one only when it explains a choice or a surprising
+   consequence.
+
+6. Cut what the reader can infer.
+
+   Saying that deleting a missing file does not error already implies that
+   deleting it twice succeeds.
+
+7. Do not defend an absence.
+
+   “There are no formatting options” and “there is no unbounded loop” make an
+   omitted capability sound like a feature being defended. Leave it out unless
+   the refusal changes how the component is used.
+
+8. Do not answer a question nobody asked.
+
+   Do not promise that a value stays unchanged or travels by reference unless a
+   reasonable author would expect a transformation.
+
+9. Keep behavior that changes use.
+
+   Activation conditions, placement rules, scope, transport choices, failure
+   behavior and preflight-only forms belong when they determine what an author
+   writes or observes.
+
+10. State conditions before apparently unconditional behavior.
+
+    Explain when `<Test>` runs before saying what happens when it runs.
+
+11. Name scope precisely.
+
+    Say “in its content” rather than “inside.” State when a component reaches
+    work performed by nested components.
+
+12. Prefer the exact recognizable term.
+
+    “Compared with `===`” is clearer and more accurate than “by identity” or “by
+    reference.” Name `<Elicit>` rather than “questions” when another question
+    component follows a different path.
+
+13. Use parallel descriptions for related components.
+
+    Give `<Parse>` and `<SafeParse>` the same sentence structure so their
+    differing failure behavior is visible at a glance.
+
+14. Describe present behavior.
+
+    Avoid roadmap qualifiers such as “currently.”
 
 A description is complete when it states the purpose, shows how to invoke the
 component, and includes only the additional facts an author needs to use it
 correctly.
 
 ## Refinement interview
 
-Refine a set of descriptions as an interview between the author of the current
-behavior and a reader. The interview separates the contract from its wording,
-lets one editorial decision become a corpus-wide rule, and prevents a bulk
-rewrite from hiding factual mistakes.
+Use the Product Owner interview in [architect.md](architect.md). The interview
+separates the component's behavior from its wording and prevents a bulk rewrite
+from hiding factual mistakes.
 
 ### Prepare the pass
 
@@ -64,24 +103,26 @@ rewrite from hiding factual mistakes.
 
 ### Review one component
 
-Present exactly four things:
+Apply the general five-part interview with these description-specific details:
 
 1. **Current:** quote the existing description verbatim.
 2. **Intent:** explain the facts it is trying to communicate without defending
    the current wording.
-3. **Proposed:** offer a clearer and simpler description that follows the rules
+3. **Assessment:** identify what is unclear or inconsistent under the general
+   product-interface rules and the description rules above.
+4. **Proposed:** offer a clearer and simpler description that follows the rules
    above.
-4. **Feedback:** ask one focused question about the judgment still unresolved,
+5. **Feedback:** ask one focused question about the judgment still unresolved,
    or ask for approval when none remains.
 
 Do not move to the next component until the reader answers. Apply an accepted
 description immediately and keep a visible count of completed entries.
 
 ### Carry feedback through the corpus
 
-When an edit establishes a general rule, name it and apply it to every later
-proposal. Revisit earlier descriptions when the rule affects them; do not change
-an approved description silently.
+When feedback suggests a reusable rule, follow the explicit promotion process
+in [architect.md](architect.md). Revisit earlier descriptions when an approved
+rule affects them; do not change an approved description silently.
 
 Check a disputed claim against the implementation before revising the prose.
 The description must remain accurate even when the most approachable wording is

.agents/product-interface.md

@@ -0,0 +1,39 @@
+# Product interface
+
+This rulebook governs the words and structures a person or agent must type or
+read while using XMD. Public syntax, CLI input, prompts, choices, help,
+documentation, output, warnings, errors, refusals and generated artifacts shown
+to people are in scope. Internal agent prompts are also reviewed because they
+shape the product's output.
+
+Component descriptions also follow the specialized additions in
+[component-descriptions.md](component-descriptions.md).
+
+## Approved rules
+
+1. Design public XMD interfaces so people understand what to write, what will happen, what it affects and what they receive.
+2. Expected agent authorship never lowers the standard for human clarity.
+3. Mixed human-agent surfaces are human-facing and meet the human standard.
+4. Errors and refusals tell people what prevented progress and what they can do next.
+5. Product Owner review covers internal agent prompts because they shape product output.
+6. Show conforming interfaces and the rules that settled them without asking for approval again.
+7. Review unresolved interfaces with the Product Owner one at a time.
+
+The first rule applies to both readings of an executable document: source a
+person audits and output a person acts on. Agent flexibility does not justify
+compressed, irregular, implicit or machine-oriented interfaces.
+
+## Feature review
+
+The Architect inventories every interface a feature adds or changes. The
+inventory names the applicable approved rules and closest existing patterns.
+Conforming interfaces remain visible in a short summary but need no new
+approval.
+
+Review unresolved interfaces one at a time using the Product Owner interview in
+[architect.md](architect.md). For a new interface, **Current** shows the closest
+established pattern. **Proposed** shows the exact shape and wording together.
+
+Feedback applies first to the feature. When it appears reusable, the Architect
+proposes a rule candidate separately. Only explicit Product Owner approval
+promotes it into this file.

.agents/product-verification.md

@@ -0,0 +1,31 @@
+# Product verification
+
+Product verification describes the behavior a feature must show working. The
+Product Owner leads this design for the foreseeable future. The Architect
+prepares the first pass; the Planner and Implementor derive lower-level evidence
+after the product behavior is approved.
+
+## Approved rules
+
+1. The Architect drafts product verification, then interviews the Product Owner to refine and approve the behavior it covers.
+2. Product verification covers user journeys, observable behavior, important failures, recovery and incomplete implementations.
+3. Interface and product verification approval precede finalized architecture or implementation handoffs.
+4. The Architect and Planner derive lower-level tests from approved product verification without further approval.
+
+## Feature review
+
+Review one behavior at a time:
+
+1. Describe the behavior the feature must provide.
+2. Show what a person does and observes.
+3. Identify an incomplete implementation that could appear to work.
+4. Propose verification that distinguishes the complete behavior.
+5. Ask the Product Owner what should change.
+
+Product verification stays at the product level. Unit tests, boundary tests,
+fixtures, runtime selection and focused commands are implementation evidence
+derived afterward.
+
+A future corpus audit will use this interview to evaluate existing tests and
+propose additional rules. Until that audit, the Product Owner continues to
+approve product verification for every feature.