arkaos 4.16.0 → 4.18.0

package/core/workflow/transcript_scope.py

@@ -72,3 +72,49 @@ def split_from_path(transcript_path: str) -> ScopeSplit:
     except OSError:
         return ScopeSplit()
     return split_by_scope(raw)
+
+
+def recent_user_messages(raw_text: str, limit: int = 6) -> list[str]:
+    """The most recent USER message texts, newest last.
+
+    ``split_by_scope`` collects assistant records only. A gate that must
+    know what the OPERATOR asked — not what the agent said — needs the
+    other role, and reading the wrong one inverts the gate: the guarded
+    agent could authorise its own edit while the operator's real request
+    is never seen. Sidechain (subagent) user turns are excluded — a
+    dispatched agent's prompt is not the operator speaking.
+    """
+    found: list[str] = []
+    for line in raw_text.splitlines():
+        if not line.strip():
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(record, dict):
+            continue
+        message = record.get("message")
+        message = message if isinstance(message, dict) else {}
+        role = record.get("role") or message.get("role")
+        if role != "user" or record.get("isSidechain", False):
+            continue
+        content = record.get("content")
+        if content is None:
+            content = message.get("content")
+        text = _extract_text(content)
+        if text:
+            found.append(text)
+    return found[-limit:]
+
+
+def user_messages_from_path(transcript_path: str, limit: int = 6) -> list[str]:
+    """Recent operator messages from a transcript file. Never raises."""
+    path = Path(transcript_path) if transcript_path else None
+    if path is None or not path.exists():
+        return []
+    try:
+        raw = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return []
+    return recent_user_messages(raw, limit)

package/departments/dev/skills/click-path-audit/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: dev/click-path-audit
+description: >
+  Simulates every interactive handler call-by-call to find bugs a normal
+  read skips over — shared-state side effects, handlers that silently undo
+  each other, and async races — then checks the final UI state matches
+  what the control promises. TRIGGER: "/dev click-path-audit", "the button
+  does nothing", "state side effects", "handlers cancel each other", "why
+  is the UI wrong after clicking", "o botão não faz nada", "audita o fluxo
+  de cliques"; run on an interactive component whose behaviour is wrong but
+  whose code looks right. SKIP: general pre-merge review ->
+  dev/code-review wins; visual/layout/brand review ->
+  brand/design-review wins.
+allowed-tools: [Read, Grep, Glob]
+metadata:
+  origin: ecc-derived
+  source: https://github.com/affaan-m/ecc
+  license: MIT
+---
+
+# Click-Path Audit — `/dev click-path-audit`
+
+> **Agent:** Diana (Senior Frontend Developer) | **Framework:** Handler state-tracing, shared-state side-effect analysis
+
+Some interface bugs survive every check that looks at one thing at a time.
+Each handler compiles, each function returns the right type, each call
+works when you test it alone — and the button still does the wrong thing,
+because the second call quietly resets the state the first one set. This
+lens catches those by simulating the handler on paper: it walks the calls
+in the order they run and tracks what each reads, writes, and resets in
+shared state, so a cancelling side effect shows up before a user ever
+clicks.
+
+## The bug this catches
+
+A "New Email" button called `setComposeMode(true)` then `selectThread(null)`.
+Each call was correct on its own, but `selectThread` reset `composeMode`
+back to false as a side effect, so the button opened nothing — no type
+error, no crash, and no unit test to catch it. Tracing the two calls in
+order makes the reset obvious on the page.
+
+## Process
+
+For every interactive touchpoint in scope (`onClick`, `onSubmit`, `onChange`, effects):
+
+1. **Identify** the handler.
+2. **Trace** each call it makes, in order.
+3. For each call record: what shared state it **reads**, what it **writes**, and any **side effect** — especially a state it clears or resets that it does not obviously own.
+4. **Check** whether any later call undoes a state change an earlier call made.
+5. **Check** the final state matches what the control's label promises.
+6. **Check** for races — async calls whose resolution order changes the outcome (a stale response overwriting a fresh one).
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- two calls in one handler that write the same store slice → which one wins, and is that intended
+- a setter with a side effect that resets unrelated state (a `select`/`reset`/`clear` that touches more than its name implies) → the earlier change it silently undoes
+- an `await` inside a handler with no guard against an out-of-order resolution → the stale-overwrite race
+
+## Output
+
+```markdown
+## Click-Path Report
+
+**Scope:** {component / area audited}
+
+### {control / handler} — {file}:{line}
+| # | Call | Reads | Writes | Side effect |
+|---|------|-------|--------|-------------|
+| 1 | {fn} | {state} | {state} | {reset/clear, or none} |
+| 2 | {fn} | {state} | {state} | {undoes call 1's write?} |
+
+**Promised by label:** {what the user expects} · **Actual final state:** {what happens}
+**Verdict:** {works / silently broken} · **Fix:** {reorder, isolate the side effect, guard the race}
+```

