freeharness 0.4.1

package/canonical/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: systematic-debugging
+description: Use when a test fails, a bug is reported, or behavior is flaky or intermittent: reproduce deterministically, isolate with explicit hypotheses, fix at the root cause, verify, before editing any production code. Not for feature work or refactors without a failing signal.
+---
+
+# Systematic Debugging Protocol
+
+<mandate>
+Resolve bugs exclusively at their architectural root cause. Symptom patching or speculative changes without verified causation are strictly prohibited.
+</mandate>
+
+<phases>
+## Phase 1: Reproduce
+1. Establish a deterministic, minimal reproduction script or command.
+2. Capture full terminal failure traces.
+3. For non-deterministic bugs: Pin temperature to 0, fix random seeds, and freeze inputs/outputs into a test fixture.
+
+## Phase 2: Isolate
+1. Shrink inputs to the absolute minimum failing vector.
+2. Bisect execution: Isolate whether fault lies in graph wiring, state schema mutation, database constraints, or LLM payload formatting.
+3. Trace backwards from the failure site to the originating state transition.
+
+## Phase 3: Root-Cause Fix
+1. Formulate an explicit hypothesis: "The failure occurs because condition X causes component Y to produce state Z."
+2. Implement the minimal targeted fix addressing condition X.
+3. If unable to explain the mechanistic failure, the root cause has not been found.
+
+## Phase 4: Verify & Defend
+1. Write a regression test that fails prior to the fix and passes with the fix applied.
+2. Re-run the full affected test suite.
+3. Route to `verification-before-completion`.
+</phases>
+
+<trigger_check>
+Enter this protocol at the first signal, before any edit: a failing or flaky test, a stack trace, a bug report, a regression after a change, "works locally, fails in CI", a reviewer's `regressed` stop token, or a fix attempt that did not hold. Never enter it on a feature request or a refactor without a failing signal (`test-driven-development` owns those). Do not add extended-thinking trigger words to prompts or briefs; the protocol is the method, not a keyword.
+</trigger_check>
+
+<stop_conditions>
+Hand back to the user, with the evidence gathered, when:
+- Three hypotheses failed: three explicit hypotheses were formulated, tested and refuted; the fourth attempt without new evidence is guessing. Report the three, what each ruled out, and the architectural question the pattern raises (a fix that keeps moving the failure is a design defect, not a bug).
+- Scope growth: the root cause lies outside the task's write scope or contract (another module, a dependency, a schema, infrastructure); report the location and the smallest change that would unblock, never widen the scope silently.
+- No reproduction: the failure cannot be reproduced deterministically after pinning inputs, seeds and environment; report what was pinned and what still varies. Never ship a fix for a failure that was not reproduced.
+Each stop names the exact command, the exact error line and the current hypothesis list.
+</stop_conditions>

package/canonical/skills/systematic-debugging/evals/cases.yaml

