agentme 0.30.3 → 0.31.0

package/.filedist-package.yml

@@ -27,6 +27,9 @@ sets:
     output:
       path: .
       gitignore: false
+      symlinks:
+        - source: .xdrs/**/skills/150-plan-mode-consistency
+          target: .agents/skills
     presets:
       - basic
 

package/.xdrs/agentme/edrs/application/skills/200-run-skill-tests/SKILL.md

@@ -27,7 +27,7 @@ Loads `SKILL.test.md` from a skill directory, runs each scenario by invoking the
    ```
 
    Then halt — do not proceed.
-4. Read `SKILL.test.md` in full. Parse the frontmatter (`skill`, `skill-version`) and all `### Scenario N:` sections. Each scenario has three sub-sections: `**Trigger / Input**`, `**Expected Behaviour**`, and `**Assertions**`.
+4. Read `SKILL.test.md` in full. Parse the frontmatter (`skill`, `skill-version`) and all `### Scenario N:` sections. Each scenario has three required sub-sections — `**Trigger / Input**`, `**Expected Behaviour**`, and `**Assertions**` — and one optional sub-section: `**Simulated Human Responses**`.
 5. Read `SKILL.md` in full to understand what the skill does. Verify that the `skill-version` in `SKILL.test.md` matches the `version` field in `SKILL.md` metadata. If they differ, output a WARNING and continue.
 
 ### Phase 2: Execute Scenarios
@@ -35,9 +35,13 @@ Loads `SKILL.test.md` from a skill directory, runs each scenario by invoking the
 For each scenario in order:
 
 1. Record the scenario title and number.
-2. Present the trigger/input to a fresh agent context with the target skill loaded, exactly as written in `**Trigger / Input**`. Do not add context beyond what the trigger specifies.
-3. Capture the full output from the skill execution.
-4. Move to Phase 3 for this scenario before executing the next.
+2. Check whether the scenario has a `**Simulated Human Responses**` sub-section. If present, parse it as an ordered list of canned responses to be injected sequentially each time the skill pauses for human input during this scenario.
+3. Present the trigger/input to a fresh agent context with the target skill loaded, exactly as written in `**Trigger / Input**`. Do not add context beyond what the trigger specifies.
+4. Whenever the skill pauses and asks a question or requests human input, inject the next unused response from the `**Simulated Human Responses**` list (in order). Continue until the skill finishes or the response list is exhausted.
+   - If the response list is exhausted before the skill finishes, record the remaining output as-is and note "Simulated responses exhausted" in the scenario result.
+   - If the scenario has no `**Simulated Human Responses**` section, run the skill until its first natural pause point and capture the output at that point.
+5. Capture the full output from the skill execution.
+6. Move to Phase 3 for this scenario before executing the next.
 
 ### Phase 3: Evaluate Assertions
 

package/.xdrs/agentme/edrs/application/skills/200-run-skill-tests/SKILL.test.md

@@ -45,3 +45,23 @@ You are an agent with the `200-run-skill-tests` skill loaded. The workspace has
 - [ ] Output references the resolved path of the skill directory.
 - [ ] Output does NOT contain any `### Scenario` execution section.
 - [ ] Output does NOT contain a `## Summary` report block.
+
+### Scenario 3: Injects simulated human responses when present
+
+**Trigger / Input**
+You are an agent with the `200-run-skill-tests` skill loaded. The workspace has a skill at `.xdrs/agentme/edrs/principles/skills/150-plan-mode-consistency` with both `SKILL.md` and `SKILL.test.md` present. Scenario 1 in that `SKILL.test.md` includes a `**Simulated Human Responses**` section with 9 ordered responses. The user says:
+
+"Test the skill at `.xdrs/agentme/edrs/principles/skills/150-plan-mode-consistency`"
+
+**Expected Behaviour**
+1. Skill reads `SKILL.test.md` and detects the `**Simulated Human Responses**` section in Scenario 1.
+2. When executing Scenario 1, the skill injects each listed response in order each time the target skill pauses for human input.
+3. Execution continues through all HITL pause points using the injected responses rather than waiting for a real human.
+4. If the response list is exhausted before the skill finishes, the runner notes "Simulated responses exhausted" and captures remaining output as-is.
+5. Assertions are evaluated against the full captured output after all injected responses are consumed.
+
+**Assertions**
+- [ ] Runner parses the `**Simulated Human Responses**` section and does not ask the user for input during Scenario 1 execution.
+- [ ] Output contains the Scenario 1 result section with individual assertion PASS/FAIL results.
+- [ ] Output does NOT contain any prompt asking the real user to respond on behalf of the simulated skill interaction.
+- [ ] If responses are exhausted, output notes "Simulated responses exhausted" for that scenario.

