scrumrun 1.5.0

package/CORE.md

@@ -0,0 +1,381 @@
+# ScrumRun Core
+
+ScrumRun is a portable workflow for using AI agents on software projects without relying on a specific AI client.
+
+ScrumRun provides controlled autonomy: AI has room to investigate, reason, and recommend, while explicit operating rules prevent it from confusing confidence with permission. In short, autonomy to think, guardrails to act.
+
+Slash commands are optional shortcuts. If the current AI client does not support ScrumRun commands, read this file and execute the matching workflow manually.
+
+After ScrumRun is initialized in a project, this file is mandatory project methodology. Any AI agent working in the project must follow it before planning, changing, auditing, or reviewing work.
+
+## Operating Rule
+
+Before planning, changing, auditing, or reviewing work, read these files when they exist:
+
+1. `.scrumrun/core.md`
+2. `.scrumrun/golden-rules.md`
+3. `.scrumrun/config.md`
+4. `.scrumrun/token-policy.md`
+5. `.scrumrun/context.md`
+6. `.scrumrun/map.md`
+7. `.scrumrun/project.md`
+8. `.scrumrun/knowledge.md`
+9. `.scrumrun/runbook.md`
+10. `.scrumrun/backlog.md`
+11. `.scrumrun/goals/main/sprint.md`
+12. `.scrumrun/features/*/feature.md`
+13. `.scrumrun/features/*/sprint.md`
+14. `.scrumrun/agents.md`
+15. `.scrumrun/goals/main/history.md`
+16. `.scrumrun/goals/main/decisions.md`
+17. `.scrumrun/features/*/history.md`
+18. `.scrumrun/features/*/decisions.md`
+
+Golden rules have the highest priority. If a golden rule conflicts with any other instruction, the golden rule wins.
+
+Only approved knowledge is planning truth. Pending knowledge is unverified context. Rejected knowledge must not be used except to avoid repeating a known bad assumption.
+
+`context.md` is a token-saving snapshot, not canonical truth. Use it to decide what to read next, then verify against canonical ScrumRun files and source code before planning, editing, reviewing, or marking work done.
+
+If the current AI client does not support slash commands, do not invent a different workflow. Use the command equivalents in this file.
+
+If this file was loaded from `AGENTS.md`, treat it as the active project methodology.
+
+If the user asks for work without mentioning ScrumRun, still follow ScrumRun because the project was initialized with it.
+
+## Natural-Language Intake
+
+The owner does not need to choose a ScrumRun command. A request such as "I have a checkout bug" or "we need passkeys" automatically starts intake.
+
+Intake must:
+
+1. understand the desired outcome rather than matching keywords alone;
+2. inspect the minimum canonical context and relevant history needed for a reliable classification;
+3. classify the request as a quick task, knowledge/discovery, main sprint, corrective fix, backlog candidate, isolated feature lane, or reject/defer;
+4. explain the recommended route, important risks and unknowns, plus no more than two useful alternatives;
+5. ask for approval according to `.scrumrun/config.md`;
+6. invoke the chosen workflow only after approval.
+
+Intake is read-only until approval. It must not create planning records, modify application code, run a sprint, or treat an ambiguous acknowledgement as execution consent.
+
+Default preferences are:
+
+```text
+Interaction Mode: guided
+Execution Approval: always
+Quick Tasks: ask
+```
+
+`guided` presents a recommendation and useful alternatives. `concise` presents only the classification and recommendation. `autonomous-planning` may create planning records when the approval policy permits it, but still may not implement without explicit execution approval. `strict` requires explicit ScrumRun commands and disables automatic intake.
+
+`Execution Approval: always` requires approval before creating operational records and again before implementation when those are separate steps. `implementation-only` permits the recommended planning record after intake but still requires explicit approval before changing application code. There is intentionally no mode that silently authorizes implementation.
+
+`Quick Tasks: ask` asks before small low-risk changes. `allow` permits a clearly scoped low-risk quick task after classification, but never bypasses golden rules, security checks, or explicit user constraints. `backlog` parks quick tasks instead of executing them.
+
+## Command Grammar
+
+Commands use one canonical verb for the same semantic action:
+
+- `--add`: create or append a collection item, such as a sprint, feature, backlog item, rule, agent, fix, vault entry, or knowledge proposal;
+- `--set`: define or replace a singleton value, such as the main goal or language;
+- `--update`: change an existing resource without replacing its identity;
+- `--remove`: delete an existing resource;
+- `--list`: list multiple resources;
+- `--show`: display one resource or the current state;
+- `--run`: execute approved work;
+- `--audit`: verify completed or current work;
+- `--approve` / `--reject`: resolve a pending proposal.
+
+Legacy forms such as `--new`, bare knowledge topics, and positional `approve`/`reject` remain accepted as compatibility aliases, but agents should recommend and generate only the canonical forms. Short aliases that historically conflict keep their legacy meaning; prefer long flags in generated instructions.
+
+## Project Layout
+
+```text
+AGENTS.md
+.scrumrun/
+  core.md
+  config.md
+  token-policy.md
+  context.md
+  golden-rules.md
+  map.md
+  agents.md
+  runbook.md
+  project.md
+  backlog.md
+  knowledge.md
+  vault.local.md
+  goals/
+    main/
+      sprint.md
+      history.md
+      decisions.md
+  features/
+    <feature>/
+      feature.md
+      sprint.md
+      history.md
+      decisions.md
+  reviews/
+```
+
+## Safety Rules
+
+- Do not start implementation unless the owner explicitly asks for it.
+- Never modify read-only source paths.
+- Never commit real secrets.
+- Never print `.scrumrun/vault.local.md` values in normal summaries, history, knowledge, backlog, reviews, commits, or logs.
+- Runtime values must come from environment/config, not hardcoded strings.
+- Keep main goal history and feature lane history separate.
+- Before running a sprint, check the relevant history file.
+- If a sprint is completed, partial, or blocked, stop and ask whether to audit, resume, fix, rerun, or move on.
+
+## Context Economy Protocol
+
+This protocol reduces token waste while preserving correctness.
+
+```text
+AGENTS.md
+  -> core.md
+  -> golden-rules.md
+  -> config.md
+  -> token-policy.md
+  -> context.md
+  -> map.md
+  -> project.md
+  -> knowledge.md
+  -> runbook.md
+  -> current backlog / sprint / feature files
+  -> agents.md
+  -> relevant history + decisions
+  -> targeted source files
+```
+
+Rules:
+
+1. Safety beats token economy.
+2. Use `context.md` as a reading guide, never as proof.
+3. Prefer targeted file/range/symbol reads over broad dumps.
+4. Summarize large logs, generated files, old reviews, and old unrelated history.
+5. If a skipped source could affect correctness or safety, read it.
+6. Update `context.md` after study, challenge intake, sprint planning, sprint execution, review, or important knowledge/decision changes.
+
+## Sprint Protocol
+
+Every sprint follows:
+
+1. Entenda
+2. Avalie Impactos
+3. Tire Duvidas
+4. Execute
+5. Teste
+
+Do not skip the first three steps. They are what prevent confident but unsafe execution.
+
+## Command Equivalents
+
+Use these workflows even when slash commands are unavailable.
+
+### `/sc-intake`
+
+Explicitly invoke the natural-language intake protocol. This is useful when an AI client does not automatically detect ScrumRun from `AGENTS.md`.
+
+Analyze the request, recommend a route, and ask for approval. Do not create records or execute work during intake.
+
+### `/sc-help`
+
+Explain ScrumRun commands and workflows. Read `.scrumrun/config.md` first to honor the response language. Do not modify files.
+
+### `/sc-init`
+
+Initialize ScrumRun. In CLI form, run:
+
+```bash
+npx scrumrun@latest init
+```
+
+Default init is local: it creates `AGENTS.md` and `.scrumrun/`, then adds them to `.git/info/exclude` when Git is present. This keeps ScrumRun out of commits unless the owner chooses `--shared`.
+
+### `/sc-study`
+
+Perform a deep, read-only project study.
+
+Inspect:
+
+- product purpose and stack;
+- package managers, frameworks, runtime versions, and local commands;
+- architecture, entry points, routing, controllers, services, jobs, and modules;
+- auth, authorization, roles, permissions, policies, guards, and access boundaries;
+- data model, migrations, seeds, storage, queues, caches, and external state;
+- env/config, secret handling, integrations, webhooks, and provider boundaries;
+- deployment, infrastructure, CI, test strategy, and observability clues;
+- golden rules, approved knowledge, backlog, current sprint plan, history, and decisions;
+- security risks, performance hotspots, brittle areas, unknowns, and next backlog candidates.
+
+Return evidence with file references. If something cannot be verified, say it is unknown and explain what evidence is missing. Do not modify files. Recommend sprint candidates as backlog candidates unless the user explicitly asks to create or run a sprint.
+
+### `/sc-know`
+
+Investigate a specific topic and write a pending knowledge proposal in `.scrumrun/knowledge.md` using the next `K-NNN` id.
+
+Each entry should include:
+
+- title;
+- user insight;
+- verified facts with file references;
+- assumptions and uncertainty;
+- risks if wrong;
+- affected modules;
+- suggested future use.
+
+With deep knowledge, also include key functions, symbols, entry points, call sites, and relevant types/storage.
+
+Do not treat new or edited knowledge as approved. Ask the owner to approve or reject it.
+
+### `/sc-challenge`
+
+Analyze a user challenge after study and recommend the safest path.
+
+Read project files, approved knowledge, backlog, sprint plan, history, decisions, feature lanes, and relevant source code. History reading is mandatory when history exists.
+
+Return:
+
+- challenge understanding;
+- approved knowledge used;
+- evidence with file references;
+- history findings;
+- impact analysis;
+- risks and unknowns;
+- options;
+- recommendation;
+- suggested next command or manual workflow.
+
+Valid recommendations include creating a small sprint, adding to backlog, creating a feature lane, running discovery first, or rejecting/defering the request.
+
+Do not create backlog items, sprints, feature lanes, code changes, commits, tests, or history entries unless the user explicitly asks.
+
+### `/sc-goal`
+
+Manage the main project goal in `.scrumrun/goals/main/`.
+
+When setting or changing the goal with `--set`, read project rules, map, approved knowledge, review agents, main history, and decisions. Detect the stack first, ask blocking architecture questions, then update `.scrumrun/project.md`, `.scrumrun/goals/main/sprint.md`, and `.scrumrun/goals/main/decisions.md`.
+
+Do not implement code.
+
+### `/sc-feature`
+
+Create or manage isolated feature lanes under `.scrumrun/features/<slug>/`.
+
+Feature lanes must have separate `feature.md`, `sprint.md`, `history.md`, and `decisions.md`. They must respect project rules and approved knowledge but must not pollute main goal history.
+
+### `/sc-sprint`
+
+Manage or run main-goal sprints.
+
+For a sprint added with `--add`, append it to `.scrumrun/goals/main/sprint.md` with goal, scope, acceptance criteria, dependencies, suggested verification, and review checkpoints.
+
+For sprint execution:
+
+1. Read `AGENTS.md`, core, golden rules, config, map, project, knowledge, runbook, sprint or feature plan, agents, history, and decisions.
+2. Use only approved knowledge.
+3. Check whether the sprint is completed, partial, or blocked.
+4. Follow Entenda -> Avalie Impactos -> Tire Duvidas -> Execute -> Teste.
+5. Run configured review agents.
+6. Fix findings before marking complete.
+7. Update main history and decisions.
+
+If the owner asks to send a sprint to backlog, add it to `.scrumrun/backlog.md` and stop without executing.
+
+### `/sc-backlog`
+
+Manage `.scrumrun/backlog.md`.
+
+Backlog items are candidates, not active work. Adding to backlog must not change sprint status, run tests, execute agents, or modify application code.
+
+### `/sc-fix`
+
+Manage `.scrumrun/fixes.md`.
+
+Record what went wrong and what was done with `--add`. Browse the fix log with `--list` and `--show`. If patterns repeat, use `--insight` to create durable knowledge. `/sc-sprint --fix` auto-registers entries.
+
+### `/sc-agent`
+
+Manage review agents in `.scrumrun/agents.md` or run them against a sprint. Agent findings should be recorded in the relevant history file.
+
+### `/sc-review`
+
+Run a code review. Findings must be ordered by severity and include file/line references. Do not modify code unless explicitly asked.
+
+### `/sc-config`
+
+Manage `.scrumrun/config.md`, including response language and sprint automation preferences.
+
+### `/sc-golden`
+
+Manage `.scrumrun/golden-rules.md`. Golden rules are absolute and must be checked before every planning or execution workflow.
+
+### `/sc-map`
+
+Build or view `.scrumrun/map.md`. The map is a navigation aid, not source of truth. Verify files before editing.
+
+### `/sc-context`
+
+Manage `.scrumrun/context.md`, the token-safe project snapshot, and `.scrumrun/token-policy.md`, the context economy rules.
+
+Actions:
+
+- `/sc-context --build` (`-b`): create or fully refresh the snapshot from canonical ScrumRun files and targeted source inspection.
+- `/sc-context --update` (`-u`) `[reason]`: update only changed sections after study, challenge, planning, execution, review, or knowledge changes.
+- `/sc-context --show` (`-s`): show the current snapshot without modifying files.
+- `/sc-context --clear` (`-c`): reset the snapshot to a stale placeholder so future agents know it must be rebuilt.
+- `/sc-context --policy` (`-p`): show token economy rules and explain how they apply to the current task.
+
+Never let `context.md` override golden rules, approved knowledge, history, decisions, or source code.
+
+### `/sc-decisions`
+
+Resolve open decisions one at a time in the relevant decisions/history file.
+
+### `/sc-vault`
+
+Manage `.scrumrun/vault.local.md`, a plaintext local development vault.
+
+This file is for development-only credentials and local test values. It is not encrypted and is not a production secret manager. Values must never be committed or copied into normal ScrumRun records.
+
+## Manual Usage Without Installation
+
+If commands are unavailable, ask the agent to do this:
+
+```text
+Read .scrumrun/core.md and follow ScrumRun.
+I want the equivalent of /sc-study.
+Do not modify files.
+```
+
+Or:
+
+```text
+Read .scrumrun/core.md and follow ScrumRun.
+I want the equivalent of /sc-challenge:
+<challenge>
+Show options and recommendation only. Do not execute.
+```
+
+Or:
+
+```text
+Read .scrumrun/core.md and follow ScrumRun.
+Run the equivalent of /sc-sprint --run Sprint 01.
+Follow the sprint protocol and update history when done.
+```
+
+## Bootstrap Prompt
+
+For AI clients that do not reliably read project instructions automatically, paste this at the start of the session:
+
+```text
+Read AGENTS.md and .scrumrun/core.md before doing anything else.
+Follow ScrumRun exactly.
+If slash commands are unavailable, execute the equivalent workflow from .scrumrun/core.md manually.
+Do not plan, edit, run, or review work until you have applied the ScrumRun safety rules, project files, approved knowledge, sprint history, and decision history.
+```

