agent-bober 0.15.0 → 0.17.0

package/skills/bober.run/references/lens-panel.md

@@ -0,0 +1,115 @@
+# Lens Panel — Canonical Protocol Reference
+
+This document is the single source of truth for native panel orchestration in agent-bober.
+It embeds the five canonical lens focus fragments verbatim from
+`src/orchestrator/eval-lenses.ts` (the `LENS_CATALOG` literal) and documents the
+split fan-out, majority-vote/fail-closed reconciliation, and the `lensVerdicts` output shape.
+
+---
+
+## Lens Focus Fragments
+
+The following fragments are the exact strings returned by `resolveLensFocus(lens)` for each
+built-in lens. They MUST remain byte-for-byte identical to the corresponding entries in
+`LENS_CATALOG` — the drift gate (`src/orchestrator/lens-panel-parity.test.ts`) enforces this.
+
+### correctness
+
+```
+Focus on whether the implementation actually satisfies each success criterion verbatim. Check that all required behaviours exist, all edge cases are handled, and the contract's definitionOfDone is met.
+```
+
+### security
+
+```
+Focus on injection vulnerabilities, authentication and authorisation gaps, secret handling, unsafe input validation, and any path traversal or privilege escalation risks.
+```
+
+### regression
+
+```
+Focus on whether previously working behaviour still works after the changes. Verify that pre-existing tests pass, that no public API or config interface was broken, and that the sprint diff does not silently remove functionality.
+```
+
+### quality
+
+```
+Focus on principles violations, dead code, misleading naming, smells, duplicated logic, and whether the implementation follows the project's established patterns and conventions.
+```
+
+### simplicity
+
+```
+Focus exclusively on over-engineering in the production code: logic that reinvents the standard library, dependencies or hand-rolled code doing what a native platform feature already provides, abstractions with a single implementation, configuration nobody reads, dead flexibility, and code expressible in materially fewer lines. For each, name the location, what to cut, and what replaces it. Never flag tests, assertion-based self-checks, input validation at trust boundaries, error handling, security measures, or accessibility as deletable — minimalism governs production code, never the verification or safety discipline.
+```
+
+> The `simplicity` lens is the complexity-only counterpart to `quality`. `quality` asks
+> "does this follow our patterns and is it free of smells?"; `simplicity` asks "what can be
+> deleted, replaced by stdlib/native, or shrunk?" — and is forbidden from ever recommending the
+> removal of a test, a validation, or a safety measure. It pairs cleanly with the evaluator's
+> test/verification Iron Law: minimalism governs what is built, never what is verified.
+
+---
+
+## Native Panel Protocol
+
+### Split Fan-out
+
+When the native panel is active, the orchestrator spawns evaluators in two passes:
+
+1. **Deterministic evaluator (one instance):** runs the configured strategy suite exactly once
+   (build, typecheck, lint, unit-test, playwright, api-check, etc.). This produces the
+   deterministic verdict — objective, tool-based checks that do not depend on lens focus.
+
+2. **Qualitative evaluators (one per configured lens):** each evaluator receives the same
+   sprint diff and context but is instructed to judge the contract's success criteria
+   exclusively through its lens focus fragment. The strategy suite is **not** re-run for
+   these evaluators — they perform qualitative assessment only, using the results already
+   collected by the deterministic evaluator as supporting context.
+
+This split ensures strategies execute once (no duplicate CI cost) while each lens evaluates
+the diff independently.
+
+### Reconciliation — Majority Vote, Fail-Closed
+
+The lens verdicts are reconciled by `reconcile()` in
+`src/orchestrator/workflow/reconciler.ts` using the following semantics:
+
+- **Inputs:** the array of per-lens `EvalResult` objects (`lensVerdicts`).
+- **Require non-empty:** an empty array throws `"reconcile: lensVerdicts must be non-empty"`.
+- **Vote count:** `passCount` = number of lenses where `passed === true`;
+  `failCount` = total − passCount.
+- **Verdict:** `passed = passCount > failCount` (strict majority).
+  - **Fail-closed on tie:** when `passCount === failCount` the panel verdict is `false`.
+- **Details:** union of all failing lens details, de-duplicated by `(criterion, message)` key.
+- **Feedback:** failing lenses' feedback joined with `\n`; `"All lenses passed."` when all pass.
+- **Summary:** `"Panel verdict: ${passCount}/${n} lenses passed"`.
+- **Score:** `Math.round((100 * passCount) / n)`.
+- **Evaluator tag:** `evaluator = "panel"`.
+- **Timestamp:** echoed verbatim from the input argument (pure function, ADR-4).
+
+### Combine
+
+The final sprint verdict combines both passes:
+
+```
+final.passed = deterministic.passed && reconciled.passed
+```
+
+Both must pass for the sprint to be accepted.
+
+### lensVerdicts Output Shape
+
+After reconciliation the orchestrator writes a `lensVerdicts` array into the saved
+`EvalResult` JSON and sets `evaluator = "panel"`. The array shape is:
+
+```ts
+lensVerdicts: Array<{
+  lens: string;    // e.g. "correctness", "security", "regression", "quality", "simplicity"
+  passed: boolean; // individual lens verdict
+  summary: string; // per-lens summary from the qualitative evaluator
+}>
+```
+
+This field is optional and backward-compatible: eval results produced before the panel
+feature (or by non-panel evaluators) simply omit it.