package/departments/dev/skills/pr-test-analyzer/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: dev/pr-test-analyzer
+description: >
+  Judges whether a PR's tests would catch the change breaking — maps
+  changed code to its tests, finds untested paths and edge cases, flags
+  assertion-free and flaky tests, and ranks the gaps by blast radius.
+  TRIGGER: "/dev pr-test-analyzer", "test coverage of this PR", "are these
+  tests enough", "behavioural coverage", "test gaps", "os testes cobrem
+  isto?", "isto está bem testado?"; run on a diff before approving its
+  merge. SKIP: general code review -> dev/code-review wins; writing the
+  missing tests -> dev/tdd-cycle wins; error-handling review ->
+  dev/silent-failure-hunter wins.
+allowed-tools: [Read, Grep, Glob, Bash]
+metadata:
+  origin: ecc-derived
+  source: https://github.com/affaan-m/ecc
+  license: MIT
+---
+
+# PR Test Analyzer — `/dev pr-test-analyzer`
+
+> **Agent:** Rita (QA Engineer) | **Framework:** Behavioural coverage, test-quality over line-coverage
+
+Coverage is a measure of which lines ran, and it is routinely mistaken for
+a measure of whether the change is safe. A PR can add a feature, run every
+new line through one happy-path test that asserts almost nothing, and post
+a green 100%. This lens reads the diff and its tests side by side and holds
+them to the only standard that matters at merge time: if the change were
+wrong, would a test go red?
+
+## Analysis
+
+### 1. Map changed code to tests
+- List the functions, classes, and branches the diff added or altered.
+- Locate the tests that exercise each. Name the changed paths with **no** test.
+
+### 2. Behavioural coverage
+- Does each new behaviour have a test that would fail if the behaviour broke?
+- Are the edge cases covered — empty input, boundary values, the error path, not just the success path?
+- Are the integrations the change touches (db, queue, external call) exercised, or only mocked away?
+
+### 3. Test quality
+- Flag tests that assert nothing beyond "it did not throw" — a green test that proves nothing.
+- Flag flaky patterns: time/order dependence, shared mutable state, sleeps.
+- Check that test names describe the behaviour, so a failure reads as a spec.
+
+### 4. Rank the gaps
+Rate each gap by the blast radius of the bug it would let ship:
+critical (data loss, auth, money), important (a real feature path),
+nice-to-have (a defensive branch unlikely to trigger).
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- a changed function with no test at all → critical or important by its blast radius; name it
+- a new test with no assertion (or only `assert not raises`) → it proves nothing; say what it should assert
+- an error/exception path added in the diff with only the happy path tested → the failure that ships untested
+
+## Output
+
+```markdown
+## PR Test Report
+
+**Diff:** {files / functions changed}
+**Verdict:** {tests adequate to merge? yes / gaps below}
+
+### Coverage summary
+{what is covered well, in one or two lines}
+
+### Critical gaps
+- {file}:{func} — {the behaviour with no failing test} → {the test to add}
+
+### Test-quality issues
+- {file}:{test} — {assertion-free / flaky} → {fix}
+
+### Positive
+{what the tests do genuinely well}
+```

