docs(tasks): extract and establish audit-1 and audit-2 protocol templates

chore(tasks): add UI redesign task for sessions drawer

tasks/audit-1.md

@@ -0,0 +1,65 @@
+# Task Plan & Specification Audit Protocol (`tasks/audit-1.md`)
+
+This protocol defines the standard for auditing, grading, and refining new task
+files in `tasks/new/` before implementation begins.
+
+---
+
+## 1. Direct Execution Protocol (When Running the Audit Yourself)
+
+When commanded to **"Run Audit-1 on `[TASK_FILE]`"**:
+
+1. **Remain Strictly Read-Only:** Do not modify any codebase files or task files
+   during the audit.
+2. **Examine the Codebase:** Inspect the current architecture to verify if the
+   task's assumptions, dependencies, and target files are accurate.
+3. **Score against the 5-Point Plan Rubric:**
+   - **Criterion 1 (Standards Compliance):** Adheres to `tasks/GUIDELINES.md`
+     naming conventions (`YYYY-MMDD.XX.agent.type.scope.title-HHMM.md`) and
+     contains the mandatory `# TASK METADATA` header.
+   - **Criterion 2 (Architectural Safety):** Identifies real technical risks
+     (event loop blocks, memory leaks, cache staleness, monolithic sprawl,
+     zero-trust bypasses) with mitigations.
+   - **Criterion 3 (Purity & Simplicity):** Evaluates native/simpler
+     alternatives and avoids dependency/code bloat.
+   - **Criterion 4 (Implementation Precision):** Target files, functions, SQL
+     schemas, and error boundaries are unambiguously specified.
+   - **Criterion 5 (Testing Rigor):** Includes unit/integration test plans
+     covering happy paths, edge cases, and 401/403 security gates.
+4. **Output the Standard Audit Report:**
+   - **Overall Score / Rating:** [e.g. 5/5, 4/5, or Letter Grade]
+   - **Verdict:** [APPROVED / NEEDS REVISION / REJECTED]
+   - **Strengths & Plan Alignment:** What the plan gets right.
+   - **Identified Gaps & Failure Risks:** Missing edge cases, risks, or
+     regressions.
+   - **Concrete Suggested Revisions:** Exact text, parameters, or steps to
+     add/change in the task file.
+
+---
+
+## 2. Dispatch Template (When Preparing a Prompt for Jules or External Agents)
+
+When commanded to **"Prepare an Audit-1 prompt for Jules"**, fill in and provide
+the following block:
+
+```text
+**Role:** Act as a Principal Systems Architect and Task Quality Critic. Do not modify the codebase or execute code during this session. Your sole deliverable is a structured task critique report.
+
+**The Scope:** Review the newly generated task file in `[tasks/new/TASK_FILENAME.md]` against our master architectural guidelines (`AGENTS.md`, `docs/`, `tasks/GUIDELINES.md`).
+
+**Your Task:**
+Critically evaluate the proposed task plan against the 5-point quality rubric in `tasks/audit-1.md`:
+1. Metadata & Standards Compliance
+2. Architectural Alignment & Safety
+3. Purity & Simplicity (Avoiding bloat)
+4. Implementation Precision & State Machine
+5. Testing & Quality Gate Rigor
+
+**Deliverable:**
+Provide a structured critique report with:
+- **Overall Score / Rating:** [e.g. 5/5, 4/5, or Letter Grade]
+- **Verdict:** [APPROVED / NEEDS REVISION / REJECTED]
+- **Strengths & Plan Alignment:** Key architectural insights captured in the plan.
+- **Identified Gaps & Potential Risks:** Missing edge cases, unaddressed failure modes, or UX/architectural oversights.
+- **Concrete Suggested Revisions:** Exact adjustments, additions, or rewordings to incorporate into the task file before implementation starts.
+```

tasks/audit-2.md