package/skills/bober.sprint/SKILL.md

@@ -283,6 +283,15 @@ When done, respond with EXACTLY this JSON structure (no other text):
 
 ## Step 6: Spawn the Evaluator Subagent
 
+**Panel mode (gated, off by default):** Read `config.evaluator.panel`. If `panel.enabled` is `true` AND `panel.lenses.length >= 2`, run the PANEL flow described in the inlined Lens Panel reference below (`<!-- Reference: lens-panel.md -->`):
+- Spawn ONE bober-evaluator with **MODE:deterministic** — runs the configured strategy suite exactly once.
+- Then spawn one bober-evaluator per lens with **MODE:lens:<name>** for each name in `panel.lenses`, bounded by `panel.maxConcurrent` concurrent spawns.
+- Collect each lens verdict; majority-vote: `passed = passCount > failCount`, **FAIL-CLOSED on tie** (tie → false).
+- Set `final.passed = deterministic.passed && reconciled.passed`.
+- Save the eval-result with `evaluator: "panel"` and a `lensVerdicts: [{ lens, passed, summary }]` array.
+
+OTHERWISE (panel disabled, or fewer than 2 lenses), spawn exactly ONE bober-evaluator with **MODE:full** exactly as described below — byte-identical to today's behaviour.
+
 **Use the Agent tool to spawn the evaluator:**
 
 ```
@@ -368,12 +377,44 @@ Respond with EXACTLY this JSON structure (no other text):
    {"event":"sprint-completed","contractId":"...","specId":"...","iteration":N,"timestamp":"..."}
    ```
 