package/departments/dev/skills/silent-failure-hunter/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: dev/silent-failure-hunter
+description: >
+  Hunts silent failures — swallowed exceptions, errors coerced to null,
+  fallbacks that mask a broken path, lost stack traces, and unguarded
+  network/file/db/transaction calls — and reports the concrete failure
+  each one hides, ranked by blast radius. TRIGGER: "/dev
+  silent-failure-hunter", "silent failures", "swallowed errors", "empty
+  catch", "error handling review", "falhas silenciosas", "erros
+  engolidos", "isto está a falhar em silêncio?"; run on the error paths
+  of any change touching I/O, network, db, or transactions. SKIP: general
+  pre-merge review -> dev/code-review wins; test coverage of the change ->
+  dev/pr-test-analyzer wins.
+allowed-tools: [Read, Grep, Glob]
+metadata:
+  origin: ecc-derived
+  source: https://github.com/affaan-m/ecc
+  license: MIT
+---
+
+# Silent Failure Hunter — `/dev silent-failure-hunter`
+
+> **Agent:** Rita (QA Engineer) | **Framework:** Defensive error handling, fail-loud discipline
+
+Every catch block is a decision about who finds out when something breaks.
+Too many of them decide that nobody does: the exception is caught and
+dropped, the failed call returns an empty list, the timeout is swallowed
+and the caller carries on with half the data. This lens assumes the worst
+about each one and asks a single question of it — when this path fails at
+runtime, who learns, and how?
+
+## Hunt Targets
+
+| # | Class | What to flag |
+|---|-------|--------------|
+| 1 | Swallowed errors | `catch {}`, `except: pass`, an error coerced to `null`/`[]`/`0` with no log and no re-raise |
+| 2 | Inadequate logging | logged at the wrong severity, logged without the context to diagnose it, log-and-continue where the caller needed to know |
+| 3 | Masking fallbacks | a default that hides a real failure — `.catch(() => [])`, `?? {}` over a failed fetch — so the bug surfaces three layers downstream instead of here |
+| 4 | Broken propagation | a lost stack trace, a generic re-raise that drops the cause, an `async` path with no `await` on the error, a promise with no rejection handler |
+| 5 | Unguarded boundaries | a network/file/db call with no timeout and no error handling; transactional work with no rollback on the failure path |
+
+## Process
+
+1. Grep the diff (or the named area) for the target patterns — `catch`, `except`, `.catch(`, `try`, `?? `, bare `return null`.
+2. For each hit, answer one question: **if this path fails at runtime, who finds out, and how?** If the answer is "nobody" or "a confused engineer three files away", it is a finding.
+3. Trace the caller once — a swallowed error is only safe if the caller genuinely does not need to know, and that is rare.
+4. Rank by blast radius: a masked failure on a payment or data-write path is critical; a swallowed log flush is minor.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- an empty catch on any I/O, network, or database call → critical; name what fails silently
+- `.catch(() => <default>)` or `except: pass` on a data-fetch path → the downstream bug this plants is worse than the crash it prevents
+- a re-raise that drops the original exception (`raise NewError()` with no `from`) → the stack trace the on-call engineer needs is gone
+
+## Output
+
+```markdown
+## Silent Failure Report
+
+**Scope:** {files / diff reviewed}
+**Findings:** {n} ({c} critical, {h} high, {m} medium)
+
+### {SEVERITY} — {file}:{line}
+- **Hides:** {the concrete runtime failure that goes unseen}
+- **Impact:** {who is affected and how far downstream the real bug surfaces}
+- **Fix:** {the specific change — log with context, re-raise with cause, add the timeout}
+
+### Clean
+{paths checked that handle failure honestly — say so, briefly}
+```