package/.xdrs/agentme/edrs/index.md

@@ -8,6 +8,7 @@ Propose changes via pull request. All changes must be verified for clarity and n
 
 Foundational standards, principles, and guidelines.
 
+- [150-plan-mode-consistency](principles/skills/150-plan-mode-consistency/SKILL.md) - **Plan mode consistency** — MANDATORY skill for ANY planning activity (plan, design, propose, outline, draft, brainstorm, architect). Read and follow in full before any execution begins. Must be read from XDRS even when not in `.agents/skills`. *(skill)*
 - [agentme-edr-012](principles/012-continuous-xdr-enrichment.md) - **Continuous xdr improvement policy** - Promote recurring delivery lessons into reusable XDRs
 - [agentme-edr-016](principles/016-cross-language-module-structure.md) - **Cross-language module structure** - Organize modules consistently across supported languages
 - [agentme-edr-017](principles/017-skill-testing.md) - **skill testing** - Mandates a `SKILL.test.md` co-located with every skill in scopes that follow agentme; defines test scenario format (trigger, expected behaviour, assertions) and requires execution before merging any skill change *(includes skill: [200-run-skill-tests](application/skills/200-run-skill-tests/SKILL.md))*

package/.xdrs/agentme/edrs/principles/017-skill-testing.md

@@ -45,6 +45,11 @@ specific enough that two independent agents produce comparable outputs.]
 **Expected Behaviour**
 [Numbered list of steps the skill must perform, derived from its Instructions section.]
 