-4. **Check if the plan is now fully complete.** Read the PlanSpec's `sprints` array to get the total count. Count how many of those contracts now have `status: "completed"`. If ALL sprints are completed (N/N):
+4. **Spawn the Documenter subagent — write docs now, while the change is fresh.** The sprint is committed and marked complete; document it per-sprint instead of batching all docs into a final sprint (which goes stale and error-prone). Use the Agent tool:
+
+   ```
+   Agent tool call:
+     description: "Docs for sprint <N>: <sprint title>"
+     subagent_type: bober-documenter
+     mode: auto
+     prompt: <the prompt below>
+   ```
+
+   IMPORTANT: Use `mode: auto` or `mode: bypassPermissions` — the documenter needs write access to create/edit docs and commit them.
+
+   **Documenter prompt:**
+   ```
+   You are the Bober Documenter subagent. Sprint <N> just PASSED evaluation and was marked complete. Write its documentation and update related docs while the change is fresh.
+
+   Read these from disk:
+   - SprintContract: .bober/contracts/<contractId>.json
+   - Generator report: .bober/handoffs/gen-report-<contractId>-<iteration>.json
+   - Eval result: .bober/eval-results/eval-<contractId>-<iteration>.json
+   - .bober/principles.md if it exists
+
+   Then follow your agent instructions: determine what was built from the committed diff, write the sprint record to docs/sprints/<contractId>.md, find & update related existing docs (README, ADRs, CLAUDE.md, module docs) that the change made stale, and commit ONLY the doc files separately. Do NOT modify application code or tests.
+
+   Respond with the JSON structure defined in your agent spec.
+   ```
+
+   **After the Documenter returns:**
+   - Parse its JSON response. Note `sprintDocPath`, `relatedDocsUpdated`, and any `concerns`.
+   - If the documenter crashed or returned an error, do NOT fail the sprint — it already passed. Log `{"event":"sprint-docs-failed","contractId":"...","timestamp":"..."}` and continue. Docs can be regenerated later.
+   - If `concerns` is non-empty, surface them in the success report so the user can decide whether to act.
+
+5. **Check if the plan is now fully complete.** Read the PlanSpec's `sprints` array to get the total count. Count how many of those contracts now have `status: "completed"`. If ALL sprints are completed (N/N):
    - Update the PlanSpec: set `status` to `"completed"` and `completedAt` to current ISO-8601 timestamp. Save to `.bober/specs/<specId>.json`. **The `status` field MUST remain in the first 10 lines of the JSON** so future runs can skip it with a partial read.
    - Update `.bober/progress.md` — change the plan's status line to `completed (N/N sprints)`.
    - Log event: `{"event":"plan-completed","specId":"...","sprintsCompleted":N,"timestamp":"..."}`
 
-5. **Report success to the user:**
+6. **Report success to the user:**
    ```
    === Sprint <N> PASSED on iteration <M> ===
 
@@ -383,6 +424,7 @@ Respond with EXACTLY this JSON structure (no other text):
    - <criterion 2>: PASS
    ...
 
+   Docs: <sprintDocPath> (+ <count> related docs updated)
    Next sprint: <next sprint title> (run /bober-sprint to continue)
    ```
    If all sprints are done, report `=== PLAN COMPLETE (N/N sprints) ===` instead of "Next sprint".

package/skills/bober.sprint/references/lens-panel.md