package/departments/dev/skills/type-design-analyzer/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: dev/type-design-analyzer
+description: >
+  Scores whether a module's types make illegal states unrepresentable —
+  across encapsulation, invariant expression, invariant usefulness, and
+  type-system enforcement — and names the concrete bug each weak type
+  lets through. TRIGGER: "/dev type-design-analyzer", "type design",
+  "illegal states", "make invalid states unrepresentable", "domain
+  modelling review", "revê o design dos tipos", "estes tipos estão bem
+  desenhados?"; run on the public types of a module or a domain model.
+  SKIP: general code review -> dev/code-review wins; the data-model
+  schema of a new feature -> dev/db-design or dev/ddd-model wins.
+allowed-tools: [Read, Grep, Glob]
+metadata:
+  origin: ecc-derived
+  source: https://github.com/affaan-m/ecc
+  license: MIT
+---
+
+# Type Design Analyzer — `/dev type-design-analyzer`
+
+> **Agent:** Gabriel (Software Architect) | **Framework:** Make-illegal-states-unrepresentable, type-driven design
+
+The strongest bug fix is the one that makes the bug impossible to write.
+A type that admits only valid values turns a whole class of runtime error
+into a compile error nobody can ship past. This lens reads the shape of a
+module's data — its enums, its models, its bounded fields — and asks what
+invalid state that shape still permits, because every permitted invalid
+state is a bug waiting for the caller who constructs it.
+
+## Evaluation Criteria
+
+For each type in scope, score four dimensions and justify each score
+with the specific state it does or does not prevent.
+
+| Dimension | The question |
+|-----------|--------------|
+| **Encapsulation** | Are internals hidden? Can an invariant be violated from outside — a public field mutated past a bound, a list appended to past its cap? |
+| **Invariant expression** | Do the types encode the business rule? Is an impossible state (a shipped order with no address, a negative price) representable at all? |
+| **Invariant usefulness** | Do these invariants prevent *real* bugs in this domain, or are they ceremony that constrains nothing anyone would get wrong? |
+| **Enforcement** | Is the invariant enforced by the type system, or by a convention with an easy escape hatch (a raw `str` where an enum belongs, an `Optional` that is never `None` in practice but the checker cannot know)? |
+
+## Process
+
+1. Grep the module for its public types — dataclasses, Pydantic models, enums, TypedDicts, the domain nouns.
+2. For each, ask the one diagnostic question: **what invalid value can I construct with this type that the domain forbids?** Every answer is a design gap.
+3. Prefer the fix that moves the check to construction time — a validator, a narrower type, a smart constructor — over a runtime guard the caller must remember.
+
+## Proactive Triggers
+
+Surface these WITHOUT being asked:
+
+- a domain value carried as a bare `str`/`int` where an enum or a bounded newtype belongs → the illegal value it now admits
+- an `Optional`/nullable field that is never legitimately empty → make it required and delete the downstream `None` checks
+- a boolean pair that encodes a state machine (`is_draft` + `is_published` both settable true) → the impossible state it allows; replace with one enum
+
+## Output
+
+```markdown
+## Type Design Report
+
+**Scope:** {module / types reviewed}
+
+### {type name} — {file}:{line}
+| Dimension | Score /5 | Why |
+|-----------|---------|-----|
+| Encapsulation | {n} | {the state it lets outside code violate, or "hidden"} |
+| Invariant expression | {n} | {the impossible state it does/does not prevent} |
+| Invariant usefulness | {n} | {real bug prevented, or ceremony} |
+| Enforcement | {n} | {type-enforced, or the escape hatch} |
+
+**Overall:** {one line} · **Fix:** {the narrower type / validator / smart constructor}
+```

package/installer/cli.js

@@ -68,6 +68,7 @@ Usage:
   npx arkaos models set <role> <provider>/<model>  Re-route a role
   npx arkaos mcp start        Start the arka-tools MCP server (stdio; --write enables writes)
   npx arkaos update --skills <curated|full>  Choose the deployed skill set (default: curated on fresh installs)
+  npx arkaos shield           Scan the harness config for vulnerabilities (--json)
   npx arkaos doctor           Run health checks
   npx arkaos uninstall        Remove ArkaOS
 