@@ -0,0 +1,69 @@
+# Implementation & Code Quality Audit Protocol (`tasks/audit-2.md`)
+
+This protocol defines the standard for auditing code changes, PR branches, or
+completed tasks before merging or releasing.
+
+---
+
+## 1. Direct Execution Protocol (When Running the Audit Yourself)
+
+When commanded to **"Run Audit-2 on `[BRANCH / TASK / FILES]`"**:
+
+1. **Remain Strictly Read-Only:** Do not modify code, commit changes, or push to
+   remotes during the audit.
+2. **Inspect Actual Code Changes:** Compare the modified files against the
+   original task specification and `AGENTS.md`.
+3. **Score against the 5-Point Implementation Rubric:**
+   - **Criterion 1 (Spec & Scope Fidelity):** Built exactly what was requested
+     without omitting core features, introducing rogue edits, or degrading
+     existing UX.
+   - **Criterion 2 (Zero-Trust Security & Boundary Safety):** Scope guards,
+     session isolation, and error boundaries are verified. Zero privilege
+     escalation risks.
+   - **Criterion 3 (Modularity & Clean Architecture):** Clean separation of
+     concerns without contributing to file bloat, monolithic sprawl, or circular
+     imports.
+   - **Criterion 4 (Quality Gates & Test Evidence):** `deno fmt`,
+     `deno task lint`, `deno task check`, and `deno test --allow-all` pass with
+     0 errors/warnings. Comprehensive test coverage for happy and failure paths.
+   - **Criterion 5 (Runtime & Client-Side Integrity):** For UI changes, zero
+     runtime JS parsing/syntax errors (validated via `ui/ui_scripts.test.ts`),
+     accessible layout, and consistent styling tokens.
+4. **Output the Standard Code Audit Report:**
+   - **Overall Implementation Score:** [e.g. 5/5, 4/5, or Letter Grade]
+   - **Verdict:** [MERGE READY / REVISION REQUIRED / BLOCKED]
+   - **Successes & Verified Achievements:** Verified working features with
+     evidence.
+   - **Deficiencies, Regressions & Failure Risks:** Bugs, unhandled errors, UX
+     regressions, or security gaps found.
+   - **Actionable Remediation Suggestions:** Specific, prioritized code changes
+     needed before release.
+
+---
+
+## 2. Dispatch Template (When Preparing a Prompt for Jules or External Agents)
+
+When commanded to **"Prepare an Audit-2 prompt for Jules"**, fill in and provide
+the following block:
+
+```text
+**Role:** Act as a Senior Security, Architecture & Quality Assurance Auditor. Do not modify production code or push commits during this audit session. Your sole deliverable is an objective Code Quality & Security Audit Report.
+
+**The Scope:** [Specify target branch, recent commits, modified files, or completed task in `tasks/wip/TASK_FILENAME.md`].
+
+**Your Task:**
+Audit the actual codebase changes against the original task specification and our system guidelines (`AGENTS.md`, `docs/`) using the 5-point implementation rubric in `tasks/audit-2.md`:
+1. Specification & Scope Fidelity
+2. Zero-Trust Security & Boundary Safety
+3. Modularity & Clean Architecture
+4. Quality Gates & Test Evidence
+5. Runtime & Client-Side Integrity
+
+**Deliverable:**
+Provide a structured code audit report with:
+- **Overall Implementation Score:** [e.g. 5/5, 4/5, or Letter Grade]
+- **Verdict:** [MERGE READY / REVISION REQUIRED / BLOCKED]
+- **Successes & Verified Achievements:** Exact functionality verified and working as expected.
+- **Deficiencies, Regressions & Failure Risks:** Technical bugs, unhandled errors, UX regressions, or security gaps found.
+- **Actionable Remediation Suggestions:** Specific, prioritized code fixes or refactoring steps needed before final approval.
+```

tasks/new/2026-0825.01.jul.sec.auth-api.zero-trust-scope-guards-1805.md