@@ -0,0 +1,115 @@
+# Lens Panel — Canonical Protocol Reference
+
+This document is the single source of truth for native panel orchestration in agent-bober.
+It embeds the five canonical lens focus fragments verbatim from
+`src/orchestrator/eval-lenses.ts` (the `LENS_CATALOG` literal) and documents the
+split fan-out, majority-vote/fail-closed reconciliation, and the `lensVerdicts` output shape.
+
+---
+
+## Lens Focus Fragments
+
+The following fragments are the exact strings returned by `resolveLensFocus(lens)` for each
+built-in lens. They MUST remain byte-for-byte identical to the corresponding entries in
+`LENS_CATALOG` — the drift gate (`src/orchestrator/lens-panel-parity.test.ts`) enforces this.
+
+### correctness
+
+```
+Focus on whether the implementation actually satisfies each success criterion verbatim. Check that all required behaviours exist, all edge cases are handled, and the contract's definitionOfDone is met.
+```
+
+### security
+
+```
+Focus on injection vulnerabilities, authentication and authorisation gaps, secret handling, unsafe input validation, and any path traversal or privilege escalation risks.
+```
+
+### regression
+
+```
+Focus on whether previously working behaviour still works after the changes. Verify that pre-existing tests pass, that no public API or config interface was broken, and that the sprint diff does not silently remove functionality.
+```
+
+### quality
+
+```
+Focus on principles violations, dead code, misleading naming, smells, duplicated logic, and whether the implementation follows the project's established patterns and conventions.
+```
+
+### simplicity
+
+```
+Focus exclusively on over-engineering in the production code: logic that reinvents the standard library, dependencies or hand-rolled code doing what a native platform feature already provides, abstractions with a single implementation, configuration nobody reads, dead flexibility, and code expressible in materially fewer lines. For each, name the location, what to cut, and what replaces it. Never flag tests, assertion-based self-checks, input validation at trust boundaries, error handling, security measures, or accessibility as deletable — minimalism governs production code, never the verification or safety discipline.
+```
+
+> The `simplicity` lens is the complexity-only counterpart to `quality`. `quality` asks
+> "does this follow our patterns and is it free of smells?"; `simplicity` asks "what can be
+> deleted, replaced by stdlib/native, or shrunk?" — and is forbidden from ever recommending the
+> removal of a test, a validation, or a safety measure. It pairs cleanly with the evaluator's
+> test/verification Iron Law: minimalism governs what is built, never what is verified.
+
+---
+
+## Native Panel Protocol
+
+### Split Fan-out
+
+When the native panel is active, the orchestrator spawns evaluators in two passes:
+
+1. **Deterministic evaluator (one instance):** runs the configured strategy suite exactly once
+   (build, typecheck, lint, unit-test, playwright, api-check, etc.). This produces the
+   deterministic verdict — objective, tool-based checks that do not depend on lens focus.
+
+2. **Qualitative evaluators (one per configured lens):** each evaluator receives the same
+   sprint diff and context but is instructed to judge the contract's success criteria
+   exclusively through its lens focus fragment. The strategy suite is **not** re-run for
+   these evaluators — they perform qualitative assessment only, using the results already
+   collected by the deterministic evaluator as supporting context.
+
+This split ensures strategies execute once (no duplicate CI cost) while each lens evaluates
+the diff independently.
+
+### Reconciliation — Majority Vote, Fail-Closed
+
+The lens verdicts are reconciled by `reconcile()` in
+`src/orchestrator/workflow/reconciler.ts` using the following semantics:
+
+- **Inputs:** the array of per-lens `EvalResult` objects (`lensVerdicts`).
+- **Require non-empty:** an empty array throws `"reconcile: lensVerdicts must be non-empty"`.
+- **Vote count:** `passCount` = number of lenses where `passed === true`;
+  `failCount` = total − passCount.
+- **Verdict:** `passed = passCount > failCount` (strict majority).
+  - **Fail-closed on tie:** when `passCount === failCount` the panel verdict is `false`.
+- **Details:** union of all failing lens details, de-duplicated by `(criterion, message)` key.
+- **Feedback:** failing lenses' feedback joined with `\n`; `"All lenses passed."` when all pass.
+- **Summary:** `"Panel verdict: ${passCount}/${n} lenses passed"`.
+- **Score:** `Math.round((100 * passCount) / n)`.
+- **Evaluator tag:** `evaluator = "panel"`.
+- **Timestamp:** echoed verbatim from the input argument (pure function, ADR-4).
+
+### Combine
+
+The final sprint verdict combines both passes:
+
+```
+final.passed = deterministic.passed && reconciled.passed
+```
+
+Both must pass for the sprint to be accepted.
+
+### lensVerdicts Output Shape
+
+After reconciliation the orchestrator writes a `lensVerdicts` array into the saved
+`EvalResult` JSON and sets `evaluator = "panel"`. The array shape is:
+
+```ts
+lensVerdicts: Array<{
+  lens: string;    // e.g. "correctness", "security", "regression", "quality", "simplicity"
+  passed: boolean; // individual lens verdict
+  summary: string; // per-lens summary from the qualitative evaluator
+}>
+```
+
+This field is optional and backward-compatible: eval results produced before the panel
+feature (or by non-panel evaluators) simply omit it.

package/skills/shared/arch-lens-panel.md

