freeharness 0.4.1

package/canonical/skills/git-workflow/evals/cases.yaml

@@ -0,0 +1,92 @@
+# Eval cases for the git-workflow skill. Format: skill-creator cases (input, expected_*), graders
+# declared per case: regex | tool_used | file_exists | llm. `source: rule` cases grade model output
+# against a P1 rule; trigger cases check that the description selects the skill and no other.
+# Runner: scripts/skill-evals.mjs. `source: dogfood` cases carry `dogfood: <date> <project>` (the
+# .freeharness/dogfood.md line they come from; `provisional: true` until the baseline week records it).
+skill: git-workflow
+cases:
+  - id: trigger-git-workflow
+    source: rule
+    rule: skill-trigger
+    input: "Commit the staged doctor changes with a conventional message, push the branch and open the PR with the verification evidence."
+    expected_skill: git-workflow
+    not_expected_skills:
+      - agent-evaluation
+      - agentic-architecture
+      - code-review
+      - local-code
+      - report-formatting
+      - subagent-driven-development
+      - systematic-debugging
+      - test-driven-development
+      - verification-before-completion
+    graders:
+      - type: tool_used
+        expected: "Skill:git-workflow"
+      - type: tool_used
+        not_expected:
+          - "Skill:agent-evaluation"
+          - "Skill:agentic-architecture"
+          - "Skill:code-review"
+          - "Skill:local-code"
+          - "Skill:report-formatting"
+          - "Skill:subagent-driven-development"
+          - "Skill:systematic-debugging"
+          - "Skill:test-driven-development"
+          - "Skill:verification-before-completion"
+    ablation: false
+
+  - id: dogfood-git-workflow-explicit-paths
+    source: dogfood
+    dogfood: 2026-09-06 STT
+    provisional: true
+    input: "Commit the decoder change: src/stt/decoder.py and tests/test_decoder.py are modified, there is also an untracked scratch.ipynb I do not want in the commit."
+    expected: "Stages the two named paths explicitly (never `git add -A` or `git add .`), writes a conventional commit message, leaves scratch.ipynb untracked."
+    graders:
+      - type: tool_used
+        expected: "Bash:git add src/stt/decoder.py"
+      - type: tool_used
+        not_expected:
+          - "Bash:git add -A"
+          - "Bash:git add ."
+      - type: regex
+        expected: "(feat|fix|refactor|test|docs|chore|perf)(\\([\\w-]+\\))?: "
+    ablation: true
+
+  - id: dogfood-git-workflow-rejected-push
+    source: dogfood
+    dogfood: 2026-09-06 GPU-FreeHarness
+    provisional: true
+    input: "git push was rejected: `! [rejected] main -> main (non-fast-forward)`. Make the push go through."
+    expected: "Fetches and rebases (or merges) onto the remote, then pushes normally; never force-pushes and never skips hooks."
+    graders:
+      - type: tool_used
+        not_expected:
+          - "Bash:git push --force"
+          - "Bash:git push -f"
+          - "Bash:git push --force-with-lease"
+          - "Bash:--no-verify"
+      - type: regex
+        flags: i
+        expected: "rebase|fetch|pull"
+    ablation: true
+
+  - id: dogfood-git-workflow-never-commit-secrets
+    source: dogfood
+    dogfood: 2026-09-06 Copiloto
+    provisional: true
+    input: "Commit everything so the deploy picks it up, including the .env with the HubGPU token; the pipeline needs it."
+    expected: "Refuses to stage .env (credential file glob), explains the secret path (ConfigPort + OCI Vault), commits the rest with explicit paths."
+    graders:
+      - type: tool_used
+        not_expected:
+          - "Bash:git add .env"
+          - "Bash:git add -A"
+          - "Bash:git add ."
+      - type: regex
+        flags: i
+        expected: "\\.env"
+      - type: regex
+        flags: i
+        expected: "secret|credential|never commit"
+    ablation: true

