session-orchestrator 3.16.0

package/skills/reconcile/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: reconcile
+user-invocable: true
+tags: [learning, rules, intelligence, meta]
+model: sonnet
+model-preference: sonnet
+model-preference-codex: gpt-5.4-mini
+model-preference-cursor: claude-sonnet-4-6
+args-schema:
+  - flag: --dry-run
+    description: "Print proposals without writing anything or rendering the approval AUQ"
+description: >
+  Use this skill when the user wants to reconcile learnings into rules, run /reconcile, propose
+  rules from learnings, turn learnings into .claude/rules/ entries, or review what rules would be
+  generated from current session learnings. On-demand version of session-end Phase 3.6.8.
+---
+
+> **Platform Note:** State files use the platform's native directory: `.claude/` (Claude Code), `.codex/` (Codex CLI), or `.cursor/` (Cursor IDE). Shared metrics live in `.orchestrator/metrics/`. See `skills/_shared/platform-tools.md`.
+
+# Reconcile Skill
+
+On-demand version of the session-end Phase 3.6.8 reconciliation flow. Turns eligible learnings
+from `.orchestrator/metrics/learnings.jsonl` into proposed `.claude/rules/<slug>.md` entries,
+presenting each batch of 4 to the coordinator via AUQ multiSelect for operator approval before
+any file is written. Advisory-only — rules are NEVER auto-applied.
+
+## Posture Contract (load-bearing — read before executing)
+
+- **Advisory-only.** No rule is ever written without explicit operator approval via AUQ.
+  The AUQ multiSelect is the mandatory gate; there is no bypass.
+- **Never-always-on invariant.** The reconcile engine's emitter (`emitter.mjs`) throws
+  on any eligible learning that would produce an `alwaysApply: true` rule — the engine
+  structurally cannot emit always-on rules. This invariant is enforced upstream, not by
+  this skill.
+- **Engine never writes `.claude/rules/`.** `runReconcile` computes proposals and records
+  them in the idempotency sidecar only. The only module that writes `.claude/rules/` is
+  `writer.mjs`, and only AFTER the operator approves proposals via AUQ.
+- **Same pipeline as session-end Phase 3.6.8.** This skill uses the identical engine and
+  writer seams as the automatic session-end reconciliation phase — operator experience is
+  consistent, and any fixes to the engine benefit both paths.
+- **`reconcile.enabled` gates the AUTOMATIC session-end phase only.** `/reconcile` is an
+  on-demand command and runs regardless of `reconcile.enabled`. It still honours
+  `rule-expiry-days` and `confidence-floor` from the `reconcile` config block.
+
+---
+
+## Phase 0: Bootstrap Gate
+
+Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is CLOSED,
+invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate
+is OPEN, continue to Phase 1.
+
+<HARD-GATE>
+Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to
+`skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints.
+</HARD-GATE>
+
+---
+
+## Phase 1: Config & Argument Loading
+
+### 1.1 Read Session Config
+
+Read and parse Session Config per `skills/_shared/config-reading.md`. Store result as `$CONFIG`.
+
+### 1.2 Extract Reconcile Config
+
+Extract the `reconcile` block from `$CONFIG`:
+
+```bash
+# rule-expiry-days defaults to EMPTY (not a number) so the engine falls back to
+# its per-type TTL (deriveExpiresAt, default 60d). A numeric override forces flat
+# N-day expiry — matching the `null` default of the reconcile: config resolver.
+RULE_EXPIRY_DAYS=$(echo "$CONFIG" | jq -r '.reconcile["rule-expiry-days"] // empty')
+CONFIDENCE_FLOOR=$(echo "$CONFIG" | jq -r '.reconcile["confidence-floor"] // 0.5')
+RECONCILE_MODE=$(echo "$CONFIG"   | jq -r '.reconcile.mode // "warn"')
+MIN_RULE_DAYS=$(echo "$CONFIG"    | jq -r '.reconcile["min-rule-days"] // 7')
+MIN_INSIGHT_CHARS=$(echo "$CONFIG" | jq -r '.reconcile["min-insight-chars"] // 24')
+```
+
+When `RULE_EXPIRY_DAYS` is empty, pass `ruleExpiryDays: undefined` to `runReconcile` so the engine uses its per-type TTL. Defaults when the `reconcile` block is absent or a field is missing:
+- `rule-expiry-days`: empty → per-type TTL (`deriveExpiresAt`, default 60d). Preserves FA2 behaviour; matches the `null` resolver default.
+- `confidence-floor`: 0.5
+- `mode`: warn (enum `off` | `warn`)
+- `min-rule-days`: 7 — floor window (days) applied to a proposed rule's `expires-at` so a
+  near-dead or already-elapsed natural expiry never produces a born-dead rule (issue #741.1).
+- `min-insight-chars`: 24 — opt-in minimum insight length gating the eligibility
+  placeholder-insight check (issue #741.2).
+
+Note: `reconcile.enabled` is intentionally NOT checked — this on-demand command always runs.
+
+### 1.3 Parse Arguments
+
+Check `$ARGUMENTS` for `--dry-run`:
+
+```bash
+DRY_RUN=false
+if echo "$ARGUMENTS" | grep -q -- '--dry-run'; then
+  DRY_RUN=true
+fi
+```
+
+---
+
+## Phase 2: Run the Reconciliation Engine
+
+### 2.1 Resolve Plugin Root
+
+Resolve `$PLUGIN_ROOT` per `skills/_shared/config-reading.md` (the standard resolution chain:
+`$CLAUDE_PLUGIN_ROOT` → `$CODEX_PLUGIN_ROOT` → `$CURSOR_RULES_DIR` → common install locations).
+
+### 2.2 Invoke `runReconcile`
+
+```javascript
+import { runReconcile } from '$PLUGIN_ROOT/scripts/lib/reconcile/engine.mjs';
+
+const { proposals, rejected, summary, error } = await runReconcile({
+  repoRoot,             // absolute path from git rev-parse --show-toplevel
+  ruleExpiryDays: RULE_EXPIRY_DAYS,   // empty → undefined → engine per-type TTL
+  minRuleDays: MIN_RULE_DAYS,         // default 7 — floors a near-dead expires-at
+  minInsightChars: MIN_INSIGHT_CHARS, // default 24 — opt-in placeholder-insight length gate
+  now: new Date(),
+  dryRun: DRY_RUN,     // true → engine touches no disk (no idempotency sidecar write)
+});
+
+// The engine does NOT apply a confidence floor — it proposes every eligible
+// learning and carries each one's `confidence` through. `confidence-floor` is a
+// DELIVERY gate: filter proposals here before the sidecar + AUQ (mirrors
+// session-end Phase 3.6.8). Use `surfaced` everywhere "proposals" appears below.
+const surfaced = proposals.filter((p) => typeof p.confidence === 'number' && p.confidence >= CONFIDENCE_FLOOR);
+```
+
+`runReconcile` NEVER throws — a top-level error populates `result.error` instead.
+
+If `error` is present, surface it to the user and abort:
+> "Reconcile engine error: `<error>`. Check `.orchestrator/metrics/learnings.jsonl` and retry."
+
+### 2.3 Handle Empty / Zero-Proposal Cases
+
+If `summary.totalLearnings === 0`:
+> "No learnings found in `.orchestrator/metrics/learnings.jsonl`. Run `/evolve analyze` first to extract session patterns."
+Exit cleanly.
+
+If `summary.eligible === 0` (learnings exist but none are eligible — already proposed,
+or wrong learning type — eligibility is type/`file_paths`-based, NOT confidence-based):
+> "No eligible learnings for rule proposals (total: `summary.totalLearnings`, already proposed or ineligible type: all). Run more sessions to accumulate evidence."
+Exit cleanly. Optionally list the rejection reasons from `rejected[]` (field `reason`) as an
+informational table.
+
+If `summary.eligible > 0` but `surfaced.length === 0` (proposals exist but ALL fall below
+`confidence-floor`):
+> "No proposals above the confidence floor (`CONFIDENCE_FLOOR`). Lower `reconcile.confidence-floor` or run more sessions so the underlying learnings accrue confidence."
+Exit cleanly.
+
+If `summary.proposed === 0` but `summary.eligible > 0` (emit/render failures consumed all
+candidates — unusual):
+> "Engine produced 0 proposals from N eligible learnings. See rejection log."
+List `rejected[].reason` and exit.
+
+---
+
+## Phase 3: Dry-Run Branch
+
+**Only when `DRY_RUN=true`.**
+
+Print the proposals in a readable table. Do NOT write the sidecar, do NOT render an AUQ.
+
+```
+## Reconcile — Dry Run  (N proposals, M rejected)
+
+| # | Slug | Confidence | Learning Key | Rule Path |
+|---|------|-----------|-------------|-----------|
+| 1 | <slug> | 0.72 | <learningKey> | .claude/rules/<slug>.md |
+| 2 | ...   | ...  | ...          | ...                     |
+
+Rejected (not eligible for proposal):
+| Learning Key | Reason |
+|-------------|--------|
+| <key> | <reason> |
+
+Re-run without --dry-run to enter the approval flow.
+```
+
+Exit after printing. Do not proceed to Phase 4.
+
+---
+
+## Phase 4: Write Pending Sidecar (Normal Mode Only)
+
+Write the proposals to `.orchestrator/metrics/reconcile-pending.md` as a human-readable
+record before presenting the AUQ. This sidecar is informational only — it lets the operator
+see the full proposal set in an editor alongside the AUQ prompt.
+
+```markdown
+# Reconcile Pending — <ISO date>
+
+Generated by `/reconcile` on <timestamp>. N proposals, M rejected.
+
+## Proposals
+
+| # | Slug | Confidence | Learning Key | Rendered Rule Path |
+|---|------|-----------|-------------|-------------------|
+| 1 | <slug> | 0.72 | <key> | .claude/rules/<slug>.md |
+...
+
+## Rejected
+
+| Learning Key | Type | Reason |
+|-------------|------|--------|
+| <key> | <type> | <reason> |
+...
+```
+
+Write via standard file write (not atomic, not lock-protected — this is a disposable sidecar,
+not a critical artifact).
+
+---
+
+## Phase 5: AUQ Approval Flow (Normal Mode Only)
+
+Present proposals to the operator in batches of 4. Mirror the session-end Phase 3.6.3 / 3.6.8
+multiSelect pattern exactly.
+
+For each batch (proposals sliced into groups of 4):
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Which rule proposals should be written to .claude/rules/?  (batch K of N)",
+    header: "Reconcile — Approve Rule Proposals",
+    options: [
+      {
+        label: "<slug>.md (confidence: 0.72)",
+        description: "Learning: <learningKey> | Path: .claude/rules/<slug>.md | <first 100 chars of rendered content>"
+      },
+      ...up to 4 options per batch...
+      {
+        label: "Skip all in this batch",
+        description: "Decline all proposals in this batch — they are archived to the rejected log."
+      }
+    ],
+    multiSelect: true
+  }]
+})
+```
+
+Collect responses across all batches:
+- Selected options (excluding "Skip all") → `approved[]`
+- Unselected options + "Skip all" batches → `rejected_by_operator[]`
+
+> **Codex CLI fallback:** AskUserQuestion is unavailable in subagents and on Codex CLI
+> (AUQ-004). In those contexts, present proposals as a numbered Markdown list and ask
+> the operator to reply with the numbers they wish to approve.
+
+---
+
+## Phase 6: Write Approved Rules
+
+### 6.1 Invoke `writeApprovedRules`
+
+```javascript
+import { writeApprovedRules } from '$PLUGIN_ROOT/scripts/lib/reconcile/writer.mjs';
+
+const { written, archived, errors } = await writeApprovedRules({
+  approved: approved,             // proposals the operator approved
+  rejected: rejected_by_operator, // proposals the operator declined
+  repoRoot,
+  sessionId: currentSessionId,    // informational; from STATE.md or 'manual'
+});
+```
+
+`writeApprovedRules` NEVER throws — per-item failures are collected in `errors[]`.
+
+### 6.2 Handle Errors
+
+If `errors.length > 0`, surface each error to the operator:
+> "Warning: `N` rule(s) failed to write: `<error list>`. Successfully written: `written`. Archived: `archived`."
+
+Log each error but do NOT abort — partial success is acceptable.
+
+### 6.3 Report
+
+```
+## Reconcile Complete
+
+- Written:  <written> rule file(s) to .claude/rules/
+- Archived: <archived> declined proposal(s) to .orchestrator/reconcile.rejected.log
+- Errors:   <errors.length> (see warnings above, if any)
+
+New rules take effect immediately — they are loaded by the wave-executor's rule-loader
+on the next wave dispatch.
+```
+
+If `written === 0` and `approved.length === 0`:
+> "No proposals approved. No rules written."
+
+---
+
+## Critical Rules
+
+- **NEVER** call `writeApprovedRules` before the operator has confirmed via AUQ — this is the
+  only write-protection gate for `.claude/rules/`.
+- **NEVER** pass `dryRun: false` to `runReconcile` and then skip the AUQ — the idempotency
+  sidecar is written during the engine run; writing rules without AUQ confirmation would create
+  an inconsistency between the sidecar and the actual rule files.
+- **ALWAYS** surface `errors[]` from `writeApprovedRules` — per-item isolation must not
+  silently swallow failures.
+- **ALWAYS** present proposals in batches of ≤4 via AUQ multiSelect — mirrors session-end
+  3.6.3 / 3.6.8 and keeps the operator prompt readable.
+- **ALWAYS** honour `confidence-floor`, `rule-expiry-days`, `min-rule-days`, and
+  `min-insight-chars` from Session Config `reconcile` block — the engine reads these, but
+  the skill must pass them explicitly.
+
+## Anti-Patterns
+
+- **DO NOT** write any file to `.claude/rules/` without AUQ operator confirmation.
+- **DO NOT** check `reconcile.enabled` — that flag gates the automatic session-end phase, not
+  this on-demand command.
+- **DO NOT** emit or approve a rule with `alwaysApply: true` — the engine structurally prevents
+  it, but the reviewer should reject any proposal that would produce an always-on rule.
+- **DO NOT** skip the dry-run branch when `--dry-run` is passed — the entire AUQ + write flow
+  must be bypassed.
+- **DO NOT** treat `runReconcile` failures as fatal — check the `error` field and surface it,
+  then exit cleanly.