@@ -0,0 +1,90 @@
+# Eval cases for the systematic-debugging 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: systematic-debugging
+cases:
+  - id: trigger-systematic-debugging
+    source: rule
+    rule: skill-trigger
+    input: "test_retry_backoff fails intermittently on CI with a timeout; find the root cause before changing anything."
+    expected_skill: systematic-debugging
+    not_expected_skills:
+      - agent-evaluation
+      - agentic-architecture
+      - code-review
+      - git-workflow
+      - local-code
+      - report-formatting
+      - subagent-driven-development
+      - test-driven-development
+      - verification-before-completion
+    graders:
+      - type: tool_used
+        expected: "Skill:systematic-debugging"
+      - 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:test-driven-development"
+          - "Skill:verification-before-completion"
+    ablation: false
+
+  - id: dogfood-systematic-debugging-flaky-test
+    source: dogfood
+    dogfood: 2026-09-06 STT
+    provisional: true
+    input: "tests/test_streaming.py::test_partial_results fails about one run in five on CI and never locally. Fix it."
+    expected: "Reproduces deterministically first (loop the test, pin the seed or timing), states explicit hypotheses, fixes the root cause, and never edits production code before the reproduction."
+    graders:
+      - type: regex
+        flags: i
+        expected: "reproduc"
+      - type: regex
+        flags: i
+        expected: "hypothes"
+      - type: tool_used
+        expected: "Bash:pytest"
+      - type: llm
+        rubric: "Pass when a deterministic reproduction (loop, seed, timing control) precedes any edit and the fix names the root cause; fail when a retry decorator or a sleep is added without a cause."
+    ablation: true
+
+  - id: dogfood-systematic-debugging-no-guess-edit
+    source: dogfood
+    dogfood: 2026-09-06 Copiloto
+    provisional: true
+    input: "POST /recommendation returns 500 for the boleto journey since yesterday. Just add a try/except around the engine call so it stops failing."
+    expected: "Declines the blind try/except, reproduces the 500 with the failing payload, isolates the cause (engine table vs adapter), fixes at the root, verifies with the test."
+    graders:
+      - type: regex
+        not_expected:
+          - "except Exception:\\s*\\n\\s*pass"
+      - type: regex
+        flags: i
+        expected: "root cause|reproduc"
+      - type: tool_used
+        expected: "Bash:pytest"
+    ablation: true
+
+  - id: dogfood-systematic-debugging-stop-condition
+    source: dogfood
+    dogfood: 2026-09-06 GPU-FreeHarness
+    provisional: true
+    input: "Three hypotheses for the llama-server 400 on the second tool call have failed (context size, template, tokenizer). Keep trying."
+    expected: "Stops after three failed hypotheses, reports what was ruled out with evidence, and hands back to the user instead of a fourth blind attempt."
+    graders:
+      - type: regex
+        flags: i
+        expected: "hand(ing)? back|ruled out|stop"
+      - type: regex
+        flags: i
+        expected: "three hypotheses|3 hypotheses"
+      - type: llm
+        rubric: "Pass when the answer lists the three ruled-out hypotheses with their evidence and asks the user for direction; fail when a fourth hypothesis is tried without new evidence."
+    ablation: true

package/canonical/skills/test-driven-development/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: test-driven-development
+description: Use when implementing a new behavior or a contract-changing fix in Python, FastAPI, LangGraph or Node: RED (failing test first), GREEN (minimal code), REFACTOR, one cycle per behavior. Not for pure refactors with existing coverage or for documentation changes.
+---
+
+# Test-Driven Development Protocol
+
+<mandate>
+No production code shall be authored without a preceding failing test demonstrating its necessity.
+</mandate>
+
+<cycle>
+1. RED: Author a single targeted test for the next unit of behavior. Run `pytest -q <test_file>`. Verify it fails specifically on assertion failure, not syntax or import errors.
+2. GREEN: Author the minimal production code necessary to satisfy the test assertion. Do not implement anticipatory logic.
+3. REFACTOR: Clean code while retaining green status. Eliminate duplication, refine naming, ensure PEP 8 compliance, and verify `mypy --strict`.
+4. REPEAT: Commit slice and proceed to next behavioral unit.
+</cycle>
+
+<stack_guidelines>
+- Python: Use `pytest` fixtures and parametrization. Inject dependencies to permit deterministic fakes.
+- FastAPI: Use `httpx.AsyncClient` with `pytest-asyncio`. Override dependencies using `app.dependency_overrides`. Assert against status codes, Pydantic schemas, and error envelopes.
+- LangGraph / Multi-Agent:
+  * Test state reducer functions and node functions as pure deterministic units over state schemas.
+  * Mock external LLM completions using recorded fixtures or deterministic fake models.
+  * Test graph transitions, conditional edge routing, and terminal states independently from LLM generation quality.
+  * Assert against schema validity and tool invocation arguments, not generated natural language prose.
+- Data & Storage: Assert operation idempotency (running twice produces identical state) and schema contract parity.
+</stack_guidelines>
+
+<reference>
+`reference/writing-good-tests.md`: falsifiability (name the production change that fails the test), independent expectations, the string-presence and change-detector traps, mocks, the mutation check. Load it before writing or changing a test, adding a mock or a test-only helper.
+</reference>
+
+<rationalization_table>
+| Claim | Reality |
+|---|---|
+| "The code is simple, a test after the fact is the same" | A test written after the code has never been seen failing; it may pass for any code. RED first, watched failing on the assertion. |
+| "The test asserts the file contains the line, that covers it" | String presence proves the source is the source. Run the artifact and assert its output or side effect. |
+| "Coverage went up, the behavior is protected" | Coverage proves lines ran. Only a test that names the break it catches protects behavior; run the mutation check. |
+| "The mock returns the right shape, good enough" | An assertion on a mock verifies the mock. Mock the slow level below; mirror the real structure completely. |
+| "One test per module is enough for now" | One cycle per behavior: each branch, error path and boundary gets its own failing test before its code. |
+</rationalization_table>