@@ -0,0 +1,126 @@
+# Arch Lens Panel — Canonical Protocol Reference
+
+This document is the single source of truth for native architect panel orchestration in agent-bober.
+It embeds the seven canonical arch lens focus fragments verbatim from
+`src/orchestrator/arch-lenses.ts` (the `ARCH_LENS_CATALOG` literal) and documents the
+CP2 synthesis panel and CP5 reconcile panel protocols.
+The drift gate (`src/orchestrator/arch-lens-panel-parity.test.ts`) enforces byte-exact parity.
+
+---
+
+## Lens Focus Fragments
+
+The following fragments are the exact strings returned by `resolveArchLensFocus(lens)` for each
+built-in arch lens. They MUST remain byte-for-byte identical to the corresponding entries in
+`ARCH_LENS_CATALOG` — the drift gate (`src/orchestrator/arch-lens-panel-parity.test.ts`) enforces this.
+
+### scalability
+
+```
+Focus on whether the proposed architecture can handle projected load growth. Evaluate horizontal and vertical scaling paths, bottlenecks, stateful vs stateless components, and whether partitioning or sharding strategies are available when needed.
+```
+
+### security
+
+```
+Focus on the threat surface introduced by this architecture. Evaluate trust boundaries, data flows across zones, authentication and authorisation enforcement points, secrets management, and exposure of internal services.
+```
+
+### cost
+
+```
+Focus on the total cost of ownership implied by this architecture. Evaluate compute, storage, and egress costs at projected scale, licensing or SaaS subscription expenses, and the operational overhead of running, monitoring, and scaling the system.
+```
+
+### operability
+
+```
+Focus on how easy it will be to operate this architecture in production. Evaluate observability (metrics, logs, traces), deployment complexity, rollout and rollback procedures, on-call burden, and the blast radius of common failure modes.
+```
+
+### maintainability
+
+```
+Focus on how easy it will be to change and extend this architecture over time. Evaluate coupling between components, clarity of boundaries, documentation needs, onboarding friction for new contributors, and the risk of accruing technical debt.
+```
+
+### reversibility
+
+```
+Focus on how difficult or costly it would be to undo or replace this architectural decision. Evaluate lock-in to vendors or proprietary technologies, data migration complexity, and whether a strangler-fig or incremental migration path exists if the approach needs to change.
+```
+
+### simplicity
+
+```
+Focus on whether this is the simplest architecture that satisfies the Checkpoint 1 constraints. Challenge whether each component needs to exist, whether a native platform feature or an already-present dependency removes a proposed custom layer, whether two components should collapse into one, and whether any abstraction is speculative — added for a use case absent from the problem statement. Reward the smallest design that honours every hard constraint; penalise layers introduced for unproven future flexibility, but never at the expense of a stated constraint.
+```
+
+> The `simplicity` lens enforces the top rung of the YAGNI ladder at design time: "does this
+> component need to exist at all?". It is constraint-bounded by construction — it may never
+> recommend dropping a layer that a Checkpoint 1 hard constraint requires. This keeps it
+> consistent with the architect's IRON LAW (every decision must cite the constraint that
+> eliminates the rejected alternative): a simplification that violates a constraint is not simpler,
+> it is wrong.
+
+---
+
+## Native Architect Panel Protocol
+
+### CP2 Synthesis Panel
+
+At Checkpoint 2 (candidate generation + scoring), the orchestrator runs the synthesis panel:
+
+1. **Generate candidates:** The architect produces 2–3 candidate approaches that satisfy the
+   Checkpoint 1 constraints.
+
+2. **Lens scorer fan-out (one per lens):** The orchestrator spawns one scorer subagent per
+   configured arch lens (scalability, security, cost, operability, maintainability, reversibility,
+   simplicity), bounded by `maxConcurrent`. Each scorer receives the same candidate set and is instructed to
+   score the candidates exclusively through its lens focus fragment (the exact string returned by
+   `resolveArchLensFocus(lens)` from `src/orchestrator/arch-lenses.ts`).
+
+3. **Synthesis:** `synthesize()` in `src/orchestrator/synthesizer.ts` aggregates the per-lens
+   scores and produces a ranked winner with dissent. The highest-scoring approach across lenses
+   becomes the recommended architecture; any lens that preferred a different candidate is recorded
+   as a dissenting voice in the synthesis output.
+
+### CP5 Reconcile Panel
+
+At Checkpoint 5 (review pass), the orchestrator runs the reconcile panel:
+
+1. **Lens reviewer fan-out (one per lens):** The orchestrator spawns one reviewer subagent per
+   configured arch lens. Each reviewer receives the assembled architecture document and ADRs, and
+   is instructed to produce a PASS/FAIL verdict exclusively through its lens focus fragment.
+
+2. **Reconciliation — fail-closed on tie:** `reconcile()` in
+   `src/orchestrator/workflow/reconciler.ts` aggregates the per-lens verdicts using the following
+   semantics:
+
+   - **Inputs:** the array of per-lens `EvalResult` objects (`lensVerdicts`).
+   - **Require non-empty:** an empty array throws `"reconcile: lensVerdicts must be non-empty"`.
+   - **Vote count:** `passCount` = number of lenses where `passed === true`;
+     `failCount` = total − passCount.
+   - **Verdict:** `passed = passCount > failCount` (strict majority).
+     - **Fail-closed on tie:** when `passCount === failCount` the panel verdict is `false`.
+   - **Details:** union of all failing lens details, de-duplicated by `(criterion, message)` key.
+   - **Feedback:** failing lenses' feedback joined with `\n`; `"All lenses passed."` when all pass.
+   - **Summary:** `"Panel verdict: ${passCount}/${n} lenses passed"`.
+   - **Score:** `Math.round((100 * passCount) / n)`.
+   - **Evaluator tag:** `evaluator = "panel"`.
+
+### lensVerdicts Output Shape
+
+After reconciliation the orchestrator writes a `lensVerdicts` array into the saved result.
+The array shape is:
+
+```ts
+lensVerdicts: Array<{
+  lens: string;    // e.g. "scalability", "security", "cost", "operability", "maintainability", "reversibility", "simplicity"
+  passed: boolean; // individual lens verdict
+  summary: string; // per-lens summary from the scorer or reviewer subagent
+}>
+```
+
+This field is optional and backward-compatible: results produced before the panel feature
+(or by non-panel architect runs) simply omit it.