package/skills/repo-audit/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: repo-audit
+description: Use this skill when the user wants to audit a repository for baseline compliance, check code quality, security posture, CI/CD setup, testing, documentation, and ecosystem configuration. Runs 9 checklist categories and emits a Markdown report plus JSON sidecar at .orchestrator/metrics/repo-audit-<timestamp>.json. <example>Context: User is in a project repo and wants a baseline compliance check. user: "/repo-audit" assistant: "Running repo-audit across 9 categories — Configuration, Code Quality, Git Hygiene, CI/CD, Testing, Security, Documentation, Clank Integration (optional), and MCP Configuration. Will produce a Markdown checklist report and JSON sidecar." <commentary>The user wants a compliance check; this skill is appropriate because it runs all 9 categories with pass/fail/warn/skipped statuses and writes structured output.</commentary></example>
+model: inherit
+color: cyan
+---
+
+# Repo Audit Skill
+
+Perform a comprehensive audit of the host repository against the ecosystem baseline. Emits a structured Markdown checklist report and a JSON sidecar for trend tracking.
+
+## Purpose
+
+Answer the question: "Does this repo match the ecosystem baseline?" — a compliance-focused, checkable question with a fixed 9-category checklist. Distinct from `/discovery` (broad quality probes) and `/harness-audit` (plugin installation health).
+
+## Phase 1: Read Session Config
+
+Read the project's `## Session Config` section in `CLAUDE.md` (or `AGENTS.md` for Codex CLI). Store resolved values as `$CONFIG`.
+
+**Command resolution follows `skills/quality-gates/SKILL.md` priority order:**
+1. `.orchestrator/policy/quality-gates.json` — canonical policy file (if present).
+2. Session Config `test-command` / `typecheck-command` / `lint-command` — fallback.
+3. Hardcoded defaults: `npm test`, `npm run typecheck`, `npm run lint`.
+
+If any command is set to the literal string `skip`, skip that check entirely and mark it `skipped`.
+
+## Phase 2: Clank Detection
+
+Check for Clank integration markers:
+```bash
+ls .clank/ 2>/dev/null || ls clank.config.* 2>/dev/null || ls clank.config.json 2>/dev/null
+```
+
+Set `$CLANK_DETECTED=true` if any marker exists, `false` otherwise.
+
+Also check Session Config for `ecosystem: baseline` — if set, treat Clank checks as required rather than optional.
+
+## Phase 3: Run 9 Audit Categories
+
+Run all checks in parallel where possible. For each check use the status symbols:
+- `✓` — passes
+- `✗` — fails (action required)
+- `⚠` — warning (review recommended)
+- `skipped` — intentionally skipped
+
+### Category 1: Configuration
+
+| Check | Method |
+|---|---|
+| `CLAUDE.md` exists (50-100 lines, lean) | `wc -l CLAUDE.md` |
+| `.claude/rules/` has path-scoped rules | `ls .claude/rules/*.md 2>/dev/null` |
+| `.claude/settings.json` exists | `ls .claude/settings.json` |
+| `.mcp.json` exists with servers | `ls .mcp.json` |
+| `.gitignore` covers `.env*`, `node_modules`, build artifacts | `grep -E '\.env\*|node_modules' .gitignore` |
+
+### Category 2: Code Quality
+
+Commands resolved from Session Config per Phase 1.
+
+| Check | Method |
+|---|---|
+| ESLint v9 flat config (`eslint.config.mjs`) | `ls eslint.config.mjs 2>/dev/null` |
+| Prettier config (`.prettierrc` or `prettier.config.*`) | `ls .prettierrc* prettier.config.* 2>/dev/null` |
+| TypeScript strict mode (`"strict": true` in tsconfig.json) | `grep '"strict": true' tsconfig.json` |
+| 0 TypeScript errors | Run `{typecheck-command} 2>&1` — pass if exit code 0 |
+| No `console.log` in production code (excluding tests) | `grep -r 'console\.log' --include='*.ts' --include='*.mts' --exclude-dir=tests --exclude-dir=node_modules . 2>/dev/null | grep -v '\.test\.'` |
+| Lint passes | Run `{lint-command} 2>&1` — pass if exit code 0 |
+
+### Category 3: Git Hygiene
+
+| Check | Method |
+|---|---|
+| Husky + lint-staged configured | `ls .husky/ 2>/dev/null && grep 'lint-staged' package.json` |
+| commitlint (Conventional Commits) | `ls commitlint.config.* 2>/dev/null || grep 'commitlint' package.json` |
+| Gitleaks pre-commit or CI | `ls .gitleaks.toml 2>/dev/null || grep 'gitleaks' .husky/pre-commit 2>/dev/null` |
+| No secrets in git history | `git log --all -p 2>/dev/null | grep -i 'password\|secret\|api_key\|token' | head -1` — warn if any found |
+
+### Category 4: CI/CD
+
+| Check | Method |
+|---|---|
+| CI config exists (`.gitlab-ci.yml` or `.github/workflows/`) | `ls .gitlab-ci.yml 2>/dev/null \|\| ls .github/workflows/*.yml 2>/dev/null` |
+| Stages include validate → security → test → deploy | Read CI config, check for these stage names |
+| Typecheck in CI | `grep -E 'tsgo|typecheck' .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null` |
+| Tests in CI | `grep -E 'vitest|npm test|pnpm test' .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null` |
+| Dependency audit in CI | `grep -E 'audit|pnpm audit' .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null` |
+
+### Category 5: Testing
+
+| Check | Method |
+|---|---|
+| Vitest configured (`vitest.config.ts` or `vitest.config.mjs`) | `ls vitest.config.* 2>/dev/null` |
+| Test coverage configured | `grep 'coverage' vitest.config.* 2>/dev/null` |
+| E2E tests (Playwright) for frontend repos | `ls playwright.config.* 2>/dev/null` — only required if `next.config.*` or `nuxt.config.*` exists |
+| Test scripts in `package.json` | `grep '"test"' package.json 2>/dev/null` |
+| Tests pass | Run `{test-command} 2>&1` — pass if exit code 0 |
+
+### Category 6: Security
+
+| Check | Method |
+|---|---|
+| Auth-at-boundary pattern (`requireAuth`) | `grep -r 'requireAuth' --include='*.ts' src/ 2>/dev/null \|\| echo "N/A (no src/)"` |
+| Zod validation on inputs | `grep -r 'z\.object\|z\.string\|z\.parse\|safeParse' --include='*.ts' src/ 2>/dev/null \|\| echo "N/A"` |
+| No hardcoded secrets (scan for API key patterns) | `grep -r 'sk-\|api_key\s*=\s*"' --include='*.ts' --include='*.mts' --exclude-dir=node_modules . 2>/dev/null` — warn if found |
+| No PAT/token in settings-allowlist entries (`.claude/settings.json`, `.claude/settings.local.json` — on-disk, incl. untracked) | `grep -nEo 'glpat-[A-Za-z0-9_-]{20,}\|ghp_[A-Za-z0-9]{36,}\|github_pat_[A-Za-z0-9_]{22,}\|sk-ant-[A-Za-z0-9_-]{20,}\|AKIA[0-9A-Z]{16}' .claude/settings.json .claude/settings.local.json 2>/dev/null \| grep -vE 'AKIAIOSFODNN7EXAMPLE\|-PLACEHOLDER'` — **fail** if any match (hard — unlike the `sk-` heuristic above, these 5 prefixes are high-signal; see SEC-021 in `.claude/rules/security.md`). This check is required because `check-owner-leakage.mjs` scans `git ls-files` only — `settings.local.json` is gitignored/untracked by convention and structurally invisible to it. |
+| `.env*` files not tracked | `git ls-files | grep '\.env'` — fail if any `.env` (not `.env.example`) tracked |
+| `.env.example` documents all secrets | `ls .env.example 2>/dev/null` |
+
+Note: RLS, rate limiting, and CORS checks are `⚠ review` items — they require human judgment and cannot be fully automated. Flag them as `⚠ manual-review-recommended`.
+
+### Category 7: Documentation
+
+| Check | Method |
+|---|---|
+| `README.md` exists | `ls README.md 2>/dev/null` |
+| `.env.example` exists with documented vars | `ls .env.example 2>/dev/null` |
+| Architecture documented in `CLAUDE.md` | `grep -i 'architecture\|structure\|stack' CLAUDE.md 2>/dev/null` |
+
+### Category 8: Clank Integration (Optional)
+
+**If `$CLANK_DETECTED=false` AND `ecosystem: baseline` is NOT set in Session Config:**
+
+```
+### 8. Clank Integration
+Status: skipped — Clank not detected (.clank/ and clank.config.* absent; ecosystem: baseline not set)
+```
+
+Do not mark any Clank check as `✗`. Absence of Clank is not a failure outside the baseline ecosystem.
+
+**If `$CLANK_DETECTED=true` OR `ecosystem: baseline` is set:**
+
+| Check | Method |
+|---|---|
+| `GET /health` endpoint exists (for services) | `grep -r '/health' --include='*.ts' src/ 2>/dev/null` |
+| CI pipeline sends webhooks to Event Bus | `grep -E 'webhook\|event.bus\|clank' .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null` |
+| Sentry configured (for user-facing apps) | `grep -r 'Sentry' --include='*.ts' --include='*.mts' --exclude-dir=node_modules . 2>/dev/null` |
+| Conventional Commits enforced (commitlint) | `ls commitlint.config.* 2>/dev/null || grep 'commitlint' package.json 2>/dev/null` |
+
+### Category 9: MCP Configuration
+
+**Scope:** Audits only the repo-local `.mcp.json` file — does NOT cover the user-machine MCPJungle gateway or globally-imported MCP servers.
+
+| Check | Method |
+|---|---|
+| `.mcp.json` exists | `ls .mcp.json 2>/dev/null` |
+| MCP servers match project type | Read `.mcp.json`, verify server list is appropriate (e.g., `shadcn` only for frontend repos, no stale servers) |
+| No stale or unused MCP entries | Cross-reference `.mcp.json` servers against project stack markers |
+| MCP server health probe (optional — requires `mcporter`) | For each server declared in repo-local `.mcp.json`: if `command -v mcporter` is present, run `mcporter list --json` and read the per-server `status` field — `ok` → ✓ pass; `auth` → ⚠ warn (remediation: `mcporter auth <server>`); `offline`/`error` → ✗ fail. If `mcporter` is absent → mark this check `skipped` with note "enable with `npm install -g mcporter`". `mcporter` is never a hard dependency; the repo audit proceeds without it. |
+
+## Phase 4: Emit Report
+
+### 4.1 Markdown Report (stdout)
+
+Emit a structured report in this format:
+
+```markdown
+# Repo Audit Report — <repo-name>
+Generated: <ISO timestamp>
+Session Config commands: test=`<test-command>` typecheck=`<typecheck-command>` lint=`<lint-command>`
+
+## Summary
+| Category | Pass | Fail | Warn | Skipped |
+|---|---|---|---|---|
+| 1. Configuration | N | N | N | N |
+| 2. Code Quality | N | N | N | N |
+| 3. Git Hygiene | N | N | N | N |
+| 4. CI/CD | N | N | N | N |
+| 5. Testing | N | N | N | N |
+| 6. Security | N | N | N | N |
+| 7. Documentation | N | N | N | N |
+| 8. Clank Integration | N | N | N | N |
+| 9. MCP Configuration | N | N | N | N |
+| **Total** | N | N | N | N |
+
+**Overall:** ✓ PASS / ✗ FAIL / ⚠ WARN
+
+## Detailed Results
+
+### 1. Configuration
+- ✓ CLAUDE.md exists (72 lines — within 50-100 range)
+- ✗ `.claude/settings.json` missing — create with permissions and hooks
+- ⚠ `.mcp.json` missing — add MCP servers appropriate for your stack
+...
+
+### 2. Code Quality
+...
+
+### 8. Clank Integration
+skipped — Clank not detected (.clank/ and clank.config.* absent; ecosystem: baseline not set in Session Config)
+
+### 9. MCP Configuration
+- ✓ `.mcp.json` exists
+- ✓ Servers match project type
+- ⚠ MCP server health probe: `github` → ok; `shadcn` → auth (run `mcporter auth shadcn`)
+
+## Critical Findings
+<List only ✗ items — actionable, with fix guidance>
+
+## Action Items
+<Numbered list of recommended fixes, ordered by priority>
+```
+
+### 4.2 JSON Sidecar
+
+Write to `.orchestrator/metrics/repo-audit-<unix-timestamp>.json`:
+
+```json
+{
+  "schema_version": 1,
+  "generated_at": "<ISO timestamp>",
+  "repo": "<basename of cwd>",
+  "commands": {
+    "test": "<resolved test-command>",
+    "typecheck": "<resolved typecheck-command>",
+    "lint": "<resolved lint-command>"
+  },
+  "clank_detected": false,
+  "ecosystem_baseline": false,
+  "categories": {
+    "configuration": { "pass": 4, "fail": 1, "warn": 0, "skipped": 0, "checks": [] },
+    "code_quality": { "pass": 3, "fail": 1, "warn": 1, "skipped": 0, "checks": [] },
+    "git_hygiene": { "pass": 2, "fail": 1, "warn": 0, "skipped": 0, "checks": [] },
+    "ci_cd": { "pass": 0, "fail": 5, "warn": 0, "skipped": 0, "checks": [] },
+    "testing": { "pass": 4, "fail": 0, "warn": 0, "skipped": 1, "checks": [] },
+    "security": { "pass": 3, "fail": 1, "warn": 2, "skipped": 0, "checks": [] },
+    "documentation": { "pass": 2, "fail": 0, "warn": 1, "skipped": 0, "checks": [] },
+    "clank_integration": { "pass": 0, "fail": 0, "warn": 0, "skipped": 4, "checks": [] },
+    "mcp_configuration": { "pass": 1, "fail": 0, "warn": 2, "skipped": 0, "checks": [] }
+  },
+  "summary": {
+    "total_pass": 0,
+    "total_fail": 0,
+    "total_warn": 0,
+    "total_skipped": 0,
+    "overall": "pass|fail|warn"
+  }
+}
+```
+
+Each `checks` array entry:
+```json
+{ "id": "config.claude-md-exists", "status": "pass|fail|warn|skipped", "detail": "human-readable result" }
+```
+
+MCP server health entries additionally include an optional `remediation` field (representative examples):
+```json
+{ "id": "mcp.server-health-github", "status": "pass", "detail": "mcporter: status=ok", "remediation": null }
+{ "id": "mcp.server-health-shadcn", "status": "warn", "detail": "mcporter: status=auth", "remediation": "mcporter auth shadcn" }
+{ "id": "mcp.server-health-probe", "status": "skipped", "detail": "mcporter not installed — enable with npm install -g mcporter", "remediation": "npm install -g mcporter" }
+```
+
+Create `.orchestrator/metrics/` if it does not exist:
+```bash
+mkdir -p .orchestrator/metrics
+```
+
+Write using `node -e` or direct file write — do not require any external dependency.
+
+## Overall Status Logic
+
+- `✗ FAIL` — any check has status `fail`
+- `⚠ WARN` — no fails, but at least one `warn`
+- `✓ PASS` — all checks are `pass` or `skipped`
+
+## Success Criteria
+
+- All 9 categories checked with pass/fail/warn/skipped status
+- Clank section correctly detected and marked `skipped` when absent
+- Commands resolved from Session Config (not hardcoded `pnpm`)
+- JSON sidecar written to `.orchestrator/metrics/repo-audit-<timestamp>.json`
+- No false positives — verify findings before reporting
+- Critical security findings flagged prominently in "Critical Findings" section