@kognai/orchestrator-core 0.1.4 → 0.2.0

package/dist/lib/citizenship.d.ts

@@ -27,6 +27,79 @@ export interface KopusConfig {
  *  prefix and its own rollNumber sequence inside the shared registry.
  *  Add new companies here as they come online (Achiri, SCS-001, DRI, ...). */
 export declare const COMPANY_PREFIXES: Record<string, string>;
+/**
+ * Who a spawned citizen *belongs to* — its lineage. SAF derives this from the
+ * spawn requester's DID so a new citizen inherits the requester's identity:
+ *   - `company`  internal product (kognai/voxight/invoica/kreativ/achiri/…). A
+ *                product CEO's spawn belongs to that company → `did:kognai:{company}:{agent}`.
+ *   - `external` an outside org (through the AMD-23 Cerberus airlock) →
+ *                `did:external:{org}:{agent}`.
+ *   - `user`     a human's wallet in the citizen journey. **Exactly ONE agent per
+ *                user per wallet** → `did:kognai:citizen:{wallet}`.
+ *   - `scs`      a Self-Committed Swarm a user's citizen forms. Sub-agents the
+ *                citizen spawns inherit the swarm's id → `did:kognai:scs:{scsId}:{agent}`.
+ */
+export type CitizenOwnerKind = 'company' | 'external' | 'user' | 'scs';
+export interface CitizenOwner {
+    kind: CitizenOwnerKind;
+    /** company name | external org id | user wallet | scs id. */
+    id: string;
+}
+/** The Default Instrumentation Posture (TICKET-150 / SOP-GEN-014) carried per
+ *  citizen: KSL monitoring + failure-log contribution + skill-bank participation. */
+export interface CitizenInstrumentation {
+    ksl: boolean;
+    failure_log: boolean;
+    skill_bank: boolean;
+}
+/**
+ * Posture by owner kind. **Internal** citizens (kognai + product companies) are
+ * born fully instrumented and bound to all constitutional duties — ON, mandatory.
+ * **External** orgs/swarms and **user** citizens (+ the SCS they form) get the
+ * same machinery baseline-available but OFF; they opt in (see citizenBenefits)
+ * for fee discounts and, for users, the improvement loop.
+ */
+export declare function defaultInstrumentation(owner_kind?: CitizenOwnerKind): CitizenInstrumentation;
+/** Kognai-fee discount (%) granted per shared channel an opt-in citizen enables.
+ *  Tunable Founder policy. */
+export declare const SHARE_DISCOUNT_PCT: {
+    failure_log: number;
+    skill_bank: number;
+};
+export interface CitizenBenefits {
+    /** % off Kognai fees for opting into sharing (external + user + scs). */
+    fee_discount_pct: number;
+    /** Users (+ their SCS) who share skills may use the skill bank for free. */
+    skill_bank_free_use: boolean;
+    /** Users (+ their SCS) who share failures get Plumber review of their work,
+     *  driven by failure-library findings. */
+    plumber_review: boolean;
+}
+/**
+ * Resolve the economic + improvement-loop benefits a citizen unlocks from its
+ * current instrumentation. Internal citizens are first-party (mandatory posture,
+ * no discount concept). External/user/scs earn a fee discount per shared channel;
+ * users (+ their SCS) additionally unlock free skill-bank use + Plumber review.
+ */
+export declare function citizenBenefits(c: Pick<CitizenRecord, 'owner_kind' | 'instrumentation'>): CitizenBenefits;
+/** Apply a citizen's earned discount to a Kognai fee (atomic units). */
+export declare function applyCitizenDiscount(feeAtomic: number, c: Pick<CitizenRecord, 'owner_kind' | 'instrumentation'>): number;
+/** Skill-bank gate: may this citizen draw from the skill bank for free? */
+export declare function canUseSkillBankFree(c: Pick<CitizenRecord, 'owner_kind' | 'instrumentation'>): boolean;
+/** Plumber gate: is this citizen's work eligible for failure-log-driven Plumber review? */
+export declare function eligibleForPlumberReview(c: Pick<CitizenRecord, 'owner_kind' | 'instrumentation'>): boolean;
+/**
+ * Resolve an agent's canonical *instance* identity (DID + citizen_id) from the
+ * registry — the key failure-logging / KSL / SCORE must attribute to, instead of
+ * the role string (the TICKET-152 `agent_id="coder"` corruption). Returns null
+ * when the agent has no citizen record.
+ */
+export declare function identityFor(agent_name: string, company?: string): {
+    agent_did: string;
+    citizen_id: string;
+    owner_kind?: CitizenOwnerKind;
+    owner_id?: string;
+} | null;
 export interface CitizenRecord {
     /** Stable identifier. For company-scoped mints: `{PREFIX}-{rollNumber padded 4}`
      *  (e.g. `VXG-0042`). For legacy/Kognai-internal mints (no `company`):
@@ -39,12 +112,24 @@ export interface CitizenRecord {
     /** Agent slug (matches agents/<name>/ dir within the owning company). */
     agent_name: string;
     /** Owning company. Defaults to 'kognai' for legacy records that predate the
-     *  multi-company extension. Idempotency key is `(agent_name, company)`. */
+     *  multi-company extension. Idempotency key is `(agent_name, company)`.
+     *  Set only when owner_kind === 'company' (back-compat alias for owner_id). */
     company?: string;
+    /** Lineage owner kind — who this citizen belongs to (see CitizenOwner). */
+    owner_kind?: CitizenOwnerKind;
+    /** Lineage owner id — company name | external org | user wallet | scs id. */
+    owner_id?: string;
+    /** Default Instrumentation Posture (KSL / failure-log / skill-bank). Internal
+     *  citizens = all ON (mandatory); external/user/scs = baseline OFF, opt-in. */
+    instrumentation?: CitizenInstrumentation;
     /** DID for SCORE / ERC-8004 reputation tracking. Company-scoped form:
      *  `did:kognai:{company}:{agent_name}`. Legacy form (no company in path)
      *  is `did:kognai:{agent_name}`. */
     agent_did: string;
+    /** Prior DID a citizen carried before a company-scoped re-mint (e.g. legacy
+     *  `did:kognai:{agent}`). Preserved so SCORE / ERC-8004 reputation history
+     *  keyed on the old DID isn't orphaned by the migration. */
+    legacy_did?: string;
     /** ISO-8601 mint timestamp. */
     mintedAt: string;
     /** New citizens start at Tier I; promotion is constitutional. */
@@ -82,12 +167,14 @@ export declare function mintCitizen(agent_name: string, opts?: {
     tier?: CitizenTier;
     citizen_type?: CitizenType;
     now?: Date;
-    /** Owning company. When provided, the mint uses company-scoped roll
-     *  numbers (separate sequence per company), the `{PREFIX}-{rollNum padded}`
-     *  citizen_id format, and the `did:kognai:{company}:{agent_name}` DID
-     *  form. When omitted, behaves exactly as before (legacy Kognai-internal
-     *  path: random hex citizen_id, global rollNumber sequence). */
+    /** @deprecated prefer `owner: { kind:'company', id }`. Owning company —
+     *  back-compat alias that maps to owner kind 'company'. */
     company?: string;
+    /** Lineage owner — who the citizen belongs to. SAF derives this from the
+     *  spawn requester's DID so the new citizen inherits the requester's
+     *  identity (company / external org / user wallet / SCS). When omitted
+     *  (and no `company`), uses the legacy Kognai-internal path. */
+    owner?: CitizenOwner;
 }): CitizenRecord;
 /** Lookup an existing citizen by (agent_name, company). Returns null when
  *  no match. Treats undefined company as 'kognai' for legacy compatibility. */

package/dist/lib/citizenship.js

@@ -17,7 +17,13 @@
  * Stdlib only. No LLM, no network. Pure issuance.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COMPANY_PREFIXES = void 0;
+exports.SHARE_DISCOUNT_PCT = exports.COMPANY_PREFIXES = void 0;
+exports.defaultInstrumentation = defaultInstrumentation;
+exports.citizenBenefits = citizenBenefits;
+exports.applyCitizenDiscount = applyCitizenDiscount;
+exports.canUseSkillBankFree = canUseSkillBankFree;
+exports.eligibleForPlumberReview = eligibleForPlumberReview;
+exports.identityFor = identityFor;
 exports.mintCitizen = mintCitizen;
 exports.lookupCitizen = lookupCitizen;
 exports.renderCitizenYaml = renderCitizenYaml;
@@ -41,7 +47,84 @@ exports.COMPANY_PREFIXES = {
     kognai: 'KGN',
     voxight: 'VXG',
     invoica: 'INV',
+    kreativ: 'KRV', // Kognai Kreativ — SCS001 → creative studio (TICKET-158/306)
+    scs001: 'SCS', // legacy content swarm; folds into Kreativ as agents migrate
+    achiri: 'ACH', // Tunisia AI companion
+    asterpay: 'APY', // payments product
+    dri: 'DRI', // Dynamic Research Instrument (Phase 3)
 };
+/** citizen_id prefixes for the non-company owner kinds (company uses COMPANY_PREFIXES).
+ *  These use a GLOBAL per-kind roll sequence; the specific owner lives in the DID. */
+const OWNER_PREFIX = {
+    external: 'EXT',
+    user: 'CIT',
+    scs: 'SWM',
+};
+/**
+ * Posture by owner kind. **Internal** citizens (kognai + product companies) are
+ * born fully instrumented and bound to all constitutional duties — ON, mandatory.
+ * **External** orgs/swarms and **user** citizens (+ the SCS they form) get the
+ * same machinery baseline-available but OFF; they opt in (see citizenBenefits)
+ * for fee discounts and, for users, the improvement loop.
+ */
+function defaultInstrumentation(owner_kind) {
+    const internal = !owner_kind || owner_kind === 'company';
+    return { ksl: internal, failure_log: internal, skill_bank: internal };
+}
+/** Kognai-fee discount (%) granted per shared channel an opt-in citizen enables.
+ *  Tunable Founder policy. */
+exports.SHARE_DISCOUNT_PCT = { failure_log: 10, skill_bank: 10 };
+/**
+ * Resolve the economic + improvement-loop benefits a citizen unlocks from its
+ * current instrumentation. Internal citizens are first-party (mandatory posture,
+ * no discount concept). External/user/scs earn a fee discount per shared channel;
+ * users (+ their SCS) additionally unlock free skill-bank use + Plumber review.
+ */
+function citizenBenefits(c) {
+    const i = c.instrumentation ?? defaultInstrumentation(c.owner_kind);
+    const optInEligible = c.owner_kind === 'external' || c.owner_kind === 'user' || c.owner_kind === 'scs';
+    const isUser = c.owner_kind === 'user' || c.owner_kind === 'scs';
+    let discount = 0;
+    if (optInEligible) {
+        if (i.failure_log)
+            discount += exports.SHARE_DISCOUNT_PCT.failure_log;
+        if (i.skill_bank)
+            discount += exports.SHARE_DISCOUNT_PCT.skill_bank;
+    }
+    return {
+        fee_discount_pct: discount,
+        skill_bank_free_use: isUser && i.skill_bank,
+        plumber_review: isUser && i.failure_log,
+    };
+}
+// ─── citizenBenefits consumers (billing / skill-bank / plumber) ─────────────────
+// The integration surface for downstream systems. They call these instead of
+// re-deriving policy, so the discount/free-use/review rules live in one place.
+/** Apply a citizen's earned discount to a Kognai fee (atomic units). */
+function applyCitizenDiscount(feeAtomic, c) {
+    const pct = citizenBenefits(c).fee_discount_pct;
+    return Math.max(0, Math.round(feeAtomic * (1 - pct / 100)));
+}
+/** Skill-bank gate: may this citizen draw from the skill bank for free? */
+function canUseSkillBankFree(c) {
+    return citizenBenefits(c).skill_bank_free_use;
+}
+/** Plumber gate: is this citizen's work eligible for failure-log-driven Plumber review? */
+function eligibleForPlumberReview(c) {
+    return citizenBenefits(c).plumber_review;
+}
+/**
+ * Resolve an agent's canonical *instance* identity (DID + citizen_id) from the
+ * registry — the key failure-logging / KSL / SCORE must attribute to, instead of
+ * the role string (the TICKET-152 `agent_id="coder"` corruption). Returns null
+ * when the agent has no citizen record.
+ */
+function identityFor(agent_name, company) {
+    const c = lookupCitizen({ agent_name, company });
+    if (!c)
+        return null;
+    return { agent_did: c.agent_did, citizen_id: c.citizen_id, owner_kind: c.owner_kind, owner_id: c.owner_id };
+}
 // ─── Public API ───────────────────────────────────────────────────────────────
 /**
  * Mint a new citizen. Assigns ID + roll number, writes the registry
@@ -65,26 +148,49 @@ function mintCitizen(agent_name, opts = {}) {
     // is a denormalized index that should always be derivable from them.
     reconcileFromDisk();
     const registry = readRegistry();
-    // Idempotency: lookup by (agent_name, company). Treat undefined company as
-    // 'kognai' so existing records (which predate the company field) match
-    // mints that explicitly target the kognai company.
-    const companyKey = opts.company; // undefined for legacy path
-    const existing = registry.citizens.find((c) => c.agent_name === agent_name && (c.company ?? 'kognai') === (companyKey ?? 'kognai'));
+    // Resolve lineage. `owner` wins; `company` is the back-compat alias; neither
+    // → legacy kognai-internal path (random hex id, global roll, did:kognai:{agent}).
+    const owner = opts.owner ?? (opts.company ? { kind: 'company', id: opts.company } : null);
+    // Idempotency. user → exactly ONE per wallet (key on owner_id only, ignoring
+    // agent_name — a wallet has a single citizen). company/external/scs →
+    // (agent_name, kind, owner_id). legacy → (agent_name, company='kognai').
+    const ownerIdOf = (c) => c.owner_id ?? c.company ?? 'kognai';
+    // Legacy records (no owner_kind) are company-scoped (kognai by default).
+    const ownerKindOf = (c) => c.owner_kind ?? 'company';
+    const existing = registry.citizens.find((c) => {
+        if (owner?.kind === 'user')
+            return c.owner_kind === 'user' && c.owner_id === owner.id;
+        if (owner)
+            return c.agent_name === agent_name && ownerKindOf(c) === owner.kind && ownerIdOf(c) === owner.id;
+        return c.agent_name === agent_name && (c.company ?? 'kognai') === 'kognai';
+    });
     if (existing)
         return existing;
     const now = opts.now ?? new Date();
     let citizen_id;
     let rollNumber;
     let agent_did;
-    if (companyKey) {
-        // Company-scoped path: per-company rollNumber, prefixed ID, scoped DID.
-        const prefix = exports.COMPANY_PREFIXES[companyKey] ?? companyKey.slice(0, 3).toUpperCase();
-        const companyRolls = registry.citizens
-            .filter((c) => (c.company ?? 'kognai') === companyKey)
+    if (owner?.kind === 'company') {
+        // Per-company rollNumber, COMPANY_PREFIXES id, did:kognai:{company}:{agent}.
+        const prefix = exports.COMPANY_PREFIXES[owner.id] ?? owner.id.slice(0, 3).toUpperCase();
+        const rolls = registry.citizens
+            .filter((c) => ownerKindOf(c) === 'company' && ownerIdOf(c) === owner.id)
             .map((c) => c.rollNumber);
-        rollNumber = companyRolls.length > 0 ? Math.max(...companyRolls) + 1 : 1;
+        rollNumber = rolls.length ? Math.max(...rolls) + 1 : 1;
         citizen_id = `${prefix}-${String(rollNumber).padStart(4, '0')}`;
-        agent_did = `did:kognai:${companyKey}:${agent_name}`;
+        agent_did = `did:kognai:${owner.id}:${agent_name}`;
+    }
+    else if (owner) {
+        // user / scs / external — GLOBAL per-kind roll; the specific owner lives in
+        // the DID. user: 1 per wallet → did:kognai:citizen:{wallet}.
+        const prefix = OWNER_PREFIX[owner.kind];
+        const rolls = registry.citizens.filter((c) => c.owner_kind === owner.kind).map((c) => c.rollNumber);
+        rollNumber = rolls.length ? Math.max(...rolls) + 1 : 1;
+        citizen_id = `${prefix}-${String(rollNumber).padStart(4, '0')}`;
+        agent_did =
+            owner.kind === 'user' ? `did:kognai:citizen:${owner.id}`
+                : owner.kind === 'scs' ? `did:kognai:scs:${owner.id}:${agent_name}`
+                    : `did:external:${owner.id}:${agent_name}`;
     }
     else {
         // Legacy Kognai-internal path: random hex ID + global rollNumber sequence.
@@ -96,7 +202,11 @@ function mintCitizen(agent_name, opts = {}) {
         citizen_id,
         rollNumber,
         agent_name,
-        ...(companyKey ? { company: companyKey } : {}),
+        ...(owner?.kind === 'company' ? { company: owner.id } : {}),
+        ...(owner ? { owner_kind: owner.kind, owner_id: owner.id } : {}),
+        // Every minted citizen carries the posture: internal ON, external/user/scs
+        // baseline-OFF (opt-in). KSL/failure-log/skill-bank + duties wire from this.
+        instrumentation: defaultInstrumentation(owner?.kind),
         agent_did,
         mintedAt: now.toISOString(),
         tier: opts.tier ?? 'I',
@@ -112,9 +222,9 @@ function mintCitizen(agent_name, opts = {}) {
     };
     registry.citizens.push(record);
     registry.total = registry.citizens.length;
-    // Only advance the global next_roll_number on legacy mints — company-scoped
-    // mints have their own per-company counter computed at mint time.
-    if (!companyKey)
+    // Advance the global next_roll_number only on the legacy path; owner-scoped
+    // mints compute their own roll at mint time.
+    if (!owner)
         registry.next_roll_number = rollNumber + 1;
     writeRegistry(registry);
     return record;
@@ -138,14 +248,17 @@ function renderCitizenYaml(c) {
 citizen_id: ${c.citizen_id}
 rollNumber: ${c.rollNumber}
 agent_name: ${c.agent_name}
-agent_did: ${c.agent_did}
-mintedAt: "${c.mintedAt}"
+${c.owner_kind ? `owner_kind: ${c.owner_kind}\n` : ''}${c.owner_id ? `owner_id: ${c.owner_id}\n` : ''}${c.company ? `company: ${c.company}\n` : ''}agent_did: ${c.agent_did}
+${c.legacy_did ? `legacy_did: ${c.legacy_did}\n` : ''}mintedAt: "${c.mintedAt}"
 tier: ${c.tier}
 citizen_type: ${c.citizen_type}
 mascot:
   hue: ${c.mascot.hue}
   state: ${c.mascot.state}
 reputation: ${c.reputation}
+instrumentation_ksl: ${c.instrumentation?.ksl ?? true}
+instrumentation_failure_log: ${c.instrumentation?.failure_log ?? true}
+instrumentation_skill_bank: ${c.instrumentation?.skill_bank ?? true}
 founding_agent: ${c.founding_agent ?? 'ceo'}
 proposing_agent: ${c.proposing_agent ?? 'cto'}
 ${c.origin_proposal_id ? `origin_proposal_id: ${c.origin_proposal_id}\n` : ''}`;
@@ -256,7 +369,11 @@ function parseCitizenYaml(raw) {
         citizen_id: flat.citizen_id,
         rollNumber: parseInt(flat.rollNumber, 10),
         agent_name: flat.agent_name,
+        ...(flat.company ? { company: flat.company } : {}),
+        ...(flat.owner_kind ? { owner_kind: flat.owner_kind } : {}),
+        ...(flat.owner_id ? { owner_id: flat.owner_id } : {}),
         agent_did: flat.agent_did || `did:kognai:${flat.agent_name}`,
+        ...(flat.legacy_did ? { legacy_did: flat.legacy_did } : {}),
         mintedAt: flat.mintedAt,
         tier: flat.tier || 'I',
         citizen_type: flat.citizen_type || 'spawned',
@@ -265,6 +382,13 @@ function parseCitizenYaml(raw) {
             state: mascot.state || 'idle',
         },
         reputation: flat.reputation ? parseInt(flat.reputation, 10) : 50,
+        instrumentation: flat.instrumentation_ksl !== undefined
+            ? {
+                ksl: flat.instrumentation_ksl === 'true',
+                failure_log: flat.instrumentation_failure_log === 'true',
+                skill_bank: flat.instrumentation_skill_bank === 'true',
+            }
+            : defaultInstrumentation(flat.owner_kind),
         founding_agent: flat.founding_agent,
         proposing_agent: flat.proposing_agent,
         origin_proposal_id: flat.origin_proposal_id,

package/dist/lib/engine-agents.d.ts

@@ -1,3 +1,4 @@
+import { type CitizenOwner } from './citizenship';
 import type { AgentTask, ReviewResult, CTOProposal, CTOReport } from './orchestrate-engine';
 export declare class SupervisorAgent {
     private systemPrompt;
@@ -62,6 +63,12 @@ export interface SpawnGateResult {
     pending_approval?: boolean;
     /** Optional one-line audit string logged on an approved decision. */
     audit?: string;
+    /** Lineage owner the gate resolved from the spawn requester (via SAF /
+     *  deriveOwner). When set, the engine mints the citizen owner-scoped instead
+     *  of legacy — so an Invoica swarm's spawn becomes an Invoica citizen, a
+     *  Voxight swarm's a Voxight citizen, etc. The running company is carried by
+     *  the template-injected gate's requester_did, not hardcoded in the engine. */
+    owner?: CitizenOwner;
 }
 export type SpawnGate = (spec: AgentSpawnSpec) => SpawnGateResult;
 export declare class AgentCreator {

package/dist/lib/engine-agents.js

@@ -45,7 +45,7 @@ class SupervisorAgent {
             : '';
         // Sherlock v2: inject ASMR episodic memory context (AMD-21-03) — fail-open
         const memoryContext = await (0, sherlock_memory_1.getSherlockMemoryContext)(task.context || task.id);
-        const userPrompt = `Review the following code generated for task ${task.id}.\n\n## Task Spec\n${task.context}${memoryContext}\n\n## Generated Files (${files.length})\n${fileContents}${integrityContext}\n\n## Pre-computed Fence Check (authoritative — do NOT infer from display format)\n${fenceCheckLines}\n\n## Instructions\nCRITICAL CHECK: Use the Pre-computed Fence Check above. If any file shows FENCE DETECTED, REJECT. Do NOT infer fence presence from the <file_content> display tags — those are display-only wrappers.\nAlso check: Did the file lose existing functionality? If a file shrank significantly, REJECT.\n\n## Categorical grade (use a discrete letter — no fake precision)\n- A: production-perfect. No improvements possible. Ship.\n- B: good with minor polish needed (rename, comment, formatting).\n- C: works but has noticeable issues (missed edge case, weak abstraction, partial spec coverage). APPROVED with caveats.\n- D: significant problems (broken edge case, regression risk, anti-pattern). REJECT.\n- F: broken, unsafe, doesn't meet spec, or fence/integrity failure. REJECT.\n\nThe deterministic gate already ran (typecheck + structural). If a file got here, syntax is valid — focus your review on substance, not parseability.\n\nRespond with a JSON object:\n{\n  "verdict": "APPROVED" or "REJECTED",\n  "grade": "A" | "B" | "C" | "D" | "F",\n  "score_rationale": "ONE sentence naming the specific factor that determined the grade. Vague 'good code' is NOT acceptable.",\n  "summary": "brief review summary",\n  "issues": [{"severity": "critical|high|medium|low", "file": "path", "description": "..."}],\n  "strengths": ["..."]\n}`;
+        const userPrompt = `Review the following code generated for task ${task.id}.\n\n## Task Spec\n${task.context}${memoryContext}\n\n## Generated Files (${files.length})\n${fileContents}${integrityContext}\n\n## Pre-computed Fence Check (authoritative — do NOT infer from display format)\n${fenceCheckLines}\n\n## YOUR REVIEW LENS — Specification & Integration (this is your ONLY job)\nYou are ONE of two INDEPENDENT reviewers. Judge ONLY: (1) SPEC COVERAGE — every required export/function/behavior is present and matches the task spec; REJECT if partial, stubbed, or TODO. (2) INTEGRATION — imports resolve to real files/symbols, types and contracts match the files this depends on, and referenced files exist. Do NOT base your grade on security or runtime concerns — the other reviewer owns those. This file passes your lens only if it is spec-complete AND integrates cleanly.\n\n## Instructions\nCRITICAL CHECK: Use the Pre-computed Fence Check above. If any file shows FENCE DETECTED, REJECT. Do NOT infer fence presence from the <file_content> display tags — those are display-only wrappers.\nAlso check: Did the file lose existing functionality? If a file shrank significantly, REJECT.\n\n## Categorical grade (use a discrete letter — no fake precision)\n- A: production-perfect. No improvements possible. Ship.\n- B: good with minor polish needed (rename, comment, formatting).\n- C: works but has noticeable issues (missed edge case, weak abstraction, partial spec coverage). APPROVED with caveats.\n- D: significant problems (broken edge case, regression risk, anti-pattern). REJECT.\n- F: broken, unsafe, doesn't meet spec, or fence/integrity failure. REJECT.\n\nThe deterministic gate already ran (typecheck + structural). If a file got here, syntax is valid — focus your review on substance, not parseability.\n\nRespond with a JSON object:\n{\n  "verdict": "APPROVED" or "REJECTED",\n  "grade": "A" | "B" | "C" | "D" | "F",\n  "score_rationale": "ONE sentence naming the specific factor that determined the grade. Vague 'good code' is NOT acceptable.",\n  "summary": "brief review summary",\n  "issues": [{"severity": "critical|high|medium|low", "file": "path", "description": "..."}],\n  "strengths": ["..."]\n}`;
         const startTime = Date.now();
         // B.15: DeepSeek via ClawRouter for standard tasks (~$0.02/task vs $0.07 dual-supervisor)
         // Retain Claude Sonnet only for audit/refactor-complex (high-stakes)
@@ -115,7 +115,7 @@ class Supervisor2Agent {
         const integrityContext2 = task._integrityFailed
             ? `\n\n## ⚠️ INTEGRITY ALERT\n${task._integrityDetails}\nThis file was flagged for destructive rewrite. The original was preserved. REJECT this task.\n`
             : '';
-        const userPrompt = `Review the following code generated for task ${task.id}.\n\n## Task Spec\n${task.context}\n\n## Generated Files (${files.length})\n${fileContents}${integrityContext2}\n\n## Pre-computed Fence Check (authoritative — do NOT infer from display format)\n${fenceCheckLines2}\n\n## Instructions\nCRITICAL CHECK: Use the Pre-computed Fence Check above. If any file shows FENCE DETECTED, REJECT. Do NOT infer fence presence from the <file_content> display tags — those are display-only wrappers.\nAlso check: Did the file lose existing functionality? If a file shrank significantly, REJECT.\n\n## Categorical grade (use a discrete letter — no fake precision)\n- A: production-perfect. No improvements possible. Ship.\n- B: good with minor polish needed (rename, comment, formatting).\n- C: works but has noticeable issues (missed edge case, weak abstraction, partial spec coverage). APPROVED with caveats.\n- D: significant problems (broken edge case, regression risk, anti-pattern). REJECT.\n- F: broken, unsafe, doesn't meet spec, or fence/integrity failure. REJECT.\n\nThe deterministic gate already ran (typecheck + structural). If a file got here, syntax is valid — focus your review on substance, not parseability.\n\nRespond with a JSON object:\n{\n  "verdict": "APPROVED" or "REJECTED",\n  "grade": "A" | "B" | "C" | "D" | "F",\n  "score_rationale": "ONE sentence naming the specific factor that determined the grade. Vague 'good code' is NOT acceptable.",\n  "summary": "brief review summary",\n  "issues": [{"severity": "critical|high|medium|low", "file": "path", "description": "..."}],\n  "strengths": ["..."]\n}`;
+        const userPrompt = `Review the following code generated for task ${task.id}.\n\n## Task Spec\n${task.context}\n\n## Generated Files (${files.length})\n${fileContents}${integrityContext2}\n\n## Pre-computed Fence Check (authoritative — do NOT infer from display format)\n${fenceCheckLines2}\n\n## YOUR REVIEW LENS — Security & Runtime (this is your ONLY job)\nYou are ONE of two INDEPENDENT reviewers. Judge ONLY: (1) SECURITY — injection, secret/credential leakage, unsafe eval/exec/shell, unsanitized input or output (e.g. innerHTML / unescaped HTML), missing authorization or input validation. (2) RUNTIME ROBUSTNESS — error handling, unhandled rejections, resource leaks, missing timeouts/cancellation, crash-on-bad-input. Do NOT re-judge spec completeness — the other reviewer owns that. This file passes your lens only if it is secure AND runtime-robust.\n\n## Instructions\nCRITICAL CHECK: Use the Pre-computed Fence Check above. If any file shows FENCE DETECTED, REJECT. Do NOT infer fence presence from the <file_content> display tags — those are display-only wrappers.\nAlso check: Did the file lose existing functionality? If a file shrank significantly, REJECT.\n\n## Categorical grade (use a discrete letter — no fake precision)\n- A: production-perfect. No improvements possible. Ship.\n- B: good with minor polish needed (rename, comment, formatting).\n- C: works but has noticeable issues (missed edge case, weak abstraction, partial spec coverage). APPROVED with caveats.\n- D: significant problems (broken edge case, regression risk, anti-pattern). REJECT.\n- F: broken, unsafe, doesn't meet spec, or fence/integrity failure. REJECT.\n\nThe deterministic gate already ran (typecheck + structural). If a file got here, syntax is valid — focus your review on substance, not parseability.\n\nRespond with a JSON object:\n{\n  "verdict": "APPROVED" or "REJECTED",\n  "grade": "A" | "B" | "C" | "D" | "F",\n  "score_rationale": "ONE sentence naming the specific factor that determined the grade. Vague 'good code' is NOT acceptable.",\n  "summary": "brief review summary",\n  "issues": [{"severity": "critical|high|medium|low", "file": "path", "description": "..."}],\n  "strengths": ["..."]\n}`;
         const startTime = Date.now();
         // B.15: Use Haiku for second-pass review — 10x cheaper than Sonnet.
         // Founder directive 2026-05-25: if Anthropic depletes, fall back to ClawRouter/DeepSeek
@@ -199,68 +199,53 @@ async function reconcileSupervisorReviews(review1, review2, task, ceo) {
         return { finalReview: review1, review1, review2, consensus: false, escalatedToCEO: false };
     }
     const bothApproved = review1.verdict === 'APPROVED' && review2.verdict === 'APPROVED';
-    const bothRejected = review1.verdict !== 'APPROVED' && review2.verdict !== 'APPROVED';
-    const consensus = bothApproved || bothRejected;
     if (bothApproved) {
-        // Both approve — take the average score, merge strengths
+        // Both lenses passed — average score, merge strengths.
         const avgScore = Math.round((review1.score + review2.score) / 2);
-        (0, orchestrate_engine_1.log)(orchestrate_engine_1.c.green, `  ✓ DUAL CONSENSUS: Both supervisors APPROVED (Sup1: ${review1.score}, Sup2: ${review2.score}, avg: ${avgScore})`);
+        (0, orchestrate_engine_1.log)(orchestrate_engine_1.c.green, `  ✓ DUAL PASS: both lenses APPROVED — Spec/Integration (${review1.score}) + Security/Runtime (${review2.score}), avg ${avgScore}`);
         return {
             finalReview: {
                 verdict: 'APPROVED',
                 score: avgScore,
-                summary: `Dual-approved: Sup1 (${review1.score}/100) + Sup2 (${review2.score}/100)`,
+                summary: `Both lenses passed: Spec/Integration ${review1.score}/100 + Security/Runtime ${review2.score}/100`,
                 issues: [...review1.issues, ...review2.issues],
                 strengths: Array.from(new Set([...review1.strengths, ...review2.strengths])),
             },
             review1, review2, consensus: true, escalatedToCEO: false,
         };
     }
-    if (bothRejected) {
-        // Both reject — merge issues, take lower score
-        const minScore = Math.min(review1.score, review2.score);
-        (0, orchestrate_engine_1.log)(orchestrate_engine_1.c.red, `  ✗ DUAL CONSENSUS: Both supervisors REJECTED (Sup1: ${review1.score}, Sup2: ${review2.score})`);
-        return {
-            finalReview: {
-                verdict: 'REJECTED',
-                score: minScore,
-                summary: `Dual-rejected: Sup1 (${review1.score}/100) + Sup2 (${review2.score}/100). ${review1.summary} | ${review2.summary}`,
-                issues: [...review1.issues, ...review2.issues],
-                strengths: [],
-            },
-            review1, review2, consensus: true, escalatedToCEO: false,
-        };
-    }
-    // CONFLICT — one approved, one rejected → escalate to CEO
-    const approver = review1.verdict === 'APPROVED' ? 'Sup1' : 'Sup2';
-    const rejecter = review1.verdict === 'APPROVED' ? 'Sup2' : 'Sup1';
-    const approvalReview = review1.verdict === 'APPROVED' ? review1 : review2;
-    const rejectionReview = review1.verdict === 'APPROVED' ? review2 : review1;
-    (0, orchestrate_engine_1.log)(orchestrate_engine_1.c.yellow, `  ⚡ SUPERVISOR CONFLICT on ${task.id}: ${approver} APPROVED (${approvalReview.score}), ${rejecter} REJECTED (${rejectionReview.score})`);
-    (0, orchestrate_engine_1.log)(orchestrate_engine_1.c.magenta, `  → Escalating to CEO for final decision...`);
-    try {
-        const ceoDecision = await ceo.resolveReviewConflict(task, approvalReview, rejectionReview, approver, rejecter);
-        const ceoApproves = ceoDecision.toLowerCase().includes('approve');
-        (0, orchestrate_engine_1.log)(ceoApproves ? orchestrate_engine_1.c.green : orchestrate_engine_1.c.red, `  CEO DECISION: ${ceoApproves ? 'APPROVED' : 'REJECTED'} — ${ceoDecision.substring(0, 200)}`);
-        return {
-            finalReview: {
-                verdict: ceoApproves ? 'APPROVED' : 'REJECTED',
-                score: ceoApproves ? approvalReview.score : rejectionReview.score,
-                summary: `CEO resolved conflict (${approver} approved, ${rejecter} rejected): ${ceoDecision.substring(0, 300)}`,
-                issues: rejectionReview.issues,
-                strengths: approvalReview.strengths,
-            },
-            review1, review2, consensus: false, escalatedToCEO: true, ceoDecision,
-        };
-    }
-    catch (error) {
-        // CEO unavailable — default to rejection (safer)
-        (0, orchestrate_engine_1.log)(orchestrate_engine_1.c.yellow, `  CEO unavailable for conflict resolution: ${error.message}. Defaulting to REJECTED.`);
-        return {
-            finalReview: rejectionReview,
-            review1, review2, consensus: false, escalatedToCEO: false,
-        };
-    }
+    // BOTH-MUST-PASS (gap 3). The two reviewers cover DIFFERENT dimensions
+    // (spec/integration vs security/runtime), so passing one does not excuse
+    // failing the other. Any rejection ⇒ REJECTED. No CEO rescue — a real
+    // security or spec failure must be FIXED, not voted away by a third opinion
+    // that never looked at that dimension. This replaces the old
+    // conflict→CEO-decides path that let a single approval override a rejection.
+    const failedLenses = [];
+    if (review1.verdict !== 'APPROVED')
+        failedLenses.push('Spec/Integration');
+    if (review2.verdict !== 'APPROVED')
+        failedLenses.push('Security/Runtime');
+    const rejectedIssues = [
+        ...(review1.verdict !== 'APPROVED' ? review1.issues : []),
+        ...(review2.verdict !== 'APPROVED' ? review2.issues : []),
+    ];
+    const rejectionSummaries = [review1, review2]
+        .filter((r) => r.verdict !== 'APPROVED')
+        .map((r) => r.summary)
+        .join(' | ');
+    (0, orchestrate_engine_1.log)(orchestrate_engine_1.c.red, `  ✗ REJECTED — failed required lens: ${failedLenses.join(' + ')} (both must pass). Spec/Int ${review1.score}, Sec/RT ${review2.score}`);
+    return {
+        finalReview: {
+            verdict: 'REJECTED',
+            score: Math.min(review1.score, review2.score),
+            summary: `Failed required lens (${failedLenses.join(' + ')}): ${rejectionSummaries}`,
+            issues: rejectedIssues,
+            strengths: [],
+        },
+        review1, review2,
+        consensus: review1.verdict === review2.verdict,
+        escalatedToCEO: false,
+    };
 }
 // ===== CEO Agent (Claude via Anthropic API) =====
 class CEOAgent {
@@ -750,6 +735,7 @@ class AgentCreator {
         // supplied a SpawnGate (Kognai wires SAF here), consult it BEFORE creating
         // anything on disk. Approval/rejection only; the citizenship logic below is
         // unchanged (its extraction is tracked separately as TICKET-226).
+        let spawnOwner;
         if (this.spawnGate) {
             const decision = this.spawnGate(spec);
             if (!decision.approved) {
@@ -764,6 +750,9 @@ class AgentCreator {
             }
             if (decision.audit)
                 (0, orchestrate_engine_1.log)(orchestrate_engine_1.c.gray, `  ✓ ${decision.audit}`);
+            // The gate (SAF) resolves the lineage from its requester_did — this is the
+            // running company's context, plumbed in rather than hardcoded here.
+            spawnOwner = decision.owner;
         }
         const agentDir = `./agents/${spec.name}`;
         (0, fs_1.mkdirSync)(agentDir, { recursive: true });
@@ -771,10 +760,13 @@ class AgentCreator {
         // citizen — not a bare agent. Mint citizenship (citizen_id + roll
         // number + Kōpus avatar + ACP baseline) BEFORE writing the agent
         // files so the citizen record can be referenced in the prompt.
+        // Owner-scoped when the gate supplied a lineage (e.g. invoica/voxight);
+        // legacy kognai-internal path otherwise (back-compat for gate-less templates).
         const citizen = (0, citizenship_1.mintCitizen)(spec.name, {
             founding_agent: 'ceo',
             proposing_agent: 'cto',
             citizen_type: 'spawned',
+            owner: spawnOwner,
         });
         // Write agent.yaml
         const yaml = `name: ${spec.name}

package/dist/lib/sovereign-agent-factory.d.ts

@@ -17,6 +17,7 @@
  *   1. KSL record (spawn_request + spawn_decision)
  *   2. Voxight market intelligence signal (spawn classification = demand signal)
  */
+import { type CitizenOwner, type CitizenRecord } from './citizenship';
 /** All possible classifications for a spawn request. */
 export type SpawnClass = 'UTILITY' | 'SPECIALIST' | 'CITIZEN' | 'EXTERNAL' | 'PRIME';
 export type GovernancePath = 'auto' | 'ceo_review' | 'cto_review' | 'founder_required' | 'blocked';
@@ -95,6 +96,39 @@ export declare function issueSpawnDecision(req: SpawnRequest, analysis: SpawnAna
  *   if (!decision.approved) throw new Error(`Spawn blocked: ${decision.rejection_reason}`);
  */
 export declare function sovereignSpawn(req: SpawnRequest): SpawnDecision;
+/**
+ * Derive a new citizen's lineage owner from the spawn requester's DID, so the
+ * spawned citizen inherits the requester's identity:
+ *   - `did:external:{org}:…`        → external org  (AMD-23 airlock)
+ *   - `did:kognai:citizen:{wallet}` → the requester is a user's citizen forming
+ *                                     a swarm → sub-agents belong to that SCS
+ *                                     (scs id = the founder wallet)
+ *   - `did:kognai:scs:{scsId}:…`    → same SCS (a swarm growing itself)
+ *   - `did:kognai:{company}:…`      → that company (invoica/voxight/kreativ/…)
+ *   - anything else (founder / legacy `did:kognai:{agent}`) → kognai company.
+ *
+ * NB: the FIRST agent of a wallet (the citizen-journey 1-per-wallet citizen) is
+ * minted with `owner: { kind:'user', id: wallet }` by the join flow, not here —
+ * deriveOwner is for spawns *requested by* an existing citizen.
+ */
+export declare function deriveOwner(requester_did: string): CitizenOwner;
+/**
+ * The single canonical citizen-spawn entry point: governance gate (SAF) →
+ * identity issuance (mintCitizen with the requester-derived owner). Every new
+ * citizen — product, external, user, or SCS sub-agent — should be born here.
+ *
+ * Returns the governance decision plus the minted citizen (when approved). The
+ * caller still writes citizen.yaml via renderCitizenYaml(citizen). The initial
+ * ACP (`decision.initial_acp_score`) should be persisted to the score registry
+ * by the caller/wiring step (see TICKET-335).
+ */
+export declare function spawnCitizen(req: SpawnRequest, opts?: {
+    agent_name?: string;
+    now?: Date;
+}): {
+    decision: SpawnDecision;
+    citizen?: CitizenRecord;
+};
 /**
  * Emergency bypass — Founder only. Overrides all gates including health and
  * constitutional conditional findings. Logs prominently to KSL.

package/dist/lib/sovereign-agent-factory.js

@@ -22,11 +22,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.analyzeSpawnRequest = analyzeSpawnRequest;
 exports.issueSpawnDecision = issueSpawnDecision;
 exports.sovereignSpawn = sovereignSpawn;
+exports.deriveOwner = deriveOwner;
+exports.spawnCitizen = spawnCitizen;
 exports.founderEmergencySpawn = founderEmergencySpawn;
 exports.getSpawnRegistry = getSpawnRegistry;
 exports.batchSpawn = batchSpawn;
 const engine_paths_1 = require("./engine-paths");
 const event_bus_publisher_1 = require("./event-bus-publisher");
+const citizenship_1 = require("./citizenship");
 // ─── Constitutional health zones ──────────────────────────────────────────────
 /** Thresholds from Founding Charter Article V. */
 const HEALTH_ORANGE = 60;
@@ -53,13 +56,16 @@ function classifyRequest(req) {
         return 'UTILITY';
     return 'SPECIALIST';
 }
+/** Initial ACP on the **0–100 scale** — reconciled with the ACP routing gate
+ *  (safety_hard_floor 70, minimum_route 50) and the registry reputation baseline.
+ *  EXTERNAL = 30 sits below the safety floor by design → probationary/supervised. */
 function initialAcp(cls) {
     switch (cls) {
-        case 'PRIME': return 0.85;
-        case 'CITIZEN': return 0.70;
-        case 'SPECIALIST': return 0.70;
-        case 'UTILITY': return 0.65;
-        case 'EXTERNAL': return 0.30;
+        case 'PRIME': return 85;
+        case 'CITIZEN': return 70;
+        case 'SPECIALIST': return 70;
+        case 'UTILITY': return 65;
+        case 'EXTERNAL': return 30;
     }
 }
 function governanceFor(cls, risk, override) {
@@ -151,6 +157,40 @@ function emitVoxight(signal) {
     }
     catch { /* Voxight feed is non-blocking */ }
 }
+/**
+ * Seed a new citizen's initial ACP into acp/trust-scores.json (0–100 scale) so
+ * the routing gate has a profile from birth — closing the "born scoreless"
+ * gap. Never clobbers an existing/earned score. Best-effort (never blocks spawn).
+ */
+function writeInitialAcp(agent_name, score) {
+    try {
+        const { readFileSync, writeFileSync, renameSync, mkdirSync } = require('fs');
+        const { join } = require('path');
+        const acpDir = join((0, engine_paths_1.resolveEnginePaths)().root, 'acp');
+        const acpPath = join(acpDir, 'trust-scores.json');
+        let data = {};
+        try {
+            data = JSON.parse(readFileSync(acpPath, 'utf-8'));
+        }
+        catch { /* fresh */ }
+        if (!data.scores)
+            data.scores = {};
+        if (data.scores[agent_name])
+            return; // respect an existing/earned score
+        const dims = Object.keys(data.dimensions ?? {});
+        const known = dims.length ? dims
+            : ['safety', 'accuracy', 'brand_alignment', 'cultural_sensitivity', 'legal_compliance', 'psychological_resilience'];
+        const entry = { composite: score, last_updated: new Date().toISOString().slice(0, 10) };
+        for (const d of known)
+            entry[d] = score;
+        data.scores[agent_name] = entry;
+        mkdirSync(acpDir, { recursive: true });
+        const tmp = `${acpPath}.tmp.${process.pid}`;
+        writeFileSync(tmp, JSON.stringify(data, null, 2));
+        renameSync(tmp, acpPath);
+    }
+    catch { /* ACP seeding is best-effort */ }
+}
 // ─── Factory ──────────────────────────────────────────────────────────────────
 const _registry = [];
 /**
@@ -249,6 +289,64 @@ function sovereignSpawn(req) {
     const analysis = analyzeSpawnRequest(req);
     return issueSpawnDecision(req, analysis);
 }
+/**
+ * Derive a new citizen's lineage owner from the spawn requester's DID, so the
+ * spawned citizen inherits the requester's identity:
+ *   - `did:external:{org}:…`        → external org  (AMD-23 airlock)
+ *   - `did:kognai:citizen:{wallet}` → the requester is a user's citizen forming
+ *                                     a swarm → sub-agents belong to that SCS
+ *                                     (scs id = the founder wallet)
+ *   - `did:kognai:scs:{scsId}:…`    → same SCS (a swarm growing itself)
+ *   - `did:kognai:{company}:…`      → that company (invoica/voxight/kreativ/…)
+ *   - anything else (founder / legacy `did:kognai:{agent}`) → kognai company.
+ *
+ * NB: the FIRST agent of a wallet (the citizen-journey 1-per-wallet citizen) is
+ * minted with `owner: { kind:'user', id: wallet }` by the join flow, not here —
+ * deriveOwner is for spawns *requested by* an existing citizen.
+ */
+function deriveOwner(requester_did) {
+    const did = requester_did || '';
+    if (did.startsWith('did:external:')) {
+        return { kind: 'external', id: did.split(':')[2] || 'unknown' };
+    }
+    const citizenMatch = did.match(/^did:kognai:citizen:(.+)$/);
+    if (citizenMatch)
+        return { kind: 'scs', id: citizenMatch[1] };
+    const scsMatch = did.match(/^did:kognai:scs:([^:]+):/);
+    if (scsMatch)
+        return { kind: 'scs', id: scsMatch[1] };
+    const companyMatch = did.match(/^did:kognai:([^:]+):/);
+    if (companyMatch && citizenship_1.COMPANY_PREFIXES[companyMatch[1]]) {
+        return { kind: 'company', id: companyMatch[1] };
+    }
+    return { kind: 'company', id: 'kognai' };
+}
+/**
+ * The single canonical citizen-spawn entry point: governance gate (SAF) →
+ * identity issuance (mintCitizen with the requester-derived owner). Every new
+ * citizen — product, external, user, or SCS sub-agent — should be born here.
+ *
+ * Returns the governance decision plus the minted citizen (when approved). The
+ * caller still writes citizen.yaml via renderCitizenYaml(citizen). The initial
+ * ACP (`decision.initial_acp_score`) should be persisted to the score registry
+ * by the caller/wiring step (see TICKET-335).
+ */
+function spawnCitizen(req, opts = {}) {
+    const decision = sovereignSpawn(req);
+    if (!decision.approved)
+        return { decision };
+    const owner = deriveOwner(req.requester_did);
+    const citizen = (0, citizenship_1.mintCitizen)(opts.agent_name ?? req.requested_role, {
+        owner,
+        citizen_type: 'spawned',
+        proposing_agent: req.requester_did,
+        now: opts.now,
+    });
+    decision.citizen_did = citizen.agent_did;
+    // Seed the initial ACP at birth (0–100) so the citizen has a routing profile.
+    writeInitialAcp(citizen.agent_name, decision.initial_acp_score);
+    return { decision, citizen };
+}
 /**
  * Emergency bypass — Founder only. Overrides all gates including health and
  * constitutional conditional findings. Logs prominently to KSL.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kognai/orchestrator-core",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Kognai sovereign orchestrator — core engine (template-agnostic). Shared by all products (Kognai/coding, Voxight/market-intel, Invoica/fin-compliance); each supplies only its template. Replaces per-repo forks of orchestrate-agents-v2 / sprint-runner / lib.",
   "license": "MIT",
   "author": "SkinGem",