Merge pull request #248 from engineeredsoftware/v48/gate-1-identity-auth-interactive-qa

V48 Gate 1: Identity and authentication interactive QA

Author: geraldarthurdavis

BITCODE_SPEC_V48_NOTES.md

@@ -11,6 +11,9 @@
 - Prior generated proof appendix: `BITCODE_SPEC_V46_PROVEN.md`
 - V48 state: notes-only draft opening
 - Scope: V48 starts as the interactive local experiential QA target over promoted V47 commercial website testnet launch canon.
+- QA findings ledger: `BITCODE_V48_QA.md` (the running record of accepted V48 findings and repairs)
+- Gate 1 (in progress): identity and authentication interactive QA on branch `v48/gate-1-identity-auth-interactive-qa`
+- Full draft family (`BITCODE_SPEC_V48.md`, `BITCODE_SPEC_V48_DELTA.md`, `BITCODE_SPEC_V48_PARITY_MATRIX.md`) opens in a dedicated specification-authoring gate once the interactive QA tracks have accumulated the specification intent; Gate 1 closed as the identity/authentication QA-and-repairs gate
 
 ## Notes-only draft rule
 
@@ -53,6 +56,39 @@ deployed staging-testnet system end to end, step by step, and fix what breaks.
 - Ledgerized journaling: replayability, auditability, `/packs` page UX/UI, and
   the personal (Auxillaries) history of work.
 
+## V48 Gate 1 in progress: identity and authentication interactive QA
+
+Gate 1 exercises the live commercial testnet experience exactly as the
+notes-only rule directs: interactively, recording accepted findings in
+`BITCODE_V48_QA.md` (F1-F10 so far), and landing fail-closed repairs on the
+gate branch. The full draft family is authored at Gate 1 closure from this
+QA-driven specification intent.
+
+Accepted findings converted to repairs so far:
+
+- Supabase `redirect_to` law: GoTrue validates the Auth redirect allow-list by
+  exact string match, so `redirect_to` must stay query-free. The post-auth
+  destination travels through origin-local storage
+  (`uapi/lib/supabase-auth-redirect.ts`) and is consumed once by the callback.
+  This repaired wallet sign-in from both localhost and production www, which
+  previously stranded the PKCE verifier and never minted a session.
+- Identity-derived wallet binding: the canonical wallet sign-up signs on the
+  OAuth provider authorize page, so nothing is staged client-side to replay.
+  `/api/wallet/authenticate` now derives the binding server-side from the
+  session's GoTrue-verified `custom:bitcode-bitcoin` identity
+  (`source: 'oauth-identity'`), and `WalletSessionPersistenceBridge` triggers
+  it whenever a wallet-backed session has no replayable local proof.
+- Post-auth landing is `/packs`, not the legacy `/terminal` overlay route.
+
+Specification intent surfaced for the eventual V48 family (decisions, not yet
+law): eradicate legacy email/phone authentication residue (`/login`,
+`LoginForm`, PhoneSSO) and the legacy `/terminal` route after verifying its
+capabilities ported to `/packs`, `/read`, and `/deposit`; decide the
+solo-operator organization-authority posture (personal-organization bootstrap
+at wallet sign-up versus a neutral unconfigured state); complete the GitHub
+App sessionless install staging path, whose pending-installation cookie
+currently has no consumer.
+
 ## Non-goals during V48 opening
 
 - Do not implement V48 product behavior from this notes-only opening.

BITCODE_V48_QA.md

@@ -9,8 +9,8 @@
  * purpose: Create type-safe agent executors
  * pattern: factory-functions
  */
-import { Executor } from '@bitcode/execution-generics';
-import { Execution } from '@bitcode/execution-generics/Execution';
+import type { Executor } from '@bitcode/execution-generics';
+import type { Execution } from '@bitcode/execution-generics/Execution';
 import { Agent, AgentStep } from '../types';
 import { z } from 'zod';
 export type BitcodePTRRStepName = 'plan' | 'try' | 'refine' | 'retry';
@@ -120,7 +120,6 @@ export declare function factoryAgentWithPTRRGenerations<TInput, TOutput>(config:
         backoff?: number;
     };
 }): Agent<TInput, TOutput>;
-export {};
 /**
  * factoryQuickAgent - Preferred minimal agent for simple, single-step behaviors.
  *
@@ -136,3 +135,4 @@ export declare function factoryQuickAgent<TInput, TOutput>(config: {
     description?: string;
     execute: (input: TInput, execution: Execution) => Promise<TOutput>;
 }): Executor<TInput, TOutput>;
+export {};

packages/agent-generics/src/agents/factories.d.ts

@@ -1,4 +1,4 @@
-import { Execution } from '@bitcode/execution-generics/Execution';
+import type { Execution } from '@bitcode/execution-generics/Execution';
 export declare function logLLMSubstepStart(execution: Execution, sequence: string, systemPrompt: string, userPrompt: string, combinedPrompt: string, llmConfig?: {
     model?: string;
     provider?: string;

packages/agent-generics/src/diagnostics/instrumentation.d.ts

@@ -1,4 +1,4 @@
-import { Execution } from '@bitcode/execution-generics/Execution';
+import type { Execution } from '@bitcode/execution-generics/Execution';
 export interface ExecutionTraceNode {
     id: string;
     type: 'agent' | 'step' | 'substep' | 'execution';

packages/agent-generics/src/diagnostics/trace.d.ts

@@ -8,7 +8,7 @@
  * The 7-substep sequence:
  * 1. PrepareConciseContext (CONTEXT SIGNAL/NOISE) → Reason→Judge→StructuredOutput
  * 2. ChunkThenSum (BIG INPUT) → Reason→Judge→StructuredOutput
- * 3. StitchUntilComplete (CONVERSATIONSUTPUT) → Reason→Judge→StructuredOutput
+ * 3. StitchUntilComplete (large output handling) → Reason→Judge→StructuredOutput
  * 4. Tool execution (AFTER all failsafes, conditional on reasoning + judgment output)
  */
 import { Executor } from '@bitcode/execution-generics';

packages/agent-generics/src/steps/factories.d.ts

@@ -1,5 +1,5 @@
-import { Executor } from '@bitcode/execution-generics';
-import { Execution } from '@bitcode/execution-generics/Execution';
+import type { Executor } from '@bitcode/execution-generics';
+import type { Execution } from '@bitcode/execution-generics/Execution';
 import { SubStepExecution } from '../execution';
 import { z } from 'zod';
 import { PreparedContext, Reasoning, UseTool, Judgment, UsedTool } from '../types';

packages/agent-generics/src/substeps/factories.d.ts

@@ -5,7 +5,7 @@
  * Agents organize Actions, Actions sequence Steps, Steps sequence GenerationSteps.
  */
 export type { PreparedContext } from '@bitcode/context';
-import { Executor } from '@bitcode/execution-generics';
+import type { Executor } from '@bitcode/execution-generics';
 import { Tool } from '@bitcode/tools-generics';
 /**
  * Agent Variation Steps - The four fundamental steps
@@ -111,7 +111,7 @@ export type StepExecutor<TInput = any, TOutput = any> = Executor<TInput, TOutput
 /**
  * AgentGeneration - Preferred alias for AgentStep. A Generation is a typed
  * executor (input → output) that may be composed by PTRR failsafes and tools
-     * postprocess. AgentStep remains the concrete execution shape.
+ * postprocess. AgentStep remains the concrete execution shape.
  */
 export type AgentGeneration<TInput = any, TOutput = any> = AgentStep<TInput, TOutput>;
 /**

packages/agent-generics/src/types.d.ts

@@ -1465,7 +1465,7 @@ export function buildOrganizationPolicyAuthority(input: {
         readString(profile?.multiSigPolicyRoot) ??
         null,
     },
-    recoveryRoute: '/terminal?auxillary-open-to=profile',
+    recoveryRoute: '/packs?auxillary-open-to=profile',
   });
 }
 
@@ -1498,7 +1498,7 @@ export function buildAuxillariesReadinessDiagnostics(input: {
         severity: readiness.connected ? 'warning' : 'blocking',
         summary: `${readiness.provider} provider readiness requires repair.`,
         requiredAction: readiness.requiredRepairAction,
-        repairRoute: '/terminal?auxillary-open-to=externals',
+        repairRoute: '/packs?auxillary-open-to=externals',
         retryPolicy: 'after_repair',
       }));
     }
@@ -1511,7 +1511,7 @@ export function buildAuxillariesReadinessDiagnostics(input: {
       severity: 'blocking',
       summary: 'Wallet binding is missing for settlement-adjacent support actions.',
       requiredAction: 'Connect and verify a Bitcoin wallet.',
-      repairRoute: '/terminal?auxillary-open-to=wallet',
+      repairRoute: '/packs?auxillary-open-to=wallet',
       retryPolicy: 'after_repair',
     }));
   } else if (!input.walletBtdPaneState.signerPosture.ready) {
@@ -1521,7 +1521,7 @@ export function buildAuxillariesReadinessDiagnostics(input: {
       severity: 'warning',
       summary: 'Wallet binding exists but signer posture is not verified.',
       requiredAction: input.walletBtdPaneState.signerPosture.requiredAction,
-      repairRoute: '/terminal?auxillary-open-to=wallet',
+      repairRoute: '/packs?auxillary-open-to=wallet',
       retryPolicy: 'after_repair',
     }));
   }
@@ -1534,7 +1534,7 @@ export function buildAuxillariesReadinessDiagnostics(input: {
       severity: 'warning',
       summary: `${blockedInterface.interfaceId} is not admitted for the requested support surface.`,
       requiredAction: blockedInterface.blockers.join(', ') || 'Review interface policy.',
-      repairRoute: '/terminal?auxillary-open-to=interfaces',
+      repairRoute: '/packs?auxillary-open-to=interfaces',
       retryPolicy: 'after_repair',
     }));
   }
@@ -1546,7 +1546,7 @@ export function buildAuxillariesReadinessDiagnostics(input: {
       severity: 'warning',
       summary: 'Organization authority is not admitted for settlement-adjacent actions.',
       requiredAction: 'Review organization role, grants, and wallet binding.',
-      repairRoute: '/terminal?auxillary-open-to=profile',
+      repairRoute: '/packs?auxillary-open-to=profile',
       retryPolicy: 'after_repair',
     }));
   }
@@ -2048,7 +2048,7 @@ function buildProfileCompletenessIssue(input: {
   const repairRoute: AuxillariesProfileRepairRoute = {
     issueId: input.id,
     pane: input.pane,
-    route: `/terminal?auxillary-open-to=${input.pane}`,
+    route: `/packs?auxillary-open-to=${input.pane}`,
     label: input.label,
     retryPolicy: 'after_repair',
   };

packages/api/src/routes/auxillaries-contract.ts

@@ -25,5 +25,5 @@ export declare function prepareContextForPrompt(context?: GlobalContext): {
     branch: string;
     commit: string;
     task: string;
-    otfInstructions: any[] | undefined;
+    otfInstructions: any[];
 };