@@ -0,0 +1,56 @@
+# TASK METADATA
+
+- **Target Files:** `server/auth-session.ts`, `server/routes/sessions.ts`, `server/routes/events.ts`, `server/main.ts`, `ui/mod.ts`, `server/main.test.ts`
+- **Core Objective:** Implement strict Zero-Trust scope enforcement and permission guards across all Auth-Yes internal API routes and SSR UI pages to ensure delegated and read-only sessions cannot escalate privileges, perform unauthorized mutations, or access admin interfaces.
+- **Dependencies:** None
+- **Additional Important Notes:** Delegated sessions (`is_agent = true`) must hold strictly the intersection of user permissions and assigned `custom_scopes`. Self-revocation of a delegated session is permitted, but revoking other sessions is prohibited without `write:sessions` or `*`.
+
+---
+
+## Architectural Considerations & Risks
+
+- **Risks:**
+  - **Backward-Compatibility with Cached Sessions:** Existing delegated sessions in the Valkey cache might lack explicit scopes if they were created before this strict enforcement. The middleware must default to a safe deny state for unknown or missing scopes but handle legacy `is_agent = true` sessions gracefully by denying mutating actions unless explicitly permitted.
+  - **Self-Revocation Edge Case:** The guard logic must correctly distinguish between a session revoking itself (which is always allowed for clean logouts) and a session attempting to revoke a sibling or parent session.
+  - **Global Admin Resolution:** The `isGlobalAdmin` check relies on database queries or cache. Ensure that the new middleware does not introduce significant latency by repeatedly querying PostgreSQL on every protected route. Use Valkey caching where possible.
+
+- **Alternatives:**
+  - Instead of injecting `customScopes` into the Valkey cache session payload, we could perform a database lookup on every privileged API request to determine exact grants. However, this violates the Auth-Yes architectural principle of fast-path caching at the edge and would significantly degrade performance. The chosen approach of checking scopes from the cached `AuthenticatedUser` object is highly modular and performant.
+
+## Proposed Implementation
+
+### 1. Scope Guard Helpers (`server/auth-session.ts`)
+Implement reusable composable functions to evaluate the current user's capabilities.
+- `hasScope(auth: AuthenticatedUser, requiredScope: string): boolean`: Evaluates if `auth.customScopes` contains `*` or the `requiredScope`. If `!auth.isAgent`, returns `true` (primary sessions have all capabilities).
+- Create Hono middleware helpers:
+  - `requirePrimarySession()`: Denies access with `403 Forbidden` if `auth.isAgent === true`.
+  - `requireScope(scope: string)`: Denies access if `hasScope(auth, scope)` returns false.
+  - `requireAdmin(auth: AuthenticatedUser)`: Uses `isGlobalAdmin(auth.userId)` and verifies `!auth.isAgent` OR `auth.customScopes.includes("*")`.
+
+### 2. Guard Internal API Routes
+Apply the newly created guards to critical endpoints.
+
+- **`server/routes/sessions.ts`**
+  - `DELETE /api/sessions/:id`: Allow if target `id === auth.sessionId`. Otherwise, require `write:sessions` scope.
+  - `PUT /api/sessions/:id/scopes`: Require `admin` or `*` scope, OR `write:sessions`.
+  - `POST /api/sessions/:id/extend`: Require `write:sessions` or `*`.
+  - `POST /api/sessions/delegate`: Prevent privilege escalation. Require `admin` or `*` scope to delegate an `admin` mode session. If creating a `read_only` or `operator` session, require the delegator to have at least those equivalent scopes.
+
+- **`server/routes/events.ts`**
+  - `POST /api/events`: Require `write:events` or `*`.
+  - `POST /api/events/:id/end`: Require `write:events` or `*`.
+  - `POST /api/events/:id/extend`: Require `write:events` or `*`.
+
+- **`server/main.ts`**
+  - Apply `requirePrimarySession()` or `requireAdmin()` to `/api/admin/*` and `/api/passkeys/*` endpoints.
+
+### 3. SSR UI Gates (`ui/mod.ts`)
+Guard the user interfaces against unauthorized delegated sessions.
+- `/admin/*`: Verify `isAdmin && (!auth.isAgent || auth.customScopes.includes("*"))`. Redirect unauthorized sessions to `/dashboard` or return a `403 Forbidden` page.
+- `/dashboard/passkeys`: Verify `!auth.isAgent`. Delegated sessions cannot manage passkeys.
+
+### 4. Testing (`server/main.test.ts`)
+- Write tests that create a delegated session with only `read_only` scopes.
+- Assert that this session gets a `403 Forbidden` when attempting to call `POST /api/sessions/delegate`, `DELETE /api/sessions/:other_id`, and `POST /api/events`.
+- Assert that the delegated session can successfully call `DELETE /api/sessions/:own_id`.
+- Write tests verifying that a delegated session attempting to access `/admin/users` is redirected/blocked.

tasks/new/2026-0825.01.jul.story.ui.redesign-sessions-drawer-1812.md