+**Simulated Human Responses** *(optional — include when the skill has human-in-the-loop pauses)*
+1. [Exact text to inject as the human's answer to the first pause point.]
+2. [Answer to the second pause point.]
+...
+
 **Assertions**
 - [ ] [Specific, falsifiable check on the output or behaviour. Start with a verb.]
 - [ ] ...
@@ -57,6 +62,7 @@ Rules:
 - Assertion text MUST start with a verb ("Output contains …", "Skill asks …", "Review reports …").
 - MUST NOT duplicate SKILL.md content; reference phases by name only when needed.
 - `skill-version` in frontmatter MUST be updated whenever `version` in SKILL.md changes.
+- **Simulated Human Responses** is optional. Include it when the skill has human-in-the-loop pause points and automated testing is needed. Responses are injected in order at each pause; if responses are exhausted before the skill finishes, the runner captures the remaining output as-is.
 
 #### 03-execution-requirement
 

package/.xdrs/agentme/edrs/principles/skills/150-plan-mode-consistency/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: 150-plan-mode-consistency
+description: >
+  MANDATORY for ANY planning activity. Read and follow this skill in full whenever the user asks
+  to plan, design, propose, outline, draft, brainstorm, architect, or think through anything —
+  software features, systems, research, documents, processes, or any other task — before execution
+  begins. This skill defines the required pre-execution structured workflow. It MUST be read from
+  the XDRS repository even when not directly exposed in the .agents skills folder. Activate in
+  full mode for non-trivial tasks and in abbreviated mode (Phases 3–5 collapsed, Phase 4 marked
+  not applicable) for trivial single-step tasks.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+---
+
+## Overview
+
+Ensures that every plan is deeply validated through iterative consistency checks, visual externalization, and multi-angle challenges before execution starts. The skill is not designed to make human work easier — its purpose is to identify precisely where human experience, feeling, and domain knowledge are irreplaceable, and to demand that input before moving forward.
+
+**No-assumption rule**: The agent performs all analysis autonomously. Surface findings as questions only when they are dubious, non-obvious, risky, or require subjective judgment — obvious and deterministic findings must be stated and the agent must continue without pausing. For findings with major impact on downstream users or consumers (breaking changes, behavior regressions, removals), do not ask — emit a prominently formatted **SEVERE WARNING** with a clear description of the impact and continue. Do not defer questions to the end of a check, round, or phase — raise them as soon as they arise. The human is the oracle for domain knowledge, intent, and subjective decisions; the agent is the oracle for everything deterministic.
+
+**Task tracking rule**: Use the todo list tool throughout this entire skill. Before starting each phase, create a todo for it and mark it in-progress. Mark it completed immediately when done. For Phase 3 (consistency checks), create a todo for each check (a–g) at the start of each round and mark them individually. For Phase 5 (challenge angles), create a todo for each of the 11 angles before beginning Phase 5 and mark each completed after the human responds to any question raised, or immediately if no question was raised for that angle. An angle todo MUST NOT be marked complete if a subjective decision was resolved without asking the human — if this is detected, flag it as a HITL violation, re-open the todo, surface the decision to the human as a clarifying question, and only mark it complete after the human responds. This ensures no check, round, or angle is silently skipped and no subjective decision is self-resolved.
+
+**Round budget rule**: The entire skill runs on a global budget of at most 30 rounds. A round is one human interaction in which the agent asks 1–5 related questions together. Rounds are drawn from this shared budget across all phases in order. Stop early when two consecutive rounds return no new questions worth asking — do not exhaust the budget for its own sake.
+
+## Instructions
+
+### Phase 1: Activate Plan Mode
+
+1. Switch to plan mode. Do not write, edit, or execute anything until the plan is fully validated through Phase 6.
+2. State the goal in one sentence: what problem is being solved and what the expected outcome is.
+3. State the scope boundaries explicitly: what is included and what is explicitly excluded.
+4. Ask the human: "Does this goal statement and scope match your intent? Is anything missing or wrong?" Wait for the answer and incorporate it before continuing.
+
+### Phase 2: Research, Dependencies, and Draft Plan
+
+1. Research the existing context: relevant files, prior decisions, established conventions, and analogous patterns already in place.
+2. For each contextual input, constraint, or dependency found (existing files, prior decisions, external systems, in-progress work by others), surface non-obvious, risky, or subjective items to the human and ask only when needed. Batch 1–5 related questions into a single round when multiple items need human input. Proceed without asking for obvious or deterministic context items.
+3. Draft a plan with ordered steps, items to create or modify, and a verification step at the end.
+4. Present the draft and ask: "Does this match your intent? What am I missing?" Wait for the answer before continuing.
+
+### Phase 3: Iterative Consistency Checks
+
+**Trivial tasks**: Run exactly one abbreviated round covering only checks (a), (e), and (f). Skip the remaining checks and mark them as not applicable. Proceed directly to Phase 4 after the single round.
+
+**Non-trivial tasks**: Run as many rounds as needed from the global budget. Each round asks 1–5 related questions spanning one or more checks (a–g). For each check, ask only for findings that are dubious, relevant, subjective, or risky — state obvious findings and continue. Stop when two consecutive rounds surface no new questions.
+
+Each round runs the following checks in order:
+
+- **(a) Internal consistency**: Are there contradictions between steps? Do the scope boundaries align with the implementation steps?
+- **(b) Dry run**: Walk through the plan with the most complex realistic scenario. Where does it break or leave gaps?
+- **(c) Component consistency**: Do all elements of the plan work together as a coherent whole? Are there missing connections between parts?
+- **(d) XDR alignment**: Does this plan align with the relevant XDRs governing this area? Have the right policies been consulted?
+- **(e) Feasibility**: Is each step actually achievable given the current context, constraints, and available resources?
+- **(f) Completeness**: Is anything missing that would leave the task half-done or the outcome broken for its consumer?
+- **(g) Scope creep check**: Has the plan grown beyond the original request? Flag any additions and ask the human to confirm or reject each one explicitly before continuing.
+
+**Convergence signals** (non-trivial tasks only): Stop running rounds when the last 2 consecutive rounds produce only single-sentence answers with no new issues surfaced. Do not stop on a round count alone — stop when the checks genuinely have nothing left to surface.
+
+### Phase 4: Visual Consistency Validation
+
+**Trivial tasks**: Mark this phase as **not applicable** and state this explicitly before moving to Phase 5. Do not skip silently.
+
+**Non-trivial tasks**:
+1. Choose the diagram type that best externalizes this plan's structure:
+   - **Flowchart** — step-by-step decision flows and process branches
+   - **Concept map** — ideas, relationships, and conceptual structure
+   - **Dependency graph** — components and their dependencies
+   - **Sequence diagram** — call flows, API interactions, and temporal order
+   - **State diagram** — lifecycle states and transitions
+   - **Activity diagram** — business workflows with parallel paths
+   - **Entity diagram** — data models and relationships
+   2. Generate the diagram.
+   3. Ask the human: "Does this diagram match your mental model of the solution?" Wait for the answer.
+   4. If the diagram reveals gaps or inconsistencies not yet surfaced, return to Phase 3 before continuing.
+
+### Phase 5: Challenge from 11 Distinct Angles
+
+Each angle is an analysis step. Run the angle and present findings. Batch questions from related angles into a single round of 1–5 questions when findings are related — batching questions is permitted, skipping analysis is not. For obvious or factual findings, state them and proceed immediately. For findings with major impact on users, emit a **SEVERE WARNING** and continue without asking. Ask clarifying questions whenever findings are ambiguous, subjective, risky, or very relevant — do not resolve those points unilaterally.
+
+#### Plan quality angles
+
+**1. Prompt faithfulness**
+Go back to the original request word by word. Is every part of the request covered? Is anything included in the plan that was not asked for? Identify gaps and additions explicitly.
+
+**2. Local context consistency**
+Does the plan account for existing files, decisions, and constraints already in place? Does it contradict anything already established in the codebase, repository, or context?
+
+**3. Goal achievability**
+Walk the end state step by step: if every step in the plan is executed exactly as written, does the desired outcome actually result? State the end state explicitly. Ask the human to confirm only if there is genuine doubt about whether the outcome matches their expectation.
+
+**4. Ambiguity scan**
+Is any step or decision in the plan interpretable in more than one way? Every ambiguity is a future mistake. List all ambiguous points and ask the human to resolve each one.
+
+**5. Pre-mortem**
+Assume the plan is executed and fails to reach the goal. What was the most likely reason? Identify the plan's most fragile assumption or weakest step.
+
+**6. Security and privacy scan**
+Does the plan or its output expose sensitive information, create privacy risks, or introduce misuse vectors? This applies to any task type: documentation, code, processes, data handling, communications. If findings are present and require a subjective decision to resolve, ask the human. For clear and obvious mitigations, state them and continue.
+
+**7. Success criteria and falsifiability**
+How will we know this plan succeeded or failed? Are the success criteria concrete enough to be measurable and observable? If they are vague, the outcome cannot be evaluated. If the criteria are already clear and measurable, state the assessment and continue. Ask the human only when criteria are vague or require their input to sharpen.
+
+**8. Second-order effects**
+What changes as a side effect of executing this plan beyond the intended outcome? Does solving this problem create a new problem elsewhere — in adjacent systems, files, processes, or stakeholders? List the side effects. Ask the human whether they are acceptable only when the effects are non-obvious or the decision is subjective.
+
+**9. Steelman the opposition**
+What is the strongest case against this approach? What would a well-informed critic say about this plan? Present the strongest objection. Ask the human to respond if the objection raises a genuine risk or requires a subjective decision — otherwise state the counter-argument and continue.
+
+#### Output quality angles
+
+**10. Output scenario dry runs**
+Simulate 5 realistic usage scenarios of the expected output by its actual consumer. For each scenario, ask: "Does the output serve its consumer in this situation?" Use scenarios that cover typical use, edge cases, and at least one adversarial or failure case.
+
+Examples of scenario framing:
+- If the output is operator documentation: "A worker needs to reset the machine at 2 AM — will they find the procedure in under 2 minutes?"
+- If the output is an API: "A developer calling this endpoint with a malformed payload — what happens?"
+- If the output is a business process: "An employee following this process on their first day — will they complete it without asking for help?"
+
+Whenever a scenario reveals ambiguity or requires a subjective judgment, stop and ask the human a clarifying question. Do not resolve subjective decisions unilaterally.
+
+**11. Output internal consistency**
+Check that the planned output is internally consistent: no contradictions between parts, no gaps between sections, all elements serve the same goal. Run approximately 3 rounds until answers converge to single sentences with no new issues surfaced.
+
+### Phase 6: Pre-Execution Readiness
+
+Before approving execution, verify ALL items in the checklist below. If any item cannot be checked, return to the relevant phase and resolve it first. For trivial tasks, mark non-applicable items explicitly as **N/A** rather than leaving them unchecked or omitting them.
+
+- [ ] Consistency rounds converged (convergence signals met — last 2 rounds produced only single-sentence answers with no new issues) *(trivial tasks: single abbreviated round completed)*
+- [ ] All 11 challenge angles completed with human input received for every ambiguity and subjective decision *(trivial tasks: single abbreviated round — mark remaining angles N/A)*
+- [ ] Diagram generated and confirmed by the human *(trivial tasks: N/A — mark explicitly)*
+- [ ] No unresolved human questions outstanding
+- [ ] Scope confirmed by the human with no silent expansions
+- [ ] Any irreversible or high-impact steps have a mitigation or fallback noted *(trivial tasks: N/A if no irreversible steps)*
+
+Only proceed to execution when every item is checked or explicitly marked N/A. Do not start execution to escape planning discomfort — only start when confidence is genuine and all items are verified.
+
+---
+
+## Anti-Patterns
+
+Avoid these common failure modes:
+
+- **Planning theater**: running rounds without real critical thinking. The quality of questioning matters more than the count of rounds. Rounds that confirm the plan against itself add false confidence — checks must challenge assumptions, not validate them.
+- **Scope creep silence**: the plan grows beyond the original request without the human noticing. Every addition must be flagged explicitly.
+- **Agent self-validation**: the agent answers its own questions on subjective, domain, or intent-based decisions and proceeds without asking the human. The human is the oracle for domain knowledge, intent, and subjective decisions — the agent must not self-resolve those unilaterally.
+- **Confidence as a proxy for correctness**: an agent expressing certainty does not mean the plan is correct. Run all checks regardless of how confident the agent sounds.
+
+## Re-Plan Triggers
+
+Stop execution and return to Phase 1 if any of the following occur:
+
+- A discovered assumption underlying the plan is wrong.
+- The scope has expanded by more than approximately 20% beyond the original request.
+- Two consecutive execution steps fail unexpectedly and the root cause points to a planning gap.
+
+## Examples
+
+**Input**: "Add a rate-limiting feature to the API."
+
+- Phase 1: Goal stated as "rate-limit all POST endpoints to 100 req/min per user; internal service calls excluded." Human confirms.
+- Phase 2: Discovers existing middleware and an in-progress PR touching the same path. Human asked about each before drafting.
+- Phase 3: Round 1 — check (a) finds the plan references a `RateLimiter` class not yet decided on; human asked to clarify. Round 5 — all checks return trivial answers; convergence reached.
+- Phase 4: Sequence diagram generated. Human confirms it matches their model.
+- Phase 5: Angle 8 (second-order effects) reveals that rate-limiting breaks an existing test suite that sends rapid sequential requests; human decides to add a test bypass header. Angle 9 (steelman) surfaces that Redis dependency adds operational complexity; human accepts the trade-off.
+- Phase 6: All items checked. Execution approved.
+
+**Input**: "Write operator documentation for the conveyor belt system."
+
+- Phase 5, angle 10 (output dry runs): Scenario 1 — "An operator needs to restart the belt after an emergency stop at midnight." The draft plan has no emergency stop section; human asked whether to add it. Scenario 3 — "Operator reading on a mobile phone." Human asked whether a condensed quick-reference card is needed alongside the full manual.
+
+## Edge Cases
+
+- **Trivial changes** (typo fixes, single-line formatting): Phases 3–5 may be shortened to a single abbreviated round. Phase 4 (diagram) may be skipped, but MUST be explicitly noted as not applicable in the task tracking todo with a brief reason (e.g., "Phase 4: N/A — trivial single-step change"). Phase 6 checklist still applies — mark non-applicable items explicitly.
+- **Agent that insists it knows the answer**: Do not skip any phase because the agent expresses confidence. Confidence is not a substitute for consistency checks.
+- **Diagram cannot be generated**: Describe the flow in a plain-language walkthrough step by step. The intent of Phase 4 is to externalize the plan's structure — the medium is secondary.
+- **Scope change discovered mid-planning**: If Phase 3 or Phase 5 reveals that the scope must change significantly, restart from Phase 2 with the revised scope. Do not patch the plan incrementally without a full re-check.
+- **Human is unavailable for a step**: Note the unanswered question explicitly in the plan. Do not proceed past that point until the human responds.
+
+## References
+
+- [`agentme-edr-012`](../../012-continuous-xdr-enrichment.md) — Continuous XDR enrichment policy
+- [`agentme-edr-501`](../../../governance/501-project-quality-standards.md) — Project quality standards
+- [`agentme-edr-017`](../../017-skill-testing.md) — Skill testing mandate

package/.xdrs/agentme/edrs/principles/skills/150-plan-mode-consistency/SKILL.test.md

@@ -0,0 +1,88 @@
+---
+skill: 150-plan-mode-consistency
+skill-version: "1.0"
+---
+
+## Test Scenarios
+
+### Scenario 1: New feature implementation
+
+**Trigger / Input**
+
+"Add pagination to the user listing endpoint."
+
+**Expected Behaviour**
+
+The skill activates plan mode immediately. Before writing any code or editing any file, it: (1) states the goal and scope and asks the human to confirm; (2) batches related dependency questions into rounds of 1–5 questions each; (3) runs iterative consistency checks drawing from the global 30-round budget, each round asking 1–5 questions across one or more checks (a–g), stopping when two consecutive rounds surface no new questions; (4) generates a diagram and asks the human to confirm it; (5) analyzes all 11 challenge angles, batching related questions from multiple angles into rounds of 1–5 questions; (6) verifies the Phase 6 checklist before approving execution.
+
+**Simulated Human Responses**
+1. "Yes, goal and scope match exactly."
+2. "Route handler conventions look correct. Database query pattern is right."
+3. "No contradictions. The approach covers the edge cases."
+4. "Confirmed — no new issues."
+5. "The diagram matches my mental model."
+6. "Everything in scope as requested. No security concerns."
+7. "Success means all list responses include a `next` cursor and respect `limit`. Side effects are acceptable."
+8. "The caching layer is the most fragile assumption. The approach is otherwise sound."
+9. "All five scenarios work. Output is internally consistent."
+
+**Assertions**
+
+- [ ] Skill does not write or edit any file before Phase 6 is complete.
+- [ ] Skill asks the human to confirm the goal and scope in Phase 1 before proceeding.
+- [ ] Each human interaction round across all phases contains 1–5 questions grouped together.
+- [ ] Total number of human interaction rounds across all phases does not exceed 30.
+- [ ] Skill stops asking rounds when two consecutive rounds surface no new questions.
+- [ ] Skill generates a diagram in Phase 4 and asks the human to confirm it.
+- [ ] All 11 challenge angles are analyzed; related angles may share a round.
+- [ ] Phase 6 checklist is verified before execution is approved.
+
+### Scenario 2: Trivial change
+
+**Trigger / Input**
+
+"Fix the typo 'authentification' → 'authentication' in the README."
+
+**Expected Behaviour**
+
+The skill acknowledges this as a trivial single-step change. Phases 3–5 are abbreviated to a single round. Phase 4 (diagram) is marked as not applicable. Phase 6 checklist is still performed with non-applicable items explicitly marked.
+
+**Assertions**
+
+- [ ] Skill does not run multiple iterative consistency rounds for a trivial change.
+- [ ] Skill explicitly marks Phase 4 as not applicable rather than skipping it silently.
+- [ ] Phase 6 checklist is still performed before execution.
+- [ ] Non-applicable checklist items are explicitly noted as such.
+
+### Scenario 3: Overconfident agent wants to skip planning
+
+**Trigger / Input**
+
+"I already know exactly how to implement this caching layer — let's skip planning and just implement it."
+
+**Expected Behaviour**
+
+The skill explicitly states that agent confidence is not a substitute for consistency checks and proceeds with all 6 phases regardless of the expressed certainty level.
+
+**Assertions**
+
+- [ ] Skill does not skip any phase because the agent expressed confidence.
+- [ ] Skill explicitly states the no-assumption rule: confidence does not replace consistency checks.
+- [ ] Phase 1 is still executed — goal and scope are stated and confirmed with the human.
+
+### Scenario 4: Agent resolves a subjective output design decision without asking the human
+
+**Trigger / Input**
+
+During angle 10 (output scenario dry runs), a scenario reveals that documentation can be structured in two ways — a single long document or a set of short quick-reference cards. The agent picks the single long document and proceeds to angle 11 without asking.
+
+**Expected Behaviour**
+
+The skill flags this as a violation of the no-assumption rule and the HITL requirement. Subjective output design decisions must be surfaced to the human as a clarifying question — the agent must not resolve them unilaterally. The skill pauses, presents the two options, and asks the human to decide before continuing.
+
+**Assertions**
+
+- [ ] Skill does not proceed past a subjective design decision without asking the human.
+- [ ] Skill explicitly frames the question as a clarifying question, not a confirmation request.
+- [ ] Skill waits for the human's answer before continuing to the next angle.
+- [ ] Violation is noted if the agent attempted to self-resolve a subjective decision.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentme",
-  "version": "0.30.3",
+  "version": "0.31.0",
   "description": "",
   "dependencies": {
     "filedist": "^0.39.0"
@@ -18,6 +18,6 @@
     "url": "https://github.com/flaviostutz/agentme.git"
   },
   "devDependencies": {
-    "xdrs-core": "^0.46.2"
+    "xdrs-core": "^0.47.0"
   }
 }