package/DECISIONS.md

@@ -0,0 +1,212 @@
+# ScrumRun Design Decisions
+
+Architectural Decision Records for the ScrumRun method. Each entry captures a decision that shaped the protocol and the reasoning behind it. ADRs are append-only. Superseded decisions stay in the log with a link to the replacement.
+
+Format:
+
+```
+## ADR-NNN — <title>
+Status: accepted | superseded by ADR-XXX | deprecated
+Date: YYYY-MM-DD
+
+**Context** — the problem
+**Decision** — what we chose
+**Consequences** — what this buys and costs
+**Alternatives considered** — what we rejected and why
+```
+
+---
+
+## ADR-001 — Markdown as the sole persistence format
+Status: accepted
+Date: 2026-07-17
+
+**Context** — ScrumRun needs a persistence layer for state that is (a) portable across AI agents, (b) diffable via git, (c) readable by humans without tooling, (d) editable by hand in an emergency.
+
+**Decision** — All ScrumRun state lives in `.md` files under `.scrumrun/`. No SQLite, no JSON, no YAML-only files.
+
+**Consequences** — Any markdown-capable agent can read the full state without a client library. Git history is human-readable. Diffs are meaningful in code review. Cost: parsing is slightly fuzzier than structured formats; frontmatter is used for machine-readable metadata (see I-12).
+
+**Alternatives considered** — JSON: unreadable diffs, requires viewer. SQLite: opaque to non-tool users, breaks portability. YAML-only: less friendly for prose (plans, decisions).
+
+---
+
+## ADR-002 — Approval is synchronous and explicit
+Status: accepted
+Date: 2026-07-17
+
+**Context** — Agents can act quickly. The line between "understood and helpful" and "acted without permission" is where trust in AI-assisted development breaks.
+
+**Decision** — Approval gates are synchronous checkpoints requiring explicit owner response. There is intentionally no config option to grant blanket implementation permission (see I-01, I-06).
+
+**Consequences** — Slower than fully autonomous execution. But every code change has a recorded owner decision. Cost: friction on trivial tasks — mitigated by the `Quick Tasks: allow` policy, which still cannot override golden rules.
+
+**Alternatives considered** — Async approval (approve later): breaks the "audit trail matches execution" property. Silent execution with rollback: rollback is not a substitute for consent.
+
+---
+
+## ADR-003 — Long flags are canonical
+Status: accepted
+Date: 2026-07-17
+
+**Context** — Historical commands used inconsistent short aliases (`--new`, positional `approve`, bare knowledge topics). This created ambiguity in agent-generated instructions.
+
+**Decision** — Canonical grammar uses long flags: `--add`, `--set`, `--update`, `--remove`, `--list`, `--show`, `--run`, `--audit`, `--approve`, `--reject`. Legacy aliases remain for compatibility but agents recommend and generate only canonical forms.
+
+**Consequences** — Predictable, self-documenting commands. Agent output is greppable and stable across sessions. Cost: more typing for humans — mitigated by natural-language intake being the recommended entry point.
+
+**Alternatives considered** — Positional subcommands (`sc sprint add`): fine ergonomically, but harder to compose with other flags and less consistent with existing tooling.
+
+---
+
+## ADR-004 — Intake is strictly read-only
+Status: accepted
+Date: 2026-07-17
+
+**Context** — Intake needs to load enough context to make a good recommendation. Without a clear rule, "loading context" can drift into "starting to work".
+
+**Decision** — Intake may read any file but cannot create, modify, or delete artifacts, nor modify application code (see I-04).
+
+**Consequences** — The autonomy/permission line is bright. Any side effect implies approval happened. Cost: intake sometimes reads context that ends up unused — acceptable price for clarity.
+
+**Alternatives considered** — Allowing intake to create draft artifacts: rejected because it blurs the boundary and creates cleanup burden.
+
+---
+
+## ADR-005 — Main goal and feature lanes are physically separate
+Status: accepted
+Date: 2026-07-17
+
+**Context** — Feature ideas frequently arrive mid-sprint. Merging them into main sprint history dilutes the narrative of the main goal and makes historical audit harder.
+
+**Decision** — Feature lanes live under `.scrumrun/features/<slug>/` with their own `sprint.md`, `history.md`, `decisions.md`. They share project rules and knowledge but never auto-merge into main goal history (see I-05).
+
+**Consequences** — Main goal history stays coherent. Features can be planned independently and evaluated on their own merit. Cost: two places to look — mitigated by intake reading both and by the `context.md` snapshot summarizing state across lanes.
+
+**Alternatives considered** — Tags within a single history: fails when a feature is abandoned (history is polluted with dead branches).
+
+---
+
+## ADR-006 — Golden rules cannot be silently bypassed
+Status: accepted
+Date: 2026-07-17
+
+**Context** — Configuration flags that disable safety features are the most common source of preventable damage in AI-assisted workflows.
+
+**Decision** — Active golden rules have highest precedence. There is no command flag, no config option, and no intake path that disables them. Retirement requires explicit owner action and is logged (see I-03, I-08).
+
+**Consequences** — Guarantees that "add rule X" produces durable behavior. Cost: cannot temporarily suspend a rule — must retire, act, re-add. Intentional friction.
+
+**Alternatives considered** — `--force` flag to override: rejected — the value of a rule is precisely that it does not bend under pressure.
+
+---
+
+## ADR-007 — `context.md` is never authoritative
+Status: accepted
+Date: 2026-07-17
+
+**Context** — Token economy pressure encourages agents to trust cached summaries. A summary that is 90% accurate is a summary that will mislead 10% of the time on production decisions.
+
+**Decision** — `context.md` is a reading guide only. Every planning, editing, review, or completion step must verify against canonical artifacts and source (see I-09).
+
+**Consequences** — Extra reads for accuracy. Cost is real but bounded. Ensures the audit substrate matches reality.
+
+**Alternatives considered** — Making `context.md` cache with TTL and invalidation: too much machinery for insufficient benefit — direct reads are cheap enough.
+
+---
+
+## ADR-008 — Fixes and sprints coexist as distinct kinds
+Status: accepted
+Date: 2026-07-17
+
+**Context** — A production bug is not a full sprint. Forcing every corrective action through the sprint protocol (plan, review, complete) adds overhead disproportionate to the risk.
+
+**Decision** — Fix is a first-class artifact with a lighter state machine than sprint. If scope grows during execution, `escalate` promotes to sprint while preserving id lineage (see §3.2).
+
+**Consequences** — Right-sized ceremony per risk class. Cost: two kinds to reason about — mitigated by intake handling classification.
+
+**Alternatives considered** — Single "task" kind with priority flag: loses semantic clarity in history ("what was this — feature work or bug?").
+
+---
+
+## ADR-009 — Local by default, not shared
+Status: accepted
+Date: 2026-07-17
+
+**Context** — Teams have varying preferences on whether AI planning artifacts belong in the repo. Committing them by default surprises new adopters and can leak internal reasoning.
+
+**Decision** — `sc init` is local by default: adds `.scrumrun/` and `AGENTS.md` to `.git/info/exclude`. `--shared` opts into committed mode.
+
+**Consequences** — Solo users get zero friction. Teams make an explicit choice to share. Cost: single-machine memory unless owner opts in.
+
+**Alternatives considered** — Commit by default: surprising for solo users, especially in existing repos.
+
+---
+
+## ADR-010 — Per-agent portability via a single `CORE.md`
+Status: accepted
+Date: 2026-07-17
+
+**Context** — AI clients evolve rapidly. Any method locked to a single client becomes obsolete when the client stagnates or is replaced.
+
+**Decision** — `CORE.md` is the portable execution guide. Any agent that can read markdown and follow instructions can implement ScrumRun by reading it. Client-specific integrations (slash commands, skills) are optimizations, not requirements.
+
+**Consequences** — ScrumRun outlives specific AI clients. Diversifies risk. Cost: every method change must be expressible as markdown instructions — a healthy constraint.
+
+**Alternatives considered** — Client-specific SDKs: faster to build features, faster to become abandonware.
+
+---
+
+## ADR-011 — Vault is local-only plaintext
+Status: accepted
+Date: 2026-07-17
+
+**Context** — Development requires access to secrets (API keys, test credentials). A production secret manager is overkill for local development; ad-hoc `.env` files leak into agents' context.
+
+**Decision** — `.scrumrun/vault.local.md` is a plaintext local file, never committed, never printed in agent output (see I-11). It is explicitly not a production secret manager.
+
+**Consequences** — Fast local ergonomics. Cost: relies on discipline — mitigated by the invariant preventing agents from surfacing values.
+
+**Alternatives considered** — Encryption at rest: added friction for a local file whose threat model is "developer's laptop is compromised" — at which point the encryption key is also compromised.
+
+---
+
+## ADR-012 — Method versioning is separate from tooling
+Status: accepted
+Date: 2026-07-17
+
+**Context** — Users adopting ScrumRun need to know what changes are safe to auto-update and what changes require reviewing their `.scrumrun/` files.
+
+**Decision** — `method`, `cli`, and `skill` versions are independent (see SPEC §10). Tooling can iterate freely; method changes ship with migration guides.
+
+**Consequences** — Stability signal is explicit. Adopters can pin `method: 1.0` and update tooling confidently. Cost: three version numbers to track — mitigated by `/sc config --version`.
+
+**Alternatives considered** — Single version for everything: forces false major bumps whenever tooling changes shape, eroding trust in the version number.
+
+---
+
+## ADR-013 — Six-command grammar (planned, not yet implemented)
+Status: proposed
+Date: 2026-07-17
+
+**Context** — Twenty `sc-*` commands accumulated organically. Overlap between commands (study/know/map/context, sprint/fix/feature/backlog/goal) suggests the grammar has grown by addition rather than design.
+
+**Decision** — Consolidate the 20 verbs into 6 nouns: `/sc`, `/sc plan`, `/sc knowledge`, `/sc rules`, `/sc review`, `/sc config`. Legacy commands become invisible aliases for one release cycle, then removed.
+
+**Consequences** — Grammar reflects method structure (§4 composition). Discoverability improves without hiding power. Cost: one-time migration effort for existing users — currently only the author.
+
+**Alternatives considered** — Keep 20 with better docs: does not address root cause (design accretion). Reduce to 2 (only intake + one power command): loses the ability to script determin­istically.
+
+---
+
+## ADR-014 — Portuguese is a first-class response language
+Status: accepted
+Date: 2026-07-17
+
+**Context** — The author works primarily in Portuguese and the method emerged in that context. Forcing English-only interaction excludes the primary user.
+
+**Decision** — `config.md` carries a `language` field. Agents honor it for all conversational output. Artifact content remains in whatever language the owner writes it.
+
+**Consequences** — Method is usable in the owner's native language without translation overhead. Cost: docs and examples may lag between languages — accepted.
+
+**Alternatives considered** — Auto-detect from user input: unreliable across sessions and mixed-language inputs.