@@ -0,0 +1,48 @@
+# TASK METADATA
+
+- **Target Files:**
+  - `ui/components/SessionsPage.tsx`
+  - `ui/ui_scripts.test.ts`
+- **Core Objective:** Redesign the Sessions management page header and drawer to eliminate dual competing top buttons, restoring the clean single `[+ Delegate Session]` header action, and unifying both pass creation workflows (1:1 Direct Pass vs. Multi-Claim Workshop Pass) into clean internal drawer tabs.
+- **Dependencies:** None.
+- **Additional Important Notes:** Must maintain 100% compliance with zero-framework SSR JSX standards and pass `ui/ui_scripts.test.ts` without client-side syntax errors.
+
+---
+
+## Architectural Considerations & Risks
+
+- **Risks:** The primary risk involves introducing JavaScript syntax errors when consolidating the drawer forms and adding the tab-switching logic. Since this is an SSR JSX environment without a framework like React, all DOM manipulation and state management (like toggling tabs) rely on raw inline or embedded `<script>` blocks. A syntax error here could break the page interactions and fail the `ui/ui_scripts.test.ts` gate.
+- **Alternatives:** We could keep the forms completely separate, but this violates the core objective of eliminating cognitive clutter and unified navigation. The proposed vanilla JavaScript tab toggle is the most native and compliant approach for this specific architectural boundary.
+- **UX Consistency:** The Event Cockpit Deck must remain rendered *above* the Active Sessions table to ensure real-time visibility for workshop hosts.
+
+## Proposed Implementation
+
+### 1. Header Consolidation
+- In `ui/components/SessionsPage.tsx`, locate the top header section.
+- Remove the `[🎟️ + Create Workshop Pass]` button completely.
+- Retain only the single, primary `[🔑 + Delegate Session]` button (and ensure it triggers `openDelegateDrawer()`).
+
+### 2. Drawer Consolidation (`#delegateDrawer`)
+- Remove the entire `#eventDrawer` DOM node.
+- Inside `#delegateDrawer`, introduce a segmented flexbox tab selector at the top of the form area.
+- Add the following styling for the tab container:
+  `display: flex; background: var(--surface-muted); padding: 4px; border-radius: var(--radius-sm); border: 1px solid var(--border-subtle); gap: 4px;`
+- Add styling for the tab buttons:
+  `flex: 1; padding: 0.5rem 0.75rem; border-radius: var(--radius-sm); border: none; font-weight: 600; cursor: pointer; transition: all 0.15s;`
+  (Use an `.active` class with `background: var(--surface-card); color: var(--primary); box-shadow: var(--shadow-xs);`).
+- Wrap the existing 1:1 Direct Pass form fields inside a `<div id="tabDirectPass">`.
+- Move the fields from the deleted `#eventDrawer` into a new `<div id="tabWorkshopPass" style="display: none;">` inside `#delegateDrawer`.
+
+### 3. JavaScript Tab-Switching Logic
+- Add vanilla JavaScript functions to the embedded `<script>` block in `SessionsPage.tsx` to handle tab switching.
+- Implement a function (e.g., `switchDelegateTab(tabId)`) that:
+  - Toggles `display: block` and `display: none` between `#tabDirectPass` and `#tabWorkshopPass`.
+  - Updates the active state styling on the corresponding tab buttons.
+
+### 4. Code Cleanup
+- Remove the `openEventDrawer()` and `closeEventDrawer()` functions from the `<script>` block.
+- Ensure `closeDelegateDrawer()` correctly resets the forms or hides the drawer.
+
+### 5. Quality Gates
+- Run `deno fmt` and `deno task lint` to ensure code style compliance.
+- Run `deno task test` to ensure `ui/ui_scripts.test.ts` passes, verifying there are no syntax errors in the newly consolidated `<script>` block.

tasks/path.md

@@ -53,48 +53,63 @@ in an existing task file._
 
 ---
 
-## 3. Pre-PR Quality & Security Audit Template (Auditor)
+## 3. Implementation & Code Quality Audit Template (`tasks/audit-2.md`)
 