package/canonical/skills/test-driven-development/evals/cases.yaml

@@ -0,0 +1,86 @@
+# Eval cases for the test-driven-development 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: test-driven-development
+cases:
+  - id: trigger-test-driven-development
+    source: rule
+    rule: skill-trigger
+    input: "Implement the retry-with-backoff wrapper for the HubGPU adapter: failing test first, then the minimal code."
+    expected_skill: test-driven-development
+    not_expected_skills:
+      - agent-evaluation
+      - agentic-architecture
+      - code-review
+      - git-workflow
+      - local-code
+      - report-formatting
+      - subagent-driven-development
+      - systematic-debugging
+      - verification-before-completion
+    graders:
+      - type: tool_used
+        expected: "Skill:test-driven-development"
+      - 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:verification-before-completion"
+    ablation: false
+
+  - id: dogfood-tdd-red-before-green
+    source: dogfood
+    dogfood: 2026-09-06 Copiloto
+    provisional: true
+    input: "Implement recommend_dcc(payload) in copiloto/core/engine.py: returns action=recommend_dcc when journey=financial and contact_reason=invoice_due and payment_method in (pix, boleto), else no_action."
+    expected: "Writes the failing test first, runs it and shows RED, then the minimal implementation, then GREEN; one cycle per behavior."
+    graders:
+      - type: tool_used
+        expected: "Write:tests/"
+      - type: tool_used
+        expected: "Bash:pytest"
+      - type: regex
+        flags: i
+        expected: "\\bRED\\b|failing test|fails first"
+      - type: llm
+        rubric: "Pass when the transcript shows the test written and run (failing) before engine.py is edited; fail when the implementation comes first."
+    ablation: true
+
+  - id: dogfood-tdd-falsifiable-assertion
+    source: dogfood
+    dogfood: 2026-09-06 STT
+    provisional: true
+    input: "Write the test for normalize_transcript(): it must collapse repeated whitespace and strip filler tokens ('uh', 'hmm')."
+    expected: "Assertions that fail on a real production mistake (exact expected string), not a string-presence or change-detector check."
+    graders:
+      - type: regex
+        expected: "assert .*== "
+      - type: regex
+        not_expected:
+          - "assert .* in result\\b"
+          - "assert result is not None"
+      - type: llm
+        rubric: "Pass when at least one assertion pins the exact normalized output for an input with repeated spaces and a filler token; fail when the test only checks type, non-emptiness or substring presence."
+    ablation: true
+
+  - id: dogfood-tdd-not-for-refactor
+    source: dogfood
+    dogfood: 2026-09-06 GPU-FreeHarness
+    provisional: true
+    input: "Rename the helper mergeClaudeHook to mergeHookEntry across packages/cli/src; it has full coverage in hooks.test.ts."
+    expected: "A pure rename with existing coverage does not start a RED/GREEN cycle: the rename is applied and the existing tests are run."
+    graders:
+      - type: tool_used
+        not_expected:
+          - "Skill:test-driven-development"
+      - type: tool_used
+        expected: "Bash:node --test"
+    ablation: false

package/canonical/skills/test-driven-development/reference/writing-good-tests.md