@@ -90,6 +91,8 @@ Examples:
   npx arkaos index                     Index knowledge base (Obsidian vault)
   npx arkaos search "query"            Search indexed knowledge
   npx arkaos doctor                     Verify installation health
+  npx arkaos shield                     Scan the harness config (exit 2 = critical)
+  npx arkaos shield --json              Machine-readable, for CI
 `);
   process.exit(0);
 }
@@ -208,6 +211,27 @@ async function main() {
       break;
     }
 
+    case "shield": {
+      // The harness config as attack surface. Exit code is the contract
+      // CI gates on (0 = A/B, 1 = C/D, 2 = F or any CRITICAL), so the
+      // child's code is propagated verbatim rather than collapsed to 1.
+      const { spawnSync } = await import("node:child_process");
+      const repoRootShield = join(__dirname, "..");
+      const pyShield = getArkaosPython();
+      if (!pyShield) { console.error("No Python found. Run: npx arkaos install"); process.exit(1); }
+      const shieldArgs = process.argv.slice(3);
+      const shieldRun = spawnSync(
+        pyShield,
+        ["-m", "core.governance.harness_scanner_cli", ...shieldArgs],
+        {
+          stdio: "inherit",
+          cwd: process.cwd(),
+          env: { ...process.env, ARKAOS_ROOT: repoRootShield, PYTHONPATH: repoRootShield },
+        }
+      );
+      process.exit(shieldRun.status === null ? 1 : shieldRun.status);
+    }
+
     case "index": {
       const { execFileSync } = await import("node:child_process");
       const repoRoot = join(__dirname, "..");

package/installer/doctor.js

@@ -531,5 +531,51 @@ export async function doctor(options = {}) {
   }
 
   console.log(`\n  Results: ${passed} passed, ${warned} warnings, ${failed} failures\n`);
+  await securityAdvisory();
   if (failed > 0) process.exit(1);
 }
+
+// Doctor answers "is the install healthy?". It never answered "is the
+// install SAFE?" — a config can be perfectly healthy and still hand a
+// third party the right to run code on this machine. The scanner does
+// that, and doctor is where the operator already looks.
+//
+// Advisory only: it prints the grade and never changes doctor's exit
+// code. A health check that starts failing on a pre-existing security
+// posture would be a breaking change to everyone's CI, and the way to
+// get a security tool ignored is to make it block on day one.
+async function securityAdvisory() {
+  const python = getArkaosPython();
+  const repoRoot = getRepoRoot();
+  if (!python || !repoRoot) return;
+  const { spawnSync } = await import("node:child_process");
+  const run = spawnSync(
+    python,
+    ["-m", "core.governance.harness_scanner_cli", "--json"],
+    {
+      encoding: "utf-8",
+      cwd: process.cwd(),
+      env: { ...process.env, ARKAOS_ROOT: repoRoot, PYTHONPATH: repoRoot },
+    }
+  );
+  // A crash must not read as "clean". If the scanner did not return a
+  // parseable report, say so — the same crash-is-not-clean rule the
+  // scanner enforces internally.
+  let report = null;
+  if (run.status !== null && run.stdout) {
+    try { report = JSON.parse(run.stdout); } catch { report = null; }
+  }
+  if (!report || !Array.isArray(report.findings)) {
+    console.log("  Security: scan did not complete — run `npx arkaos shield` directly\n");
+    return;
+  }
+
+  const cross = process.stdout.isTTY ? "\x1b[31m✗\x1b[0m" : "x";
+  const n = report.findings.length;
+  const plural = n === 1 ? "finding" : "findings";
+  console.log(`  Security: grade ${report.grade} (${report.score}/100), ${n} ${plural}`);
+  for (const finding of report.findings.filter((f) => f.severity === "critical").slice(0, 3)) {
+    console.log(`     ${cross} ${finding.rule} — ${finding.where}`);
+  }
+  console.log(n > 0 ? "     Run: npx arkaos shield\n" : "");
+}