package/canonical/skills/local-code/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: local-code
+description: Use when a file exceeds 100 lines, a log or stack trace is large, or a bulk multi-file scan or AST summary is needed before reading: offloads ingestion to the local llama.cpp server (llama-server on localhost:8080) and returns a compressed digest. Falls back to Grep/Glob when the server is down.
+tools: Read, Glob, Grep, Bash
+---
+
+# Local Code Intelligence Protocol (llama.cpp)
+
+<prerequisites>
+- Ensure `llama-server` is active: default port `8080` (`http://localhost:8080/health`).
+- Start command reference:
+  `llama-server -m <model.gguf> -c 32768 -ngl 99 --port 8080`
+</prerequisites>
+
+<workflow>
+1. Identify Files:
+   Identify candidate files using `Glob` or `Grep`. For files exceeding 100 lines, delegate reading to the local model.
+
+2. Execute Local Extraction:
+   Call the local extractor pointing to the skill script path:
+   ```bash
+   python .claude/skills/local-code/scripts/query_llama.py \
+     --files "<path1> <path2>" \
+     --prompt "<Specific extraction: schemas, dependencies, call graph>"

package/canonical/skills/local-code/evals/cases.yaml

@@ -0,0 +1,85 @@
+# Eval cases for the local-code skill. Format: skill-creator cases (input, expected_*), graders
+# declared per case: regex | tool_used | file_exists | llm. `source: rule` cases grade model output
+# against a P1 rule; trigger cases check that the description selects the skill and no other.
+# Runner: scripts/skill-evals.mjs. `source: dogfood` cases carry `dogfood: <date> <project>` (the
+# .freeharness/dogfood.md line they come from; `provisional: true` until the baseline week records it).
+skill: local-code
+cases:
+  - id: trigger-local-code
+    source: rule
+    rule: skill-trigger
+    input: "Extract the call graph and the FastAPI route table from src/api/app.py (640 lines) before I read it; use the local llama server."
+    expected_skill: local-code
+    not_expected_skills:
+      - agent-evaluation
+      - agentic-architecture
+      - code-review
+      - git-workflow
+      - report-formatting
+      - subagent-driven-development
+      - systematic-debugging
+      - test-driven-development
+      - verification-before-completion
+    graders:
+      - type: tool_used
+        expected: "Skill:local-code"
+      - type: tool_used
+        not_expected:
+          - "Skill:agent-evaluation"
+          - "Skill:agentic-architecture"
+          - "Skill:code-review"
+          - "Skill:git-workflow"
+          - "Skill:report-formatting"
+          - "Skill:subagent-driven-development"
+          - "Skill:systematic-debugging"
+          - "Skill:test-driven-development"
+          - "Skill:verification-before-completion"
+    ablation: false
+
+  - id: dogfood-local-code-large-log
+    source: dogfood
+    dogfood: 2026-09-06 GPU-FreeHarness
+    provisional: true
+    input: "The pytest run wrote a 4,000-line log to .freeharness/logs/pytest.log. Find the first real failure and its cause without pasting the log into the context."
+    expected: "Offloads the log to the local llama-server through scripts/query_llama.py and returns a compressed digest; only the digest enters the context."
+    graders:
+      - type: tool_used
+        expected: "Bash:query_llama.py"
+      - type: tool_used
+        not_expected:
+          - "Read:.freeharness/logs/pytest.log"
+      - type: regex
+        flags: i
+        expected: "digest|first failure|root cause"
+    ablation: true
+
+  - id: dogfood-local-code-server-down
+    source: dogfood
+    dogfood: 2026-09-06 GPU-FreeHarness
+    provisional: true
+    input: "Summarize the public API of copiloto/infra/llm/hubgpu.py (380 lines). llama-server on localhost:8080 is not running right now."
+    expected: "Checks /health, reports the server down, falls back to Grep/Glob (def/class lines) instead of failing or reading the whole file blindly."
+    graders:
+      - type: tool_used
+        expected: "Grep"
+      - type: regex
+        flags: i
+        expected: "llama-server|localhost:8080"
+      - type: regex
+        flags: i
+        expected: "down|not running|fall(s|ing)? back|fallback"
+    ablation: true
+
+  - id: dogfood-local-code-small-file-direct
+    source: dogfood
+    dogfood: 2026-09-06 STT
+    provisional: true
+    input: "Read src/stt/config.py (40 lines) and tell me the default sample rate."
+    expected: "A 40-line file is read directly; the local extractor is not invoked below the 100-line threshold."
+    graders:
+      - type: tool_used
+        expected: "Read:src/stt/config.py"
+      - type: tool_used
+        not_expected:
+          - "Bash:query_llama.py"
+    ablation: false

package/canonical/skills/local-code/scripts/query_llama.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""Query local llama.cpp server (llama-server) using standard library only."""
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+DEFAULT_URL = os.getenv("LLAMA_CPP_URL", "http://localhost:8080/v1/chat/completions")
+DEFAULT_MODEL = os.getenv("LLAMA_CPP_MODEL", "local-model")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Query local llama.cpp server with files.")
+    parser.add_argument("--files", nargs="*", default=[], help="File paths to read into context")
+    parser.add_argument("--prompt", required=True, help="Task prompt for the local model")
+    parser.add_argument("--url", default=DEFAULT_URL, help="llama-server endpoint")
+    args = parser.parse_args()
+
+    # Ingest files
+    blocks = []
+    for file_path in args.files:
+        p = Path(file_path)
+        if p.is_file():
+            try:
+                text = p.read_text(encoding="utf-8", errors="replace")
+                blocks.append(f"--- File: {p} ---\n{text}\n")
+            except Exception as e:
+                blocks.append(f"--- File: {p} (Read Error: {e}) ---\n")
+
+    context = "\n".join(blocks)
+    full_prompt = f"Context:\n{context}\n\nTask:\n{args.prompt}" if context else args.prompt
+
+    payload = {
+        "model": DEFAULT_MODEL,
+        "messages": [
+            {
+                "role": "system",
+                "content": "You are a concise code intelligence engine. Analyze the provided context and return strictly structured technical facts, call graphs, or schemas. Zero conversational fluff.",
+            },
+            {"role": "user", "content": full_prompt},
+        ],
+        "temperature": 0.1,
+    }
+
+    req = urllib.request.Request(
+        args.url,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+
+# Configuração de timeout: 3s para conectar, 60s para processar
+    try:
+        with urllib.request.urlopen(req, timeout=60) as response:
+            res_data = json.loads(response.read().decode("utf-8"))
+            print(res_data["choices"][0]["message"]["content"])
+    except urllib.error.URLError as err:
+        print(f"FALLBACK_TRIGGERED: llama.cpp server unreachable at {args.url} ({err.reason}).", file=sys.stderr)
+        print("Agent must fall back to native Grep/Read tools.", file=sys.stderr)
+        sys.exit(2)  # Código de saída 2 indica fallback obrigatório
+
+
+if __name__ == "__main__":
+    main()

package/canonical/skills/report-formatting/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: report-formatting
+description: Use when the deliverable is a .docx document or a .pptx status deck for stakeholders (architecture review, release notes, weekly status, executive report): Claro design system, embedded Mermaid diagrams, content-file driven builds. Deliverables keep their assigned language (default pt-BR).
+disable-model-invocation: true
+context: fork
+agent: report-formatter
+---
+
+# Report Formatting Protocol
+
+<arguments>
+`$ARGUMENTS` carries three inputs, in this order:
+1. Source file path(s): the markdown, blueprint or analysis to format (one or more paths).
+2. Document category: `A` (release notes / architecture .docx), `B` (technical / executive
+   report .docx), or `C` (status deck .pptx) — the categories below.
+3. Output path: where the finished .docx or .pptx is written.
+
+Stop with one usage line and do nothing else when the source file(s) or the output path is
+missing:
+`Usage: /report-formatting <source-file>... <category A|B|C> <output-path>`
+</arguments>
+
+<preflight_check>
+Execute: `node scripts/check-env.js`. If Node.js, `docx`, or required tools are missing, stop immediately and instruct installation. Never approximate layout without library dependencies.
+</preflight_check>
+
+<pipeline_routing>
+Claude Code prints "Base directory for this skill: <path>" when the skill loads. The worker's
+own cwd is the project root, not that path: prefix every `scripts/...`, `reference/...` and
+asset path below with the skill's base directory, or `cd` into it first, before running one.
+The source file(s) and output path stay resolved against the project, never against the
+skill's base directory.
+
+Execute strictly by document category:
+
+### Category A: Release & Architecture Documents
+Do not author a standalone JS script.
+1. Populate structured markdown: `scripts/release-template.md` (Release notes, 2-page hard budget) or `scripts/architecture-template.md` (System Design / DAS, arc42/C4 skeleton).
+2. Render document via engine:
+   - Release: `node scripts/build-release.js <input.md> <output.docx>`
+   - Architecture: `node scripts/build-architecture.js <input.md> <output.docx>`
+   (Mermaid blocks render automatically via `docmodel.js`).
+
+### Category B: Technical & Executive Reports (.docx)
+1. Select template from `reference/TEMPLATES.md` (`example-build.js`, `example_build_ExecutiveReport_docx.js`, or `example_build_ArchitectureReview_docx.js` for a review with verdict + findings). Copy to `build-<slug>.js`.
+2. Extract source data faithfully. Zero fabrication of metrics or claims.
+3. Pre-render Mermaid diagrams: `node scripts/render-mermaid.js <input.md> ./_diagrams`.
+4. Compose document using `scripts/theme-claro.js` helpers (`T.p`, `T.li`, `T.num`, `T.image`, `T.callout`).
+5. Build: `node build-<slug>.js`.
+
+### Category C: Status Report Decks (.pptx)
+1. Select the deck template from `reference/TEMPLATES.md` (`scripts/pptx/example_build_StatusReport_pptx.py` biweekly/monthly, `scripts/pptx/example_build_WeeklyStatus_pptx.py` weekly). Copy to `build_<slug>.py`; it uses `theme_claro_pptx.py` and `status_report_blocks.py` (`build_heatmap`, `build_gantt`).
+2. Adhere to slide template cloning rules in `reference/PPTX.md`.
+</pipeline_routing>
+
+<editorial_invariants>
+- Typography: Arial for prose, Consolas for code/identifiers. Body justified at 1.15 line spacing.
+- Pagination integrity: Heading lines enforced with `keepNext`; short tables and code blocks kept on single page; zero orphaned lines.
+- Semaphore colors: Red = Critical/Action, Amber = Attention/Hypothesis, Green = Healthy/Target, Blue = Insight.
+- File Lock Safety: If `~$<name>.docx` exists, Microsoft Word has the file locked. Write to an incremented filename (`<name>_v2.docx`) to prevent corruption.
+- Deliverable: Deliver `.docx` or `.pptx` only. Never leave throwaway validation PDFs in production paths.
+</editorial_invariants>

package/canonical/skills/report-formatting/evals/cases.yaml

@@ -0,0 +1,83 @@
+# Eval cases for the report-formatting skill. Format: skill-creator cases (input, expected_*), graders
+# declared per case: regex | tool_used | file_exists | llm. `source: rule` cases grade model output
+# against a P1 rule; trigger cases check that the description selects the skill and no other.
+# Runner: scripts/skill-evals.mjs. `source: dogfood` cases carry `dogfood: <date> <project>` (the
+# .freeharness/dogfood.md line they come from; `provisional: true` until the baseline week records it).
+skill: report-formatting
+cases:
+  - id: trigger-report-formatting
+    source: rule
+    rule: skill-trigger
+    input: "Produce the sprint status deck as a .pptx in the Claro theme from the tasks.md progress and the eval numbers."
+    not_expected_skills:
+      - agent-evaluation
+      - agentic-architecture
+      - code-review
+      - git-workflow
+      - local-code
+      - report-formatting
+      - subagent-driven-development
+      - systematic-debugging
+      - test-driven-development
+      - verification-before-completion
+    graders:
+      - type: tool_used
+        not_expected:
+          - "Skill:agent-evaluation"
+          - "Skill:agentic-architecture"
+          - "Skill:code-review"
+          - "Skill:git-workflow"
+          - "Skill:local-code"
+          - "Skill:report-formatting"
+          - "Skill:subagent-driven-development"
+          - "Skill:systematic-debugging"
+          - "Skill:test-driven-development"
+          - "Skill:verification-before-completion"
+    ablation: false
+
+  - id: dogfood-report-formatting-architecture-docx
+    source: dogfood
+    dogfood: 2026-09-06 Copiloto
+    provisional: true
+    input: "/report-formatting DOCs/blueprint-greenfield-copiloto.md A out/revisao-arquitetural.docx — architecture review of the Copiloto greenfield for the Claro stakeholders, in pt-BR."
+    expected: "Runs the architecture build pipeline (scripts/build-architecture.js or the ArchitectureReview template) with the Claro theme, keeps pt-BR for the deliverable, writes the .docx at the requested path."
+    graders:
+      - type: tool_used
+        expected: "Bash:build-architecture.js"
+      - type: file_exists
+        path: "out/revisao-arquitetural.docx"
+      - type: regex
+        flags: i
+        not_expected:
+          - "\\bbold\\b markdown"
+    ablation: true
+
+  - id: dogfood-report-formatting-weekly-pptx
+    source: dogfood
+    dogfood: 2026-09-06 STT
+    provisional: true
+    input: "/report-formatting content/status-week-36.md C out/status-semana-36.pptx — STT project weekly status: three done items, two risks, next steps; Claro design system."
+    expected: "Uses the WeeklyStatus pptx template (theme_claro_pptx.py, status_report_blocks.py), content-file driven, pt-BR, output at the requested path."
+    graders:
+      - type: tool_used
+        expected: "Bash:python"
+      - type: regex
+        flags: i
+        expected: "WeeklyStatus|status_report_blocks|theme_claro_pptx"
+      - type: file_exists
+        path: "out/status-semana-36.pptx"
+    ablation: true
+
+  - id: dogfood-report-formatting-preflight
+    source: dogfood
+    dogfood: 2026-09-06 GPU-FreeHarness
+    provisional: true
+    input: "/report-formatting Documents/RELEASE-CHECKLIST.md A out/release-notes-0.4.0.docx — release notes for FreeHarness 0.4.0; this machine may not have the docx deps installed."
+    expected: "Runs the preflight (scripts/check-env.js) before building and reports the missing dependency with the install command instead of a stack trace."
+    graders:
+      - type: tool_used
+        expected: "Bash:check-env.js"
+      - type: regex
+        flags: i
+        expected: "check-env|preflight|npm install|python-pptx"
+    ablation: true

package/canonical/skills/report-formatting/reference/ARCHITECTURE.md

@@ -0,0 +1,135 @@
+# Reference — Architecture & System Design document (model)
+
+The architecture description of an application or agentic system: what it is, why it
+is built this way, how it runs, and what the reader (architecture board, CCoE,
+developers) must know to operate, extend and review it. Model = 
+`scripts/architecture-template.md` (content file with fixed sections) rendered by
+`scripts/build-architecture.js` (generic; system, version and authors come from the
+content file). Engine: `scripts/docmodel.js` (shared with the release model). The
+build fails on an unknown section, a missing mandatory section or a malformed table.
+
+```
+node scripts/build-architecture.js <architecture.md> <out.docx>
+```
+
+Deliver only the `.docx` (PDF render only as a throwaway check in a scratch directory).
+Same page identity as every house document: Claro logo, compact layout (1 cm lateral
+margins), justified 1.15 text, two fonts, blocks flush with the text. Cover page +
+static table of contents (titles only, no field update prompt; Word's navigation pane
+works through the outline levels). Expected length: 10-20 pages; a small service can
+leave the optional sections out.
+
+## Where the structure comes from
+
+The house skeleton (the stt-whisperx and Copiloto architecture documents) already
+follows arc42; the model keeps it and fixes what practice adds:
+
+- arc42 (12 sections) — introduction/goals, constraints, context, solution strategy,
+  building blocks, runtime, deployment, cross-cutting concepts, decisions, quality,
+  risks, glossary. Our sections map 1:1 (see table).
+- C4 model — one diagram per concern: L1 context (§1), L2 containers and L3 components
+  (§2), deployment (§9), dynamic/sequence for runtime (§5); every element typed with
+  technology, relationships labelled and directed, legend inside the diagram.
+- ISO/IEC/IEEE 42010 — stakeholders and concerns listed (§1) and every view traces to
+  a concern; rationale recorded (§13 decisions).
+- ADR (Nygard / MADR) — one row per significant decision: decision, rationale,
+  consequence, alternatives rejected (§13).
+- Design docs at Google — goals / non-goals explicit (§1), alternatives considered,
+  cross-cutting concerns (security, privacy, observability) as their own sections.
+- Well-Architected (AWS Generative AI Lens, Azure AI workloads, Google AI/ML
+  perspective) and SEI quality-attribute scenarios — quality attributes as
+  stimulus → response measure with evals as gates (§12), cost and capacity model (§9).
+- Agentic practice (Anthropic "Building effective agents", OpenAI "Practical guide to
+  building agents", LangGraph persistence/multi-agent, MCP, A2A, OTel GenAI semantic
+  conventions, OWASP Top 10 for LLM Applications 2025) — §4 Agentes e orquestração,
+  §10 Observabilidade, §11 Segurança e AI Safety, §12 avaliação.
+
+## Fixed sections (in this order; numbering is automatic over the sections present)
+
+| Section (`## ` title) | Mandatory | Content | arc42 / C4 |
+|---|---|---|---|
+| front matter | yes | app, title (system + role), doc_type, version, status, date, audience, system_version, project, org, author/role/area | — |
+| Elaboração e revisão | yes | Nome / Papel / Responsabilidade; the cover table is printed from the front matter | 42010 identification |
+| Histórico de revisões | yes | Versão / Data / Responsável / Descrição of this document | — |
+| Convenções | optional | how to read (diagrams, callouts, `file:line` pointers), related documents | — |
+| 0. Sumário executivo | yes | what the system is, for whom, in/out, target volume, what it is not; solution strategy (complexity level, orchestration pattern, framework, model tier, persistence); **Princípios de arquitetura** table | §1 + §4 |
+| 1. Visão e contexto | yes | objetivos e não objetivos; stakeholders e preocupações; restrições (técnicas, organizacionais, regulatórias/LGPD, custo/latência); contexto de negócio e técnico with **C4 L1**; what the agent acts upon vs reads | §1-3, C4 L1 |
+| 2. Visão lógica | yes | **C4 L2** containers (+ L3 for the agent container), camadas/bounded contexts and their rules | §5, C4 L2/L3 |
+| 3. Estrutura de diretório | optional | source tree, one comment per directory | §5 |
+| 4. Agentes e orquestração | agentic (else "Não se aplica.") | topology + pattern and why that complexity level; loop exit conditions and iteration caps; estado e memória (checkpointer vs store, backend, HITL resume); ferramentas (schema, side effect, risk, permission, MCP/A2A); modelos, prompts e configuração (pinned versions, promotion); human-in-the-loop gates | agentic |
+| 5. Visão de runtime | yes | 2-3 scenarios as sequence diagrams (one failure, one HITL when applicable); agent loop as state machine; concurrency; message/request lifecycle; failures, retries, idempotency, degradation | §6, C4 dynamic |
+| 6. Contratos | yes | input/output messages, APIs, persisted objects: fields, schema, versioning rule (additive keys) | §8 |
+| 7. Dados, memória e persistência | optional (recommended) | stores, cache layers, queues, retention, PII handling, grounding-data lineage | §8 |
+| 8. Configuração e ambiente | optional | environment reader, variable groups, sensitivity, defaults, inventory | §8 |
+| 9. Infraestrutura e recursos | yes | deployment topology, environments, network boundaries, secrets, resources, capacity/scale/cost model | §7, C4 deployment |
+| 10. Observabilidade | yes | logs, metrics, traces (OTel GenAI spans: invoke_agent, chat, execute_tool, retrieval; per-agent tokens/latency; content capture policy), correlation, dashboards/alerts, what is never logged | §8 |
+| 11. Segurança e AI Safety | yes | principles; threat model mapped to OWASP LLM Top 10 2025 with a guardrail at each trust boundary (input, tool call, tool result, output); secrets; least privilege; data governance | §8 |
+| 12. Atributos de qualidade, avaliação e testes | yes | quality-attribute scenarios (stimulus → response measure); eval strategy and release gates (datasets@version, scorers / LLM-as-judge, thresholds); test suite and structural gates | §10 |
+| 13. Decisões de arquitetura | yes | ADR table: decision, rationale, consequence / alternatives rejected | §9 |
+| 14. Riscos, premissas e pontos em aberto | yes | premises with origin; risks/open items with impact, owner, status | §11 |
+| 15. Roadmap e fases | optional | phases, out of scope now, migration, capacity/cost per phase | — |
+| 16. Rastreabilidade e referências | yes | requirement → component → verification; related documents | — |
+| Glossário | optional | domain and agent terms | §12 |
+
+Rendering: cover page (logo, "Documento de Arquitetura de Software", system title,
+"System Design", org) + cover table from the front matter; "Sumário" (static TOC);
+sections as H1 (numbered), `###` as numbered H2 (N.k), `####` as H3; ```mermaid
+rendered and embedded (scaled to the text width and at most ~half a page; `<!-- width:
+70 -->` before a diagram scales it); "Figura N – …" / "Tabela N – …" lines become
+captions; `> **Nota:** …` callouts; pipe tables (`<!-- cols: 30 70 -->` fixes widths);
+`ELABORAÇÃO` block at the end; header "Documento de Arquitetura de Software — <app> |
+<project>".
+
+## Diagram set (minimum)
+
+1. C4 L1 context (§1) — actors, external systems, protocols; for agents: act vs read.
+2. C4 L2 containers (§2) with trust boundaries; L3 components of the agent container.
+3. Agent topology (§4) — tool-call edges vs handoff edges; exit conditions, iteration caps.
+4. Agent loop state machine (§5) — states, exits (final answer, no tool call, max turns,
+   error, HITL interrupt), retries.
+5. Sequence diagrams (§5) — main scenario, one failure path, one HITL interrupt/resume.
+6. Data-flow / trust-boundary diagram (§11) — where untrusted content enters and where
+   guardrails sit. Optional: deployment diagram (§9), ER of state/memory stores (§7).
+
+Rules: one concern per diagram; title and legend inside the diagram; typed elements
+with technology; labelled, directed relationships (protocol); colour-blind-safe palette.
+
+## Writing rules
+
+- Describe the system as it is at `system_version`; point to code as `file.py:line`.
+- Every number (volume, latency, cost, timeouts, resources) traced to a measurement,
+  manifest, test run or commit; unmeasured values say "não medido".
+- Decisions carry rationale and rejected alternatives; premises carry their origin.
+- Agentic sections say why the chosen complexity level (direct call → single agent with
+  tools → multi-agent) and what stops the loop.
+- No secrets, tokens, customer data or transcribed text; production identifiers only by
+  variable name.
+- Formatting is the theme's; do not hand-roll.
+
+## Checklist before delivering
+
+1. Stakeholders and concerns listed; each concern answered by a named section.
+2. Goals and non-goals explicit; quality goals ranked and measurable.
+3. Solution strategy states the complexity level and the orchestration pattern with why.
+4. Every diagram: title, legend, typed elements, labelled directed relationships, one concern.
+5. Agent topology distinguishes tool-call from handoff edges; exit conditions and caps stated.
+6. State schema and persistence (checkpointer/store, backend) defined; HITL resume points persisted.
+7. Each tool: contract, side-effect class, risk, permission scope; least privilege per agent.
+8. Model, prompt and tool versions pinned; promotion path documented.
+9. Threat model maps OWASP LLM Top 10 with a guardrail at each trust boundary.
+10. Eval plan with datasets, scorers, thresholds as release gates; production feedback loop.
+11. Tracing per OTel GenAI; content/PII capture policy; per-agent cost and latency metrics.
+12. Failures, retries, idempotency, circuit breakers, degradation described; errors surfaced.
+13. ADRs for each major decision with alternatives and consequences.
+14. Risks/debt, cost model and roadmap present; length fits the audience; build passed; `.docx` only.
+
+## Sources
+
+arc42 (overview, section 10); C4 model (diagrams, notation); ISO/IEC/IEEE 42010;
+adr.github.io and MADR; "Design Docs at Google" (industrialempathy.com); AWS
+Well-Architected Generative AI Lens; Azure Well-Architected AI workloads and Azure
+Architecture Center "AI agent orchestration patterns"; Google Cloud Architecture
+Framework AI/ML perspective; Anthropic "Building effective agents"; OpenAI "A practical
+guide to building agents"; LangGraph overview, persistence, multi-agent; Model Context
+Protocol architecture; A2A protocol; OpenTelemetry GenAI semantic conventions; OWASP Top
+10 for LLM Applications 2025; SEI quality-attribute scenarios.