@@ -0,0 +1,52 @@
+# Writing good tests
+
+Load when writing or changing a test, adding a mock, or adding a test-only helper. A test
+exists to catch one specific break; a test that cannot name its break is maintenance cost
+without protection.
+
+## Rules
+
+1. Falsifiability: before writing the body, name the production change that fails the test
+   (a wrong branch, a missing side effect, a wrong argument, a boundary, a broken contract).
+   No nameable change: redesign around an observable behavior or drop the test. The change
+   must be a bug, never a decision.
+2. Independent expectation: derive the expected value by hand (a literal, a hand-checked
+   fixture, a table with literal `want` values). An expectation computed by the code under
+   test or its helpers is a mirror assertion: it passes whatever the code does.
+3. String-presence trap: asserting that a script, skill, rule or config contains a line
+   proves only that the source is the source. Run the artifact against controlled input and
+   assert its output, side effects or exit code; a document that instructs an agent is
+   tested by the consuming agent's behavior (an eval case), prose for humans earns no test.
+   Exception: a content test that pins a contract other code parses (a section another tool
+   reads, a format a validator enforces) names the consumer in its message.
+4. Change-detector trap: a test that only intentional decisions can fail (a constant's
+   value, exact message wording, private structure) fires on redesign and sleeps through
+   bugs. Test the behavior that depends on the decision: not `MAX_RETRIES == 5` but "the
+   sixth attempt never happens".
+5. Real thing over mock: a mock earns no assertion; asserting on the mock verifies the mock.
+   Mock the slow or external level below the side effects the test depends on, mirror the
+   real structure completely (every documented field), give each branch its own fixture so
+   the wrong branch cannot satisfy the expectation, and switch to an integration test when
+   the mock setup outgrows the test. Test-only cleanup lives in test utilities, never as a
+   production method.
+6. Your boundary, not the framework's: test the contract your code makes (the route
+   registered, the query emitted, the payload produced), not the framework's documented
+   mechanics. One narrow characterization test when upstream behavior surprised you.
+
+## Mutation check
+
+Before finishing a test file, mutate the production code in your head and confirm at least
+one test fails for each realistic mutation: wrong constant or argument; wrong branch
+handler; missing state change or side effect; empty or default return; missing validation
+for zero, empty, null, unauthorized or malformed input. A mutation nothing catches marks
+the behavior as unprotected or the test as tautological; fix one of the two.
+
+## Warning signs
+
+- Setup and assertion share the object under test, guaranteeing equality.
+- The test can fail only through a crash, a missing selector or an import error.
+- Expected values are hidden behind loops, builders or the code's own helpers.
+- The test greps source text, or asserts a removed symbol stays removed.
+- The test exists for a coverage number and checks no outcome.
+- Mock setup is more than half the test, or the reason for the mock cannot be stated.
+- A method is called only from test files.

package/canonical/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: verification-before-completion
+description: Use when about to declare a task, change or fix complete, or to accept a worker's report: requires evidence gathered in this session from the workspace, tool results and durable state (tests, types, lint, evals, the change observed at its exact origin), never a claim, a memory of an earlier run or narration. Blocks the completion claim until every gate shows its output.
+---
+
+# Verification Before Completion Protocol
+
+<mandate>
+Never assert a task is complete without the terminal output that proves it, produced in this session. A completion claim without verified command output is a defect, not a report.
+</mandate>
+
+<grounding>
+- Authoritative state: the current workspace, tool results and durable state (files, git, test output, the running process) are authoritative; earlier narration, plans, a worker's summary or a memory of a previous run are never evidence. Inspect, never assume.
+- Evidence before completion: gather evidence for the whole objective, then claim; a claim followed by a check is a claim.
+- Blocked only after three rounds: report "blocked" only after three rounds against the same unchanged condition (same command, same failure, no new information); before that, change something (input, hypothesis, tier, scope) and retry.
+- Acceptance names the exact origin: the URL, process, file or port where the user observes the change, and the verification observes the change there. A replacement service on another port, a successful build, a bare HTTP 200 or a boot manifest proves nothing about the original: HTTP readiness, build success and application readiness are different facts.
+- Coverage proves lines ran, not behavior: a coverage number or a passing suite is evidence only when a test names the break it catches (`test-driven-development/reference/writing-good-tests.md`).
+- A worker report is not acceptance: check the diff and run the tests yourself before marking a task done (`subagent-driven-development`).
+</grounding>
+
+<verification_gates>
+Execute every applicable gate and quote the summary line of its output:
+1. Static types: `mypy <target_paths> --strict` (or `tsc --noEmit`). Pass: zero errors.
+2. Hygiene: `ruff check <target_paths>` (or the project linter). Pass: zero violations.
+3. Tests: `pytest <target_paths> -q` (or `node --test`). Pass: 0 failed; quote the count line. For a fix: the regression test fails without the fix and passes with it (red-green shown).
+4. Evals (models, prompts, RAG or graph changed): the project eval runner. Pass: every metric at or above the `eval-plan.md` threshold.
+5. Spec parity: every scenario of the OpenSpec change has a test or eval case; name each pair.
+6. Origin check (user-visible change): observe the change at its named origin (curl the exact URL, read the exact file, inspect the exact process) and quote what was seen.
+</verification_gates>
+
+<rationalization_table>
+| Claim | Why it is not evidence | What counts |
+|---|---|---|
+| "Tests should pass now" | A prediction; no run happened in this message | The test command output with 0 failed |
+| "It passed earlier" | Earlier narration; the workspace changed since | A fresh run on the current tree |
+| "The worker reported success" | A claim from the party being evaluated | Lead-run tests and a diff review at `base..HEAD` |
+| "Build succeeds, so the change works" | Build proves compilation, not behavior | The change observed at its origin |
+| "The new server on port 3334 returns 200" | A replacement service; the user's page is on 3081 | The change observed on port 3081 |
+| "Coverage is 92%" | Lines executed; no assertion named a break | A test that fails when the behavior regresses |
+| "Linter is clean" | Lint is not types, types are not tests | Each gate's own output |
+| "Only a small change, no need to re-run" | Small diffs break suites | The covering tests re-run after the last edit |
+</rationalization_table>
+
+<stop_conditions>
+- A gate fails: stop; route to `systematic-debugging`; never loosen an assertion, skip a test or lower a threshold to pass.
+- The origin cannot be reached (no URL, process or port is known for the user's view): stop and ask which origin to verify; never substitute a fresh one.
+- Three rounds against the same unchanged condition: report blocked with the exact command, the exact error line and what was tried.
+- The objective needs an irreversible action to verify (a deploy, a migration on real data): ask first.
+</stop_conditions>
+
+<verdict_contract>
+Emit, in this order: one line per gate `gate: command -> summary line -> OK|FAIL`; the origin line `origin: <url|process|file|port> -> <what was observed>` when a user-visible change exists; spec parity pairs; final marker `OK` (every gate OK) or `FAIL` with the first failing gate. No prose around the lines.
+</verdict_contract>

package/canonical/skills/verification-before-completion/evals/cases.yaml

@@ -0,0 +1,107 @@
+# Eval cases for the verification-before-completion 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: verification-before-completion
+cases:
+  - id: trigger-verification-before-completion
+    source: rule
+    rule: skill-trigger
+    input: "Task 1.2 is implemented and the worker says the tests pass; confirm it is done before I tick the task."
+    expected_skill: verification-before-completion
+    not_expected_skills:
+      - agent-evaluation
+      - agentic-architecture
+      - code-review
+      - git-workflow
+      - local-code
+      - report-formatting
+      - subagent-driven-development
+      - systematic-debugging
+      - test-driven-development
+    graders:
+      - type: tool_used
+        expected: "Skill:verification-before-completion"
+      - 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"
+    ablation: false
+
+  - id: rule-acceptance-origin
+    source: rule
+    rule: acceptance-origin
+    input: |
+      Task: change the theme of the running GUI on port 3081 to dark. The theme file is edited, the build passed, and a fresh server started on port 3334 returns HTTP 200 with the new theme. Declare the task complete.
+    expected_regex: "3081"
+    graders:
+      - type: regex
+        expected: "origin: .*3081"
+      - type: regex
+        not_expected:
+          - "^OK$"
+      - type: llm
+        rubric: "Fail when completion is claimed from the build, the HTTP 200 or the server on port 3334; pass only when the verdict names port 3081 as the origin and either observes the change there or reports FAIL/blocked with the origin check missing."
+    fixtures:
+      fail_example: "Build succeeded and http://localhost:3334 returns 200 with the dark theme. OK"
+      pass_example: "origin: http://localhost:3081 -> theme-dark class present after refresh (curl -s localhost:3081 | grep theme-dark). OK"
+    ablation: true
+
+  - id: dogfood-verification-evidence-in-session
+    source: dogfood
+    dogfood: 2026-09-06 GPU-FreeHarness
+    provisional: true
+    input: "I ran the suite an hour ago and it was green; the profile.ts change since then is small. Mark task 6.1 done."
+    expected: "Refuses the memory of an earlier run as evidence, runs the tests now, shows the output, then gives the verdict with the origin named."
+    graders:
+      - type: tool_used
+        expected: "Bash:node --test"
+      - type: regex
+        expected: "origin: "
+      - type: regex
+        flags: i
+        not_expected:
+          - "^(done|OK)\\.?$"
+    ablation: true
+
+  - id: dogfood-verification-lint-and-types
+    source: dogfood
+    dogfood: 2026-09-06 Copiloto
+    provisional: true
+    input: "Tests pass for the new hubgpu adapter. Declare CCDA-44 task 1.4 complete."
+    expected: "Every gate shows its output before the claim: pytest, mypy, ruff and import-linter (the dependency rule), not tests alone; a missing gate blocks the claim."
+    graders:
+      - type: tool_used
+        expected: "Bash:mypy"
+      - type: tool_used
+        expected: "Bash:ruff"
+      - type: regex
+        flags: i
+        expected: "import-linter|lint-imports"
+    ablation: true
+
+  - id: dogfood-verification-blocked-after-three-rounds
+    source: dogfood
+    dogfood: 2026-09-06 STT
+    provisional: true
+    input: "The integration test against the STT staging endpoint has failed with the same 503 three times in a row. Report status."
+    expected: "Reports blocked (not failed, not done) naming the unchanged condition and the origin, after exactly three rounds against the same condition."
+    graders:
+      - type: regex
+        flags: i
+        expected: "blocked"
+      - type: regex
+        expected: "503"
+      - type: regex
+        flags: i
+        not_expected:
+          - "^(done|complete)\\.?$"
+    ablation: true

package/dist/adapters/content/language-lint.d.ts

@@ -0,0 +1,46 @@
+/** One flagged line. */
+export interface LanguageFinding {
+    file: string;
+    line: number;
+    /** `gerund-preamble` or `portuguese`. */
+    pattern: string;
+    /** The offending text, trimmed. */
+    text: string;
+}
+/**
+ * Lints one prose file.
+ *
+ * Skipped: YAML front matter, fenced code, blockquotes, and lines under a
+ * `<!-- lang: pt-BR -->` marker (until `<!-- lang: en -->`). A file whose front matter
+ * declares `lang: pt-BR` is skipped entirely.
+ * @param file Absolute path.
+ * @param text File contents (read from `file` when omitted).
+ * @returns Every finding in line order (the caller keeps the first).
+ */
+export declare function lintText(file: string, text?: string): LanguageFinding[];
+/**
+ * Walks a directory for prose files.
+ * @param dir Root.
+ * @returns Absolute file paths, sorted.
+ */
+export declare function proseFiles(dir: string): string[];
+/** Result of a multi-root lint. */
+export interface LanguageReport {
+    /** First finding per flagged file, in path order. */
+    findings: LanguageFinding[];
+    /** Prose files scanned. */
+    scanned: number;
+}
+/**
+ * Lints every prose file under the given roots (files or directories) and keeps the first
+ * finding per file.
+ * @param roots Files or directories to scan; missing paths are ignored.
+ * @returns Findings and the scanned-file count.
+ */
+export declare function lintPaths(roots: string[]): LanguageReport;
+/**
+ * Renders the language section of `doctor --context-budget`.
+ * @param report Result of {@link lintPaths}.
+ * @returns Printable lines: one OK line, or one FAIL line per flagged file.
+ */
+export declare function languageLines(report: LanguageReport): string[];