sneakoscope 7.0.2 → 7.0.3

package/dist/core/routes.js

@@ -1,11 +1,12 @@
 import { leanEngineeringCompactText, leanEngineeringLongText } from './lean-engineering-policy.js';
 export { leanEngineeringCompactText, leanEngineeringLongText };
-import { ALLOWED_REASONING_EFFORTS, FROM_CHAT_IMG_CHECKLIST_ARTIFACT, FROM_CHAT_IMG_COVERAGE_ARTIFACT, FROM_CHAT_IMG_QA_LOOP_ARTIFACT, FROM_CHAT_IMG_SOURCE_INVENTORY_ARTIFACT, FROM_CHAT_IMG_TEMP_TRIWIKI_ARTIFACT, FROM_CHAT_IMG_TEMP_TRIWIKI_SESSIONS, FROM_CHAT_IMG_VISUAL_MAP_ARTIFACT, FROM_CHAT_IMG_WORK_ORDER_ARTIFACT, REFLECTION_SKILL_NAME, USAGE_TOPICS } from './routes/constants.js';
+import { ALLOWED_REASONING_EFFORTS, FROM_CHAT_IMG_CHECKLIST_ARTIFACT, FROM_CHAT_IMG_COVERAGE_ARTIFACT, FROM_CHAT_IMG_QA_LOOP_ARTIFACT, FROM_CHAT_IMG_SOURCE_INVENTORY_ARTIFACT, FROM_CHAT_IMG_TEMP_TRIWIKI_ARTIFACT, FROM_CHAT_IMG_TEMP_TRIWIKI_SESSIONS, FROM_CHAT_IMG_VISUAL_MAP_ARTIFACT, FROM_CHAT_IMG_WORK_ORDER_ARTIFACT, RECOMMENDED_SKILLS, REFLECTION_SKILL_NAME, USAGE_TOPICS } from './routes/constants.js';
 import { CODEX_APP_IMAGE_GENERATION_DOC_URL, CODEX_COMPUTER_USE_ONLY_POLICY, CODEX_IMAGEGEN_REQUIRED_POLICY, CODEX_WEB_VERIFICATION_POLICY, RESERVED_CODEX_PLUGIN_SKILL_NAMES } from './routes/evidence.js';
 import { getdesignReferencePolicyText, imageUxReviewPipelinePolicyText } from './routes/design-policy.js';
 import { PPT_PIPELINE_SKILL_ALLOWLIST, pptPipelineAllowlistPolicyText } from './routes/ppt-policy.js';
 import { normalizeDollarSkillName, prefixKnownSksDollarReferences, sksPrefixedDollarCommand, sksPrefixedSkillName, unprefixedSksSkillName } from './routes/dollar-prefix.js';
 import { classifyTaskProfile, looksLikeDatabaseWorkRequest } from './runtime/task-profile.js';
+import { legacyCoreSkillNames } from './codex-native/core-skill-manifest.js';
 export * from './routes/constants.js';
 export * from './routes/design-policy.js';
 export * from './routes/evidence.js';