-_Use this template to instruct an agent to perform an exhaustive pre-merge
-audit._
+_Use this template to perform an exhaustive post-implementation audit on code
+changes, PR branches, or completed tasks before merging or deploying. See
+complete protocol in
+[`tasks/audit-2.md`](file:///home/tylerg/p/data/auth-yes/tasks/audit-2.md)._
 
 ```text
-**Role:** Act as a Senior Security & Quality Assurance Auditor.
+**Role:** Act as a Senior Security, Architecture & Quality Assurance Auditor. Do not modify production code or push commits during this audit session. Your sole deliverable is an objective Code Quality & Security Audit Report.
 
-**The Scope:** [List recent changes, PR branch, or target components to audit.]
+**The Scope:** [Specify target branch, recent commits, modified files, or completed task in `tasks/wip/TASK_FILENAME.md`].
 
 **Your Task:**
-1. Inspect code changes against architectural boundaries.
-2. Verify zero regression in authentication, session management, or RBAC grants.
-3. Confirm all unit and integration tests pass with 0 lint warnings and 0 typecheck errors.
-4. Document findings and generate an audit report if any vulnerabilities or performance bottlenecks are detected.
+Audit the actual codebase changes against the original task specification and our system guidelines (`AGENTS.md`, `docs/`) using the 5-point implementation rubric in `tasks/audit-2.md`:
+1. Specification & Scope Fidelity
+2. Zero-Trust Security & Boundary Safety
+3. Modularity & Clean Architecture
+4. Quality Gates & Test Evidence
+5. Runtime & Client-Side Integrity
+
+**Deliverable:**
+Provide a structured code audit report with:
+- **Overall Implementation Score:** [e.g. 5/5, 4/5, or Letter Grade]
+- **Verdict:** [MERGE READY / REVISION REQUIRED / BLOCKED]
+- **Successes & Verified Achievements:** Exact functionality verified and working as expected.
+- **Deficiencies, Regressions & Failure Risks:** Technical bugs, unhandled errors, UX regressions, or security gaps found.
+- **Actionable Remediation Suggestions:** Specific, prioritized code fixes or refactoring steps needed before final approval.
 ```
 
 ---
 
-## 4. Task Plan Review & Critique Template (Architect / Critic)
+## 4. Task Plan Review & Critique Template (`tasks/audit-1.md`)
 
 _Use this template to critically audit, score, and refine new task files in
-`tasks/new/` before approving them for implementation._
+`tasks/new/` before approving them for implementation. See complete protocol in
+[`tasks/audit-1.md`](file:///home/tylerg/p/data/auth-yes/tasks/audit-1.md)._
 
 ```text
-**Role:** Act as a Principal Systems Architect and Task Quality Critic.
+**Role:** Act as a Principal Systems Architect and Task Quality Critic. Do not modify the codebase or execute code during this session. Your sole deliverable is a structured task critique report.
 
-**The Scope:** Review the newly generated task file in `tasks/new/[TASK_FILENAME].md`.
+**The Scope:** Review the newly generated task file in `[tasks/new/TASK_FILENAME.md]` against our master architectural guidelines (`AGENTS.md`, `docs/`, `tasks/GUIDELINES.md`).
 
 **Your Task:**
-Critically evaluate the proposed task plan against the following 5-point quality rubric:
-1. **Metadata & Standards Compliance:** Does the file strictly adhere to `tasks/GUIDELINES.md` naming conventions and include the exact `# TASK METADATA` header?
-2. **Architectural Boundary Safety:** Does the plan identify genuine technical risks (e.g., event loop blocking, memory leaks, cache staleness, zero-trust perimeter bypasses) and provide concrete mitigations?
-3. **Alternatives & Zero-Dependency Purity:** Did the author evaluate simpler or more native alternatives and justify why the proposed design avoids dependency bloat?
-4. **Implementation Precision:** Are target functions, data structures, SQL migrations, FFI symbols, and error boundaries defined with crystal clarity?
-5. **Testing & Quality Gate Rigor:** Does the proposed implementation include comprehensive unit/integration test specifications covering both happy-path and failure modes?
+Critically evaluate the proposed task plan against the 5-point quality rubric in `tasks/audit-1.md`:
+1. Metadata & Standards Compliance
+2. Architectural Alignment & Safety
+3. Purity & Simplicity (Avoiding bloat)
+4. Implementation Precision & State Machine
+5. Testing & Quality Gate Rigor
 
 **Deliverable:**
 Provide a structured critique report with:
+- **Overall Score / Rating:** [e.g. 5/5, 4/5, or Letter Grade]
 - **Verdict:** [APPROVED / NEEDS REVISION / REJECTED]
-- **Strengths:** Key architectural insights captured by the author.
-- **Identified Gaps & Refinements:** Concrete adjustments to incorporate into the task file before implementation starts.
+- **Strengths & Plan Alignment:** Key architectural insights captured in the plan.
+- **Identified Gaps & Potential Risks:** Missing edge cases, unaddressed failure modes, or UX/architectural oversights.
+- **Concrete Suggested Revisions:** Exact adjustments, additions, or rewordings to incorporate into the task file before implementation starts.
 ```
 
 ---