package/skills/shared/lens-panel.md

@@ -0,0 +1,115 @@
+# Lens Panel — Canonical Protocol Reference
+
+This document is the single source of truth for native panel orchestration in agent-bober.
+It embeds the five canonical lens focus fragments verbatim from
+`src/orchestrator/eval-lenses.ts` (the `LENS_CATALOG` literal) and documents the
+split fan-out, majority-vote/fail-closed reconciliation, and the `lensVerdicts` output shape.
+
+---
+
+## Lens Focus Fragments
+
+The following fragments are the exact strings returned by `resolveLensFocus(lens)` for each
+built-in lens. They MUST remain byte-for-byte identical to the corresponding entries in
+`LENS_CATALOG` — the drift gate (`src/orchestrator/lens-panel-parity.test.ts`) enforces this.
+
+### correctness
+
+```
+Focus on whether the implementation actually satisfies each success criterion verbatim. Check that all required behaviours exist, all edge cases are handled, and the contract's definitionOfDone is met.
+```
+
+### security
+
+```
+Focus on injection vulnerabilities, authentication and authorisation gaps, secret handling, unsafe input validation, and any path traversal or privilege escalation risks.
+```
+
+### regression
+
+```
+Focus on whether previously working behaviour still works after the changes. Verify that pre-existing tests pass, that no public API or config interface was broken, and that the sprint diff does not silently remove functionality.
+```
+
+### quality
+
+```
+Focus on principles violations, dead code, misleading naming, smells, duplicated logic, and whether the implementation follows the project's established patterns and conventions.
+```
+
+### simplicity
+
+```
+Focus exclusively on over-engineering in the production code: logic that reinvents the standard library, dependencies or hand-rolled code doing what a native platform feature already provides, abstractions with a single implementation, configuration nobody reads, dead flexibility, and code expressible in materially fewer lines. For each, name the location, what to cut, and what replaces it. Never flag tests, assertion-based self-checks, input validation at trust boundaries, error handling, security measures, or accessibility as deletable — minimalism governs production code, never the verification or safety discipline.
+```
+
+> The `simplicity` lens is the complexity-only counterpart to `quality`. `quality` asks
+> "does this follow our patterns and is it free of smells?"; `simplicity` asks "what can be
+> deleted, replaced by stdlib/native, or shrunk?" — and is forbidden from ever recommending the
+> removal of a test, a validation, or a safety measure. It pairs cleanly with the evaluator's
+> test/verification Iron Law: minimalism governs what is built, never what is verified.
+
+---
+
+## Native Panel Protocol
+
+### Split Fan-out
+
+When the native panel is active, the orchestrator spawns evaluators in two passes:
+
+1. **Deterministic evaluator (one instance):** runs the configured strategy suite exactly once
+   (build, typecheck, lint, unit-test, playwright, api-check, etc.). This produces the
+   deterministic verdict — objective, tool-based checks that do not depend on lens focus.
+
+2. **Qualitative evaluators (one per configured lens):** each evaluator receives the same
+   sprint diff and context but is instructed to judge the contract's success criteria
+   exclusively through its lens focus fragment. The strategy suite is **not** re-run for
+   these evaluators — they perform qualitative assessment only, using the results already
+   collected by the deterministic evaluator as supporting context.
+
+This split ensures strategies execute once (no duplicate CI cost) while each lens evaluates
+the diff independently.
+
+### Reconciliation — Majority Vote, Fail-Closed
+
+The lens verdicts are reconciled by `reconcile()` in
+`src/orchestrator/workflow/reconciler.ts` using the following semantics:
+
+- **Inputs:** the array of per-lens `EvalResult` objects (`lensVerdicts`).
+- **Require non-empty:** an empty array throws `"reconcile: lensVerdicts must be non-empty"`.
+- **Vote count:** `passCount` = number of lenses where `passed === true`;
+  `failCount` = total − passCount.
+- **Verdict:** `passed = passCount > failCount` (strict majority).
+  - **Fail-closed on tie:** when `passCount === failCount` the panel verdict is `false`.
+- **Details:** union of all failing lens details, de-duplicated by `(criterion, message)` key.
+- **Feedback:** failing lenses' feedback joined with `\n`; `"All lenses passed."` when all pass.
+- **Summary:** `"Panel verdict: ${passCount}/${n} lenses passed"`.
+- **Score:** `Math.round((100 * passCount) / n)`.
+- **Evaluator tag:** `evaluator = "panel"`.
+- **Timestamp:** echoed verbatim from the input argument (pure function, ADR-4).
+
+### Combine
+
+The final sprint verdict combines both passes:
+
+```
+final.passed = deterministic.passed && reconciled.passed
+```
+
+Both must pass for the sprint to be accepted.
+
+### lensVerdicts Output Shape
+
+After reconciliation the orchestrator writes a `lensVerdicts` array into the saved
+`EvalResult` JSON and sets `evaluator = "panel"`. The array shape is:
+
+```ts
+lensVerdicts: Array<{
+  lens: string;    // e.g. "correctness", "security", "regression", "quality", "simplicity"
+  passed: boolean; // individual lens verdict
+  summary: string; // per-lens summary from the qualitative evaluator
+}>
+```
+
+This field is optional and backward-compatible: eval results produced before the panel
+feature (or by non-panel evaluators) simply omit it.