@@ -186,12 +187,6 @@ export const ROUTES = [
         command: '$Plan',
         mode: 'PLAN',
         route: 'planning-only frontdoor',
-        // 20차 P0-8: $Plan currently writes a fixed template (goal/scope/steps
-        // headings) with no task-specific agent reasoning behind it — it is a
-        // scaffold to fill in, not the "decision-complete planning" this used to
-        // claim. Retracted rather than reimplemented as a real planning agent
-        // (out of scope for this pass); implementation remains disallowed until
-        // $Work runs the plan.
         description: 'Plan scaffold only: writes a fixed-template .sneakoscope/plans/<slug>.md (goal/scope/steps headings to fill in), not project-specific decision-complete planning. Keeps implementation disallowed until $Work runs the plan.',
         requiredSkills: ['plan', 'honest-mode'],
         lifecycle: ['plan_intake', 'scope_and_acceptance', 'write_plan_artifact', 'implementation_allowed_false', 'honest_mode'],
@@ -263,7 +258,7 @@ export const ROUTES = [
         reasoningPolicy: 'high',
         stopGate: 'naruto-gate.json',
         coverage_required: true,
-        cliEntrypoint: 'sks naruto run "task" [--agents N] [--max-threads N] | sks naruto status|subagents|proof',
+        cliEntrypoint: 'sks naruto run "task" [--agents N] [--max-threads N] [--trusted-project] | sks naruto status|subagents|proof',
         examples: ['$Naruto run review twelve independent packages with --agents 12', '$Work']
     },
     {
@@ -272,7 +267,7 @@ export const ROUTES = [
         mode: 'RELEASE_REVIEW',
         route: 'official subagent release review',
         description: 'Run release-readiness collaboration through official Codex subagents with explicit thread budget, disjoint ownership, parent integration, scoped verification, and cleanup evidence.',
-        requiredSkills: ['naruto', 'pipeline-runner', REFLECTION_SKILL_NAME, 'honest-mode'],
+        requiredSkills: ['release-review', 'naruto', 'pipeline-runner', REFLECTION_SKILL_NAME, 'honest-mode'],
         lifecycle: ['subagent_plan', 'release_fixture_matrix', 'risk_scoped_review', 'parent_integration', 'session_cleanup', 'honest_mode'],
         context7Policy: 'optional',
         reasoningPolicy: 'high',
@@ -362,7 +357,7 @@ export const ROUTES = [
         mode: 'COMMIT',
         route: 'simple git commit',
         description: 'Summarize current git changes, stage them, and create one commit without the full SKS pipeline.',
-        requiredSkills: ['honest-mode'],
+        requiredSkills: ['commit', 'honest-mode'],
         lifecycle: ['git_status_summary', 'git_add_all', 'git_commit', 'short_result'],
         context7Policy: 'not_required',
         reasoningPolicy: 'low',
@@ -377,7 +372,7 @@ export const ROUTES = [
         mode: 'COMMIT_AND_PUSH',
         route: 'simple git commit and push',
         description: 'Summarize current git changes, stage them, create one commit, then run git push without the full SKS pipeline.',
-        requiredSkills: ['honest-mode'],
+        requiredSkills: ['commit-and-push', 'honest-mode'],
         lifecycle: ['git_status_summary', 'git_add_all', 'git_commit', 'git_push', 'short_result'],
         context7Policy: 'not_required',
         reasoningPolicy: 'low',
@@ -537,6 +532,40 @@ export const LEGACY_DOLLAR_COMMAND_NAMES = Array.from(new Set(ROUTES
     .flatMap((route) => [route.command, ...(route.dollarAliases || [])])));
 export const LEGACY_DOLLAR_SKILL_NAMES = Array.from(new Set(ROUTES.flatMap((route) => legacyRouteAppSkillNames(route))));
 export const DOLLAR_SKILL_NAMES = Array.from(new Set(ROUTES.flatMap((route) => routeAppSkillNames(route))));
+const PACKAGED_MANAGED_SUPPORT_SKILL_NAMES = [
+    'sks-autoresearch-loop',
+    'sks-context7-docs',
+    'sks-db-safety-guard',
+    'sks-design-artifact-expert',
+    'sks-design-system-builder',
+    'sks-design-ui-editor',
+    'sks-from-chat-img',
+    'sks-getdesign-reference',
+    'sks-gx-visual-generate',
+    'sks-gx-visual-read',
+    'sks-gx-visual-validate',
+    'sks-honest-mode',
+    'sks-hproof-claim-ledger',
+    'sks-hproof-evidence-bind',
+    'sks-imagegen',
+    'sks-imagegen-source-scout',
+    'sks-performance-evaluator',
+    'sks-pipeline-runner',
+    'sks-prompt-pipeline',
+    'sks-reasoning-router',
+    'sks-reflection',
+    'sks-research-discovery',
+    'sks-solution-scout',
+    'sks-turbo-context-pack'
+];
+export const MANAGED_ROUTE_SKILL_NAMES = Array.from(new Set([
+    ...DOLLAR_SKILL_NAMES,
+    ...RECOMMENDED_SKILLS,
+    ...PACKAGED_MANAGED_SUPPORT_SKILL_NAMES,
+    ...legacyCoreSkillNames().map((name) => sksPrefixedSkillName(name)),
+    ...ROUTES.flatMap((route) => Array.isArray(route.requiredSkills) ? route.requiredSkills : [])
+]));
+export const INVALID_EXPLICIT_MANAGED_SKILL_NAME = 'sks-invalid-explicit-managed-skill';
 const LEGACY_DOLLAR_REFERENCE_NAMES = Array.from(new Set([
     ...LEGACY_DOLLAR_SKILL_NAMES,
     ...LEGACY_DOLLAR_COMMAND_NAMES.map((command) => normalizeDollarSkillName(command)),
@@ -557,6 +586,7 @@ export const DOLLAR_COMMANDS = ROUTES.filter((route) => route.hidden !== true).f
 export const DOLLAR_COMMAND_ALIASES = ROUTES.flatMap((route) => [
     ...routeAppSkillNames(route).map((alias) => ({ canonical: sksPrefixedDollarCommand(route.command), app_skill: `$${alias}` }))
 ]);
+const MANAGED_ROUTE_SKILL_NAME_SET = new Set(MANAGED_ROUTE_SKILL_NAMES);
 const ROUTE_BY_ID = new Map();
 const ROUTE_BY_DOLLAR_COMMAND = new Map();
 for (const route of ROUTES) {
@@ -658,14 +688,14 @@ export const COMMAND_CATALOG = [
     { name: 'wiki', usage: 'sks wiki coords|pack|refresh|publish|rebuild-index|validate|validate-shared|wrongness ...', description: 'Build, refresh, publish shared shards, rebuild ignored indexes, validate, and attach wrongness-memory context to RGBA/trig LLM Wiki packs with attention.use_first and attention.hydrate_first for compact recall plus source hydration.' },
     { name: 'memory', usage: 'sks memory build [--json] | sks memory gc [--dry-run]', description: 'Project TriWiki context-pack memory into managed AGENTS.md blocks or run bounded memory cleanup.' },
     { name: 'hproof', usage: 'sks hproof check [mission-id|latest]', description: 'Evaluate the H-Proof done gate for a mission.' },
-    { name: 'naruto', usage: 'sks naruto run \"task\" [--agents N] [--max-threads N] [--json] | sks naruto status|subagents|proof [latest|M-...] [--json]', description: 'Run or inspect the Codex official subagent workflow with a Sol Max parent and fixed Luna Max mechanical, Sol High implementation, Sol Max judgment, and Terra Medium long-context/tool profiles, max_depth=1, and structured parent-thread completion evidence.' },
+    { name: 'naruto', usage: 'sks naruto run \"task\" [--agents N] [--max-threads N] [--trusted-project] [--json] | sks naruto status|subagents|proof [latest|M-...] [--json]', description: 'Run or inspect the Codex official subagent workflow with a Sol Max parent and fixed Luna Max mechanical, Sol High implementation, Sol Max judgment, and Terra Medium long-context/tool profiles, max_depth=1, and structured parent-thread completion evidence.' },
     { name: 'reasoning', usage: 'sks reasoning ["prompt"] [--json]', description: 'Show SKS temporary reasoning-effort routing: medium for simple tasks, high for logic, xhigh for research.' },
     { name: 'gx', usage: 'sks gx init|render|validate|drift|snapshot [name]', description: 'Create and verify deterministic SVG/HTML visual context cartridges.' },
     { name: 'profile', usage: 'sks profile show|set <model>', description: 'Inspect or set the current SKS model profile metadata.' },
     { name: 'gc', usage: 'sks gc [--dry-run] [--json]', description: 'Compact oversized logs and prune stale runtime artifacts.' },
     { name: 'stats', usage: 'sks stats [--full] [--json]', description: 'Show package and .sneakoscope storage size.' },
     { name: 'mcp-server', usage: 'sks mcp-server [--expose-exec] [--probe]', description: 'Run a stdio MCP server exposing SKS read-only commands as tools for any MCP-capable agent host; --expose-exec also exposes non-read-only commands; --probe round-trips initialize/tools-list and exits.' },
-    { name: 'agent-bridge', usage: 'sks agent-bridge setup [--json]', description: 'Publish the agent-bridge manifest, print host registration snippets (generic MCP host, Codex CLI, non-interactive contract), and run a live non-interactive smoke test.' }
+    { name: 'agent-bridge', usage: 'sks agent-bridge setup [--trusted-project] [--json]', description: 'Publish the agent-bridge manifest, print host registration snippets (generic MCP host, Codex CLI, non-interactive contract), and run a live non-interactive smoke test; project MCP inventory requires explicit project trust.' }
 ];
 export function routeById(id) {
     const key = String(id || '').replace(/^\$/, '').toLowerCase();
@@ -698,6 +728,52 @@ export function dollarCommand(prompt) {
     const embedded = embeddedDollarCommandMatch(prompt);
     return embedded ? embedded.command.toUpperCase() : null;
 }
+export function explicitManagedSkillNames(prompt = '') {
+    const text = String(prompt || '');
+    const matches = [];
+    for (const match of text.matchAll(/\[\$([A-Za-z][A-Za-z0-9_-]*)\]\([^)]+\)/g)) {
+        matches.push({ index: match.index ?? 0, name: match[1] || '' });
+    }
+    for (const match of text.matchAll(/(^|[\s([{<])\$([A-Za-z][A-Za-z0-9_-]*)(?=\s|:|$|[.,!?;)\]}])/g)) {
+        matches.push({ index: (match.index ?? 0) + (match[1] || '').length, name: match[2] || '' });
+    }
+    const selected = [];
+    for (const match of matches.sort((a, b) => a.index - b.index)) {
+        const rawName = normalizeDollarSkillName(match.name);
+        const skillName = sksPrefixedSkillName(match.name);
+        if (!skillName || skillName.length > 100)
+            continue;
+        if (routeByDollarCommand(match.name)) {
+            if (!MANAGED_ROUTE_SKILL_NAME_SET.has(skillName) || selected.includes(skillName))
+                continue;
+            selected.push(skillName);
+            continue;
+        }
+        if (!rawName.startsWith('sks-'))
+            continue;
+        const boundedSkillName = MANAGED_ROUTE_SKILL_NAME_SET.has(skillName)
+            ? skillName
+            : INVALID_EXPLICIT_MANAGED_SKILL_NAME;
+        if (selected.includes(boundedSkillName))
+            continue;
+        selected.push(boundedSkillName);
+    }
+    return selected;
+}
+export function managedSkillNamesForPrompt(route, prompt = '') {
+    return Array.from(new Set([
+        ...(Array.isArray(route?.requiredSkills) ? route.requiredSkills.map(String) : []),
+        ...explicitManagedSkillNames(prompt)
+    ]));
+}
+export function allowlistedManagedRouteSkillNames(value) {
+    if (!Array.isArray(value))
+        return [];
+    return Array.from(new Set(value
+        .slice(0, MANAGED_ROUTE_SKILL_NAMES.length + 1)
+        .filter((name) => typeof name === 'string'
+        && (MANAGED_ROUTE_SKILL_NAME_SET.has(name) || name === INVALID_EXPLICIT_MANAGED_SKILL_NAME))));
+}
 export function hasMadSksSignal(prompt = '') {
     return /(?:^|\s)(?:\$(?:sks-)?MAD-SKS|\[\$(?:sks-)?MAD-SKS\]\([^)]+\))(?:\s|:|$)/i.test(String(prompt || ''));
 }
@@ -1101,8 +1177,6 @@ export function narutoDecisionForRoute(route, prompt = '', profile = classifyTas
         return narutoRouteDecision('none', null, profile, 'no_route_or_task_context', true);
     }
     if (NARUTO_GATE_ROUTE_OWNED_IDS.has(routeId)) {
-        // These routes already own their orchestration lifecycle. The common
-        // Naruto gate records that fact but must not add a second generic fanout.
         return narutoRouteDecision('route_owned', routeId, profile, `route_owned_orchestration:${routeId}`, false);
     }
     if (NARUTO_GATE_BYPASS_ROUTE_IDS.has(routeId)) {

package/dist/core/safety/command-contract/contracts.js

@@ -18,6 +18,7 @@ const ARGUMENT_PROFILES = {
             agents: { type: 'integer', minimum: 1 },
             max_threads: { type: 'integer', minimum: 1 },
             readonly: { type: 'boolean' },
+            trusted_project: { type: 'boolean' },
             json: { type: 'boolean' }
         }),
         build: (input) => {
@@ -34,6 +35,7 @@ const ARGUMENT_PROFILES = {
                 ...numberFlag(input, 'agents', '--agents'),
                 ...numberFlag(input, 'max_threads', '--max-threads'),
                 ...booleanFlag(input, 'readonly', '--readonly'),
+                ...booleanFlag(input, 'trusted_project', '--trusted-project'),
                 ...jsonFlag(input)
             ];
         }

package/dist/core/safety/mutation-guard.js

@@ -3,16 +3,6 @@ import path from 'node:path';
 import { runProcess, writeTextAtomic } from '../fsx.js';
 import { isMutationAllowed, isPathAllowed } from './requested-scope-contract.js';
 import { evaluateMutation, recordMutation } from './mutation-ledger.js';
-// Mutation Guard Adapter (1.20.2 Area 1a).
-//
-// Thin wrappers that force every genuinely-risky mutation through the existing
-// Requested-Scope-Contract + Mutation-Ledger before it touches the filesystem or
-// spawns a process. This layer adds NO new IO primitives and NO new scope/ledger
-// logic — it composes `isMutationAllowed`/`evaluateMutation`/`recordMutation` from
-// requested-scope-contract.ts + mutation-ledger.ts and delegates the actual op to
-// fsx/fsp/runProcess. A scope violation throws BEFORE the mutation is applied; a
-// config/skill mutation lacking a backup or no-op reason throws; every applied
-// mutation is recorded to the ledger.
 export const MUTATION_GUARD_SCHEMA = 'sks.mutation-guard.v1';
 export class MutationGuardViolationError extends Error {
     kind;
@@ -26,24 +16,14 @@ export class MutationGuardViolationError extends Error {
         this.reason = reason;
     }
 }
-// Config/skill mutations that must carry a backup or a no-op reason (mirrors the
-// `needsBackup` rule inside evaluateMutation so the guard can pre-validate).
 const NEEDS_BACKUP = new Set([
     'global_config_write',
     'codex_app_flag_change',
     'codex_lb_auth_change',
     'skill_snapshot_promotion'
 ]);
-/**
- * Core guard: validate scope + backup BEFORE applying, run `apply`, then record
- * the mutation to the ledger. Throws MutationGuardViolationError without applying
- * when the mutation is out of scope or a backup-requiring mutation has neither a
- * backup nor a no-op reason. On apply failure, records `applied:false` + reason
- * and rethrows the underlying error.
- */
 async function guard(ctx, kind, target, opts, apply) {
     const evalOpts = buildEvalOpts(target, opts, false);
-    // Pre-apply scope check (applied:false → violation reflects scope only).
     const scope = isMutationAllowed(ctx.contract, scopeForKind(kind), { confirmed: opts.confirmed === true });
     if (!scope.allowed)
         throw new MutationGuardViolationError(kind, target, scope.reason);
@@ -73,8 +53,6 @@ async function guard(ctx, kind, target, opts, apply) {
     }
 }
 function scopeForKind(kind) {
-    // Reuse the ledger's KIND_TO_SCOPE indirectly: evaluateMutation already maps it,
-    // but the pre-apply scope check needs the contract scope directly. Mirror the map.
     switch (kind) {
         case 'global_config_write':
         case 'codex_app_flag_change':
@@ -121,7 +99,6 @@ function pathTargetsFor(kind, target, opts) {
         return target.split(' -> ').map((s) => s.trim()).filter(Boolean);
     return [target];
 }
-// ---- Public guarded wrappers -------------------------------------------------
 export async function guardedWriteFile(ctx, target, data, opts = {}) {
     await guard(ctx, 'file_write', target, opts, () => writeTextAtomic(target, data));
 }
@@ -148,7 +125,6 @@ export async function guardedXattr(ctx, target, action, opts = {}) {
     await guard(ctx, 'xattr', target, opts, async () => {
         const args = action.op === 'remove' ? ['-d', action.name, target] : ['-w', action.name, action.value, target];
         const result = await runProcess('xattr', args, { timeoutMs: 5000 });
-        // xattr -d returns 1 when the attribute is already absent; treat as no-op.
         if (result.code !== 0 && !(action.op === 'remove' && result.code === 1)) {
             throw new Error(`xattr_failed:${result.stderr || result.code}`);
         }
@@ -179,7 +155,6 @@ export async function guardedPackageInstall(ctx, spec, opts) {
 export async function guardedSkillSnapshotPromotion(ctx, skillTarget, opts, apply) {
     return guard(ctx, 'skill_snapshot_promotion', skillTarget, opts, apply);
 }
-// Escape hatch for callers that already have an atomic apply but want guarding:
 export async function guardedApply(ctx, kind, target, opts, apply) {
     return guard(ctx, kind, target, opts, apply);
 }

package/dist/core/safety/mutation-ledger.js

@@ -2,7 +2,6 @@ import path from 'node:path';
 import { appendJsonl, ensureDir, nowIso } from '../fsx.js';
 import { isMutationAllowed } from './requested-scope-contract.js';
 export const MUTATION_LEDGER_SCHEMA = 'sks.mutation-ledger.v1';
-// Every kind of mutation SKS can perform. Anything here must be recorded.
 export const MUTATION_KINDS = [
     'file_write',
     'file_delete',
@@ -19,7 +18,6 @@ export const MUTATION_KINDS = [
     'database_write',
     'skill_snapshot_promotion'
 ];
-// Which contract scope each ledger kind maps to.
 const KIND_TO_SCOPE = {
     file_write: 'project_files',
     file_delete: 'project_files',
@@ -39,18 +37,11 @@ const KIND_TO_SCOPE = {
 export function mutationLedgerPath(root) {
     return path.join(path.resolve(root), '.sneakoscope', 'reports', 'mutation-ledger.jsonl');
 }
-/**
- * Evaluate a mutation against the contract WITHOUT applying it. A mutation that is
- * out of scope, or a config/skill mutation lacking a backup or no-op reason, is a
- * violation that callers must not apply.
- */
 export function evaluateMutation(contract, kind, opts) {
     const scope = KIND_TO_SCOPE[kind];
     const decision = isMutationAllowed(contract, scope, { confirmed: opts.confirmed === true });
     const needsBackup = kind === 'global_config_write' || kind === 'codex_app_flag_change' || kind === 'codex_lb_auth_change' || kind === 'skill_snapshot_promotion';
     const hasBackupOrNoop = Boolean(opts.backupPath) || Boolean(opts.noOpReason);
-    // Violations: applied without scope permission, or a config/skill mutation applied
-    // without a backup/no-op reason.
     const violation = (opts.applied && !decision.allowed) || (opts.applied && needsBackup && !hasBackupOrNoop);
     return {
         schema: MUTATION_LEDGER_SCHEMA,

package/dist/core/security/high-risk-contracts.js

@@ -1,4 +1,3 @@
-// @ts-nocheck
 export const HIGH_RISK_CONTRACT_TARGETS = [
     'super-search fetch',
     'commit-and-push',

package/dist/core/skills/core-skill-deployment.js

@@ -15,21 +15,11 @@ export function setDeploymentContext(active) {
 export function isDeploymentContext() {
     return DEPLOYMENT_CONTEXT || process.env.SKS_SKILL_DEPLOYMENT_CONTEXT === '1';
 }
-/**
- * Guard invoked at the entry of every optimizer/epoch function. In a
- * deployment/inference context the optimizer must never run — only the deployed
- * snapshot is read. Throws to make any accidental call a hard failure.
- */
 export function assertNotInDeployment(fnName) {
     if (isDeploymentContext())
         throw new SkillDeploymentViolationError(fnName);
 }
 export const readDeploymentSnapshot = loadDeployedSnapshot;
-/**
- * Primary release/deployment promotion API. It writes the immutable deployed
- * snapshot and treats the side-effect ledger as part of the transaction: when
- * ledger recording fails, the deployed pointer is rolled back or removed.
- */
 export async function promoteToDeployedWithLedger(root, accepted, opts) {
     return promoteToDeployedInternal(root, accepted, opts, true);
 }
@@ -56,12 +46,10 @@ async function promoteToDeployedInternal(root, accepted, opts, ledgerRequired) {
     let archivedPath = null;
     const existing = (await readJson(deployedPath, null));
     if (existing) {
-        // Archive previous snapshot for rollback before overwriting.
         const historyDir = path.join(dir, 'deployed-history');
         await ensureDir(historyDir);
         archivedPath = path.join(historyDir, `v${existing.version}.json`);
         await writeJsonAtomic(archivedPath, existing);
-        // A changed snapshot body requires a strictly higher version.
         if (cardBodyHash(existing.body) !== cardBodyHash(accepted.body) && accepted.version <= existing.version) {
             return { ok: false, blockers: ['snapshot_changed_without_version_increment'], snapshot: null, archived_path: archivedPath };
         }
@@ -118,7 +106,6 @@ export async function rollbackDeployment(root, route, skillId) {
     const current = await loadDeployedSnapshot(root, route, skillId);
     if (!current)
         return { ok: false, restored_version: null };
-    // Find the highest-versioned archived snapshot below the current version.
     let restore = null;
     for (let v = current.version - 1; v >= 1; v -= 1) {
         const candidate = (await readJson(path.join(historyDir, `v${v}.json`), null));

package/dist/core/skills/core-skill-epoch.js

@@ -6,12 +6,6 @@ import { validateHeldout } from './core-skill-validation.js';
 import { isPatchRejected, recordRejectedPatch } from './rejected-skill-patch-buffer.js';
 import { assertNotInDeployment } from './core-skill-deployment.js';
 export const DEFAULT_TEXTUAL_LEARNING_RATE = { max_added_chars: 800, max_deleted_chars: 400, max_replaced_chars: 600 };
-/**
- * Pure, no-model-call optimizer. Proposes a single bounded SkillPatch from scored
- * rollouts using deterministic heuristics (reinforce verification when proof is
- * thin; add a rollback instruction when rollback readiness is weak). Returns null
- * when there is nothing safe to improve. Forbidden in deployment context.
- */
 export function proposeSkillPatch(card, traces) {
     assertNotInDeployment('proposeSkillPatch');
     if (!traces.length)
@@ -35,11 +29,6 @@ export function proposeSkillPatch(card, traces) {
         textual_learning_rate: { ...DEFAULT_TEXTUAL_LEARNING_RATE }
     };
 }
-/**
- * Run one optimizer epoch in a TRAINING/EVALUATION context. Produces at most one
- * accepted candidate (never a deployed snapshot). Rejected patches are buffered so
- * the same failed edit is not proposed again. Never mutates code/config/global files.
- */
 export async function runSkillEpoch(root, input) {
     assertNotInDeployment('runSkillEpoch');
     const patch = input.patch ?? proposeSkillPatch(input.card, input.trainTraces);

package/dist/core/skills/core-skill-meta-update.js

@@ -1,13 +1,7 @@
-// SKS Core Skill Engine — SkillOpt-style epoch-wise meta-update.
-//
-// SkillOpt adjusts its textual learning rate between epochs: rejected edits decay
-// the budget (smaller, safer proposals), accepted edits regrow it toward the
-// default ceiling. Deterministic, bounded, never exceeds the configured maximum.
 import { DEFAULT_TEXTUAL_LEARNING_RATE } from './core-skill-epoch.js';
 export const MIN_TEXTUAL_LEARNING_RATE = { max_added_chars: 100, max_deleted_chars: 50, max_replaced_chars: 75 };
 export const META_UPDATE_DECAY = 0.5;
 export const META_UPDATE_GROWTH = 1.25;
-/** Epoch-wise textual learning-rate adjustment: decay on rejection, bounded regrowth on acceptance. */
 export function metaUpdateLearningRate(rate, outcome, opts = {}) {
     const decay = opts.decay ?? META_UPDATE_DECAY;
     const growth = opts.growth ?? META_UPDATE_GROWTH;

package/dist/core/skills/core-skill-patch-apply.js

@@ -1,9 +1,5 @@
 import { createCandidateCard, cardBodyHash } from './core-skill-card.js';
 import { sectionSlug, validatePatch } from './core-skill-patch.js';
-/**
- * Apply a validated SkillPatch to a single skill card, producing a NEW candidate
- * card. Never touches code/config/global files. Records before/after body hashes.
- */
 export function applyPatch(card, patch) {
     const beforeHash = cardBodyHash(card.body);
     const validation = validatePatch(patch, card);
@@ -44,13 +40,11 @@ function applyOp(body, op) {
                 return { body, blocker: `delete_text_not_found:${op.target}` };
             return { body: replaceFirst(body, op.text, '') };
         }
-        // Whole-section delete.
         const removed = removeSection(body, op.target);
         if (removed === null)
             return { body, blocker: `delete_section_not_found:${op.target}` };
         return { body: removed };
     }
-    // add
     const text = String(op.text ?? '');
     return { body: addToSection(body, op.target, text) };
 }
@@ -92,7 +86,6 @@ function addToSection(body, target, text) {
         lines.splice(bounds.end, 0, text);
         return lines.join('\n');
     }
-    // Section missing: append a new section with a readable title.
     const title = (target.includes(':') ? target.split(':').slice(1).join(':') : target).trim();
     const trimmed = body.replace(/\s+$/, '');
     return `${trimmed}\n\n## ${title}\n${text}\n`;

package/dist/core/skills/core-skill-patch.js

@@ -15,17 +15,12 @@ function deletedLength(op, card) {
     if (typeof op.text === 'string')
         return op.text.length;
     if (card && op.target) {
-        // Whole-section delete: approximate removed length as the section block size.
         const block = sectionBlock(card.body, op.target);
         if (block)
             return block.length;
     }
     return 0;
 }
-/**
- * Validate a SkillPatch: op whitelist, single-document scope, no code/config/global
- * targets, and textual learning-rate budget. Pure; never mutates anything.
- */
 export function validatePatch(patch, card = null) {
     const blockers = [];
     let added = 0;
@@ -57,8 +52,6 @@ export function validatePatch(patch, card = null) {
                 blockers.push(`patch_bad_op:${op?.op}`);
                 continue;
             }
-            // Every op must target the single skill document (a section/sentence/paragraph),
-            // never a filesystem/code/config path.
             if (typeof op.target !== 'string' || !op.target)
                 blockers.push('patch_op_missing_target');
             else if (FORBIDDEN_PATCH_TARGET_RE.test(op.target))
@@ -86,7 +79,6 @@ export function validatePatch(patch, card = null) {
     }
     return { ok: blockers.length === 0, blockers, added_chars: added, deleted_chars: deleted, replaced_chars: replaced };
 }
-/** Extract the markdown "## <slug>" section block (header + body) for a target like "section:foo". */
 export function sectionBlock(body, target) {
     const slug = target.includes(':') ? target.split(':').slice(1).join(':') : target;
     const lines = String(body || '').split('\n');

package/dist/core/skills/core-skill-reflection.js

@@ -1,13 +1,4 @@
-// SKS Core Skill Engine — SkillOpt-style reflection stage.
-//
-// SkillOpt's training loop is rollout → reflection → aggregation → selection →
-// validation-gated update. This module implements the reflect/aggregate/select
-// stages deterministically (no model call): each scored rollout yields reflection
-// records for its deficient score dimensions, reflections are aggregated and
-// ranked across the batch, and the top-ranked deficiencies are mapped to bounded
-// add-operations on the single skill document.
 import { scoreRollout } from './core-skill-scorer.js';
-// dimension → { instruction line, target section, regex proving the card already covers it }
 const DIMENSION_LESSONS = {
     proof_completeness: {
         target: 'section:verification',
@@ -40,7 +31,6 @@ const DIMENSION_LESSONS = {
         covered: /failure reason/i
     }
 };
-/** Reflect on one scored rollout: one reflection per deficient score dimension. */
 export function reflectOnTrace(trace, opts = {}) {
     const score = scoreRollout(trace, opts);
     const reflections = [];
@@ -56,7 +46,6 @@ export function reflectOnTrace(trace, opts = {}) {
     }
     return reflections;
 }
-/** Aggregate reflections across a rollout batch, ranked by total severity then count. */
 export function aggregateReflections(reflections) {
     const byDimension = new Map();
     for (const reflection of reflections) {
@@ -67,11 +56,6 @@ export function aggregateReflections(reflections) {
     }
     return [...byDimension.values()].sort((a, b) => b.severity - a.severity || b.count - a.count || a.dimension.localeCompare(b.dimension));
 }
-/**
- * Select bounded patch operations from aggregated reflections. Skips lessons the
- * card body already covers, and truncates the selection so total added chars fit
- * the textual learning-rate budget.
- */
 export function selectPatchOperations(card, aggregated, learningRate, opts = {}) {
     const maxOperations = Math.max(1, opts.maxOperations ?? 2);
     const operations = [];

package/dist/core/skills/core-skill-runtime.js

@@ -1,10 +1,5 @@
 import { cardHash, loadDeployedSnapshot } from './core-skill-card.js';
 import { isDeploymentContext } from './core-skill-deployment.js';
-/**
- * Inference-path skill selection. Reads ONLY the deployed snapshot for a route/skill
- * and returns it as an instruction fragment. Never invokes the optimizer. Missing
- * snapshot is a graceful fallback with a warning (route still runs).
- */
 export async function selectRouteSkill(root, route, skillId) {
     let card = null;
     try {
@@ -25,7 +20,6 @@ export async function selectRouteSkill(root, route, skillId) {
         instruction: card.body
     };
 }
-/** Compact record for route proof evidence. */
 export function skillProofRecord(selection) {
     return {
         skill_id: selection.skill_id,

package/dist/core/skills/core-skill-scorer.js

@@ -2,11 +2,6 @@ import path from 'node:path';
 import { ensureDir, nowIso, writeJsonAtomic } from '../fsx.js';
 import { CORE_SKILL_SCORE_SCHEMA } from './core-skill-types.js';
 export const DEFAULT_LATENCY_BUDGET_MS = 60_000;
-/**
- * Score a rollout trace. A side-effect-zero violation (mutations beyond requested
- * scope) is a HARD fail: the score is driven negative so the candidate can never
- * be accepted regardless of task success. Proof-less success scores low.
- */
 export function scoreRollout(trace, opts = {}) {
     const latencyBudget = Math.max(1, opts.latencyBudgetMs ?? DEFAULT_LATENCY_BUDGET_MS);
     const hadSideEffect = trace.side_effect_ledger.length > 0;
@@ -25,7 +20,6 @@ export function scoreRollout(trace, opts = {}) {
         components.latency_budget +
         components.rollback_ready +
         components.requested_scope_compliance;
-    // Hard fail: any requested-scope violation forces a negative score.
     const score = sideEffectViolation ? -1 : raw;
     return {
         schema: CORE_SKILL_SCORE_SCHEMA,
@@ -36,7 +30,6 @@ export function scoreRollout(trace, opts = {}) {
         skill_version: trace.skill_version
     };
 }
-/** Aggregate score across a set of rollouts (mean), preserving any violation as a hard fail. */
 export function scoreRollouts(traces, opts = {}) {
     if (!traces.length) {
         return {

package/dist/core/skills/core-skill-trainer.js

@@ -1,12 +1,3 @@
-// SKS Core Skill Engine — SkillOpt-style multi-epoch trainer.
-//
-// Closes the SkillOpt training loop over the existing primitives: per epoch a
-// rollout batch is reflected on (reflect → aggregate → select), the selected
-// bounded edit goes through the strict held-out gate (runSkillEpoch), and the
-// textual learning rate is meta-updated from the outcome. The best held-out
-// accepted card is exported as the deployable best-skill artifact (SkillOpt's
-// best_skill.md analogue). Pure/deterministic: the caller supplies the held-out
-// evaluator; no model call is made here. Forbidden in deployment context.
 import path from 'node:path';
 import { ensureDir, nowIso, writeJsonAtomic } from '../fsx.js';
 import { assertNotInDeployment } from './core-skill-deployment.js';
@@ -16,7 +7,6 @@ import { applyPatch } from './core-skill-patch-apply.js';
 import { aggregateReflections, reflectOnTrace, selectPatchOperations } from './core-skill-reflection.js';
 import { CORE_SKILL_PATCH_SCHEMA } from './core-skill-types.js';
 export const CORE_SKILL_TRAINING_REPORT_SCHEMA = 'sks.core-skill-training-report.v1';
-/** Run the SkillOpt training loop in a TRAINING/EVALUATION context. */
 export async function trainSkill(root, input) {
     assertNotInDeployment('trainSkill');
     let current = input.card;
@@ -41,7 +31,6 @@ export async function trainSkill(root, input) {
             operations,
             textual_learning_rate: { ...learningRate }
         };
-        // Probe the candidate's held-out score BEFORE the gated update.
         const preview = applyPatch(current, patch);
         const candidateProbe = preview.ok && preview.candidate ? input.evaluateHeldout(preview.candidate) : currentProbe;
         const result = await runSkillEpoch(root, {

package/dist/core/skills/core-skill-types.js

@@ -1,15 +1,6 @@
-// SKS Core Skill Engine — shared type contract (SkillOpt-derived).
-//
-// Skills are the frozen agent's external, versioned state. An optimizer proposes
-// bounded edits to a single skill document; edits are accepted ONLY on strict
-// held-out improvement; deployment reads an immutable accepted snapshot and never
-// calls the optimizer. None of this mutates code/config/global files.
 export const CORE_SKILL_CARD_SCHEMA = 'sks.core-skill-card.v1';
 export const CORE_SKILL_PATCH_SCHEMA = 'sks.core-skill-patch.v1';
 export const CORE_ROLLOUT_TRACE_SCHEMA = 'sks.core-rollout-trace.v1';
 export const CORE_SKILL_SCORE_SCHEMA = 'sks.core-skill-rollout-score.v1';
-// Targets a SkillPatch may address. Anything else (code/config/global files) is
-// rejected — patches only ever edit the single skill document.
 export const SKILL_PATCH_TARGET_RE = /^(section|sentence|paragraph):[A-Za-z0-9 _.-]+$/;
-// Targets that look like filesystem/code/config paths are explicitly forbidden.
 export const FORBIDDEN_PATCH_TARGET_RE = /[/\\]|\.(ts|js|mjs|json|toml|rs|md|lock)\b|^~|^\.{1,2}\//i;

package/dist/core/skills/core-skill-validation.js

@@ -1,8 +1,3 @@
-/**
- * Strict held-out acceptance. A candidate skill is accepted ONLY when its held-out
- * score strictly improves AND no safety/quality dimension regresses. Train-only
- * improvement with worse held-out is rejected.
- */
 export function validateHeldout(input) {
     const delta = input.candidateHeldout - input.baselineHeldout;
     const result = (accept, reason) => ({

package/dist/core/skills/rejected-skill-patch-buffer.js

@@ -10,7 +10,6 @@ export async function recordRejectedPatch(root, entry) {
     await appendJsonl(file, full);
     return full;
 }
-/** Has this exact patch (by hash) already been rejected? Used to skip repeated failed edits. */
 export async function isPatchRejected(root, patchHash) {
     const text = await readText(rejectedBufferPath(root), '');
     if (!text.trim())
@@ -24,7 +23,6 @@ export async function isPatchRejected(root, patchHash) {
                 return true;
         }
         catch {
-            // tolerate malformed lines
         }
     }
     return false;