@ngockhoale/ukit 1.1.6 → 1.1.8

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to UKit are documented here.
 
 ## Unreleased
 
+## 1.1.8 - 2026-05-05
+
+### Living Project Status
+
+- Added `docs/STATUS.md` as a compact living project-state baseline for active work, debug threads, blockers, verification, and next candidates.
+- Added `next-step` and `update-status` skills so Claude/Codex/OpenCode can use project status automatically without adding any user-facing commands beyond `ukit install`.
+- Made next-step routing freshness-aware: stale or missing status must be treated as orientation only and verified against source/index before recommendations.
+- Added concrete-task precedence so prompts like “fix login bug but not sure next step” stay on the debug/implementation/review workflow instead of being hijacked by global roadmap suggestions.
+- Registered status docs/skills in the manifest with skip semantics for the living doc, and kept source route catalogs aligned with installed helper mirrors.
+- Updated install/routing/manifest regression coverage for open-ended status prompts, explicit handoff updates, concrete debug edge cases, and default skill installation.
+
+## 1.1.7 - 2026-04-25
+
+### Impact Confidence
+
+- Added impact-confidence indexing for changed shared/runtime files, including lightweight call extraction and `calls.json` artifacts.
+- Added shared-impact classification so source index runtime, install/runtime core, shipped hooks/helpers, manifests, and templates are routed as higher-confidence verification work instead of ordinary simple edits.
+- Added mirror-counterpart guidance between source modules and installed helper mirrors, helping agents catch source/template drift before release.
+- Added shipped `impact-context.mjs` helper and manifest coverage so installed workspaces can resolve impact context after `ukit install`.
+- Tightened verification planning and guard behavior so impact-test lanes run targeted checks first, while broad verification remains advisory unless explicitly enforced.
+- Added package-artifact, hook, indexing, impact-context, and impact-catalog coverage for the new release surface.
+
 ## 1.1.6 - 2026-04-23
 
 ### Hidden Runtime Root

package/README.md

@@ -32,6 +32,7 @@ ukit install
 4. Fill in the generated docs baseline:
    - `docs/PROJECT.md`
    - `docs/MEMORY.md`
+   - `docs/STATUS.md`
    - `docs/WORKLOG.md`
 5. Open your AI tool and work in natural language.
 
@@ -64,9 +65,9 @@ If maintainers roll out a newer CLI build, the in-project workflow still stays t
 **Project support files**
 - `.claude/ukit/.ukit/` — installer manifests, metadata, backups
 - `.ukit/` — hidden shared runtime storage for config, cache, and cross-agent memory
-- `docs/` — PROJECT / MEMORY / WORKLOG baseline
+- `docs/` — PROJECT / MEMORY / STATUS / WORKLOG baseline
 
-## UKit v1.1.6 Runtime
+## UKit v1.1.8 Runtime
 
 UKit now installs a hidden shared local runtime at `.ukit/` for production-oriented state that should survive across agent sessions:
 
@@ -83,13 +84,17 @@ When long sessions approach the compact threshold, UKit now uses a conservative
 - compact only safe-zone history/noise
 - preserve active task, rules, decisions, and current code focus
 
-UKit v1.1.6 keeps the same shared runtime contract while the npm distribution now lives under the owned maintainer scope:
+UKit v1.1.8 keeps the same shared runtime contract while adding living project status routing for continuity-safe AI sessions:
 
 - install globally with `npm install -g @ngockhoale/ukit`
 - keep using the exact same human workflow inside projects: `ukit install`
 - preserve the same `ukit` binary, hooks, and install-first orchestration while standardizing the runtime root as hidden `.ukit/`
+- install `docs/STATUS.md` as a compact living state file for active work, debug threads, blockers, verification, and next candidates
+- auto-route open-ended “what next?” / “continue” prompts to the `next-step` skill with a visible freshness cue when status may be stale
+- auto-route explicit handoff/wrap-up requests to the `update-status` skill while skipping trivial/no-state-change tasks
+- keep concrete debug/implementation/review prompts primary, so project status never replaces source/index-first task work
 
-UKit v1.1.6 also keeps the fast path improvements from the recent runtime releases:
+UKit v1.1.8 also keeps the fast path improvements from the recent runtime releases:
 
 - Vietnamese prompts now normalize more effectively for English-heavy code symbols and paths
 - localized simple direct-target lanes skip extra previous-context / recent-output work when it would not change the next action

package/manifests/platform.full.yaml

@@ -143,6 +143,22 @@ items:
     packs:
       - core
 
+  - id: docs-status
+    type: config
+    sourceTemplate: docs/STATUS.md
+    targetPath: docs/STATUS.md
+    requires:
+      - docs-project
+      - docs-memory
+      - docs-worklog
+      - docs-code-map
+    mergeStrategy: skip
+    variables:
+      - project.name
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: docs-bugfix
     type: config
     sourceTemplate: docs/BUGFIX.md
@@ -460,6 +476,32 @@ items:
     packs:
       - core
 
+  - id: next-step-skill
+    type: skill
+    sourceTemplate: .claude/skills/next-step/SKILL.md
+    targetPath: .claude/skills/next-step/SKILL.md
+    requires:
+      - docs-quality-skill
+      - docs-status
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: update-status-skill
+    type: skill
+    sourceTemplate: .claude/skills/update-status/SKILL.md
+    targetPath: .claude/skills/update-status/SKILL.md
+    requires:
+      - docs-quality-skill
+      - docs-status
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: docs-manager-skill
     type: skill
     sourceTemplate: .claude/skills/docs-manager
@@ -1000,6 +1042,19 @@ items:
     packs:
       - core
 
+  - id: ukit-index-impact-context-script
+    type: config
+    sourceTemplate: .claude/ukit/index/impact-context.mjs
+    targetPath: .claude/ukit/index/impact-context.mjs
+    requires:
+      - ukit-index-core-lib
+      - ukit-index-cache-utils-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-index-cache-utils-script
     type: config
     sourceTemplate: .claude/ukit/index/cache-utils.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/src/cli/commands/doctor.js

@@ -62,6 +62,7 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
     sessionMemoryDirExists: await pathExists(runtimePaths.sessionsDir),
     docsProjectExists: await pathExists(path.join(projectRoot, 'docs', 'PROJECT.md')),
     docsMemoryExists: await pathExists(path.join(projectRoot, 'docs', 'MEMORY.md')),
+    docsStatusExists: await pathExists(path.join(projectRoot, 'docs', 'STATUS.md')),
     docsWorklogExists: await pathExists(path.join(projectRoot, 'docs', 'WORKLOG.md')),
     allProvidersConfigured: providers.allSupported,
     ...(codexAdapterTracked
@@ -103,6 +104,7 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
   console.log(`[UKit]   ${ok(checks.sessionMemoryDirExists)}  .ukit/storage/memory/sessions/`);
   console.log(`[UKit]   ${ok(checks.docsProjectExists)}  docs/PROJECT.md`);
   console.log(`[UKit]   ${ok(checks.docsMemoryExists)}  docs/MEMORY.md`);
+  console.log(`[UKit]   ${ok(checks.docsStatusExists)}  docs/STATUS.md`);
   console.log(`[UKit]   ${ok(checks.docsWorklogExists)}  docs/WORKLOG.md`);
   if (codexAdapterTracked) {
     console.log(`[UKit]   ${ok(checks.codexReadmeExists)}  .codex/README.md`);

package/src/cli/commands/install.js

@@ -244,9 +244,10 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
   const docsPaths = [
     path.join(projectRoot, 'docs', 'PROJECT.md'),
     path.join(projectRoot, 'docs', 'MEMORY.md'),
+    path.join(projectRoot, 'docs', 'STATUS.md'),
     path.join(projectRoot, 'docs', 'WORKLOG.md'),
   ];
-  const docsLabels = ['docs/PROJECT.md', 'docs/MEMORY.md', 'docs/WORKLOG.md'];
+  const docsLabels = ['docs/PROJECT.md', 'docs/MEMORY.md', 'docs/STATUS.md', 'docs/WORKLOG.md'];
   const missingDocs = [];
   for (let i = 0; i < docsPaths.length; i++) {
     if (!(await pathExists(docsPaths[i]))) {
@@ -257,7 +258,7 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
   if (missingDocs.length > 0) {
     console.log(`[UKit] Missing docs — fill these in before first use: ${missingDocs.join(', ')}`);
   } else {
-    console.log('[UKit] Docs baseline ready: docs/PROJECT.md, docs/MEMORY.md, docs/WORKLOG.md');
+    console.log('[UKit] Docs baseline ready: docs/PROJECT.md, docs/MEMORY.md, docs/STATUS.md, docs/WORKLOG.md');
     console.log('[UKit] Fill them once with real project context for the best results.');
   }
 

package/src/cli/commands/uninstall.js

@@ -47,5 +47,5 @@ export async function runUninstall({ projectRoot, argv = [] }) {
   }
 
   console.log(`[UKit] Uninstall complete. Removed ${result.removed}/${result.attempted} managed paths.`);
-  console.log('[UKit] Note: docs/PROJECT.md, docs/MEMORY.md, docs/WORKLOG.md contain user content and were preserved. Delete manually if needed.');
+  console.log('[UKit] Note: docs/PROJECT.md, docs/MEMORY.md, docs/STATUS.md, docs/WORKLOG.md contain user content and were preserved. Delete manually if needed.');
 }

package/src/core/runtimeConfig.js

@@ -42,7 +42,7 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
   const safeOverrides = isPlainObject(overrides) ? overrides : {};
 
   return mergeObjects({
-    version: '1.1.6',
+    version: '1.1.8',
     agent: 'claude-code',
     compact: {
       enabled: true,

package/src/core/uninstall.js

@@ -200,7 +200,7 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
     }
   } else {
     // Old format (no files list): fall back to hardcoded managed paths.
-    // NOTE: docs/PROJECT.md, MEMORY.md, WORKLOG.md are intentionally excluded.
+    // NOTE: docs/PROJECT.md, MEMORY.md, STATUS.md, WORKLOG.md are intentionally excluded.
     // These are user-created content (mergeStrategy: skip) — deleting them
     // would cause data loss. Users must remove them manually if desired.
     const fallback = buildFallbackPaths(projectRoot);

package/src/index/buildIndex.js

@@ -34,6 +34,9 @@ const TRACKED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'
 const DISCOVERED_EXTENSIONS = new Set([...TRACKED_EXTENSIONS, ...STYLE_EXTENSIONS]);
 export const DEFAULT_INDEX_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const INDEX_PARSE_BATCH_SIZE = 8;
+const CALL_IGNORE_WORDS = new Set([
+  'if', 'for', 'while', 'switch', 'catch', 'function', 'return', 'typeof',
+]);
 
 export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
   const absoluteRoot = path.resolve(rootDir);
@@ -89,6 +92,7 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
 
   const symbols = [];
   const imports = [];
+  const calls = [];
   const reusableCodeFiles = [];
   let filesToParse = [];
   let reusedCodeFileCount = 0;
@@ -109,20 +113,24 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
   }
 
   if (reusableCodeFiles.length > 0) {
-    const [previousSymbolsArtifact, previousImportsArtifact] = await Promise.all([
+    const [previousSymbolsArtifact, previousImportsArtifact, previousCallsArtifact] = await Promise.all([
       readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.symbols),
       readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.imports),
+      readArtifactIfExists(absoluteRoot, INDEX_ARTIFACTS.calls),
     ]);
     canReuseParsedArtifacts = previousSymbolsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
-      && previousImportsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
+      && previousImportsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION
+      && previousCallsArtifact?.schemaVersion === INDEX_SCHEMA_VERSION;
 
     if (canReuseParsedArtifacts) {
       const previousSymbolsByPath = groupBy(previousSymbolsArtifact.items ?? [], (item) => item.filePath);
       const previousImportsByPath = groupBy(previousImportsArtifact.items ?? [], (item) => item.from);
+      const previousCallsByPath = groupBy(previousCallsArtifact.items ?? [], (item) => item.filePath);
 
       for (const filePath of reusableCodeFiles) {
         symbols.push(...(previousSymbolsByPath.get(filePath) ?? []));
         imports.push(...(previousImportsByPath.get(filePath) ?? []));
+        calls.push(...(previousCallsByPath.get(filePath) ?? []));
         reusedCodeFileCount += 1;
       }
     } else {
@@ -145,6 +153,7 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
             ...extractImports(filePath, scriptContent),
             ...extractSupplementalImports(filePath, content),
           ],
+          calls: extractFunctionCalls(filePath, scriptContent),
         };
       } catch {
         return null;
@@ -154,6 +163,7 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
     for (const parsedFile of parsedBatch) {
       symbols.push(...parsedFile.symbols);
       imports.push(...parsedFile.imports);
+      calls.push(...parsedFile.calls);
     }
   }
 
@@ -279,6 +289,12 @@ export async function buildCodeIndex({ rootDir = process.cwd() } = {}) {
       rootDir: absoluteRoot,
       items: imports,
     });
+    await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.calls, {
+      schemaVersion: INDEX_SCHEMA_VERSION,
+      generatedAt,
+      rootDir: absoluteRoot,
+      items: calls,
+    });
   }
   if (!canReuseTestsMap) {
     await writeArtifact(absoluteRoot, INDEX_ARTIFACTS.testsMap, {
@@ -579,6 +595,76 @@ function extractSupplementalImports(filePath, content) {
   return imports;
 }
 
+function extractFunctionBlocks(content) {
+  const blocks = [];
+
+  for (const match of content.matchAll(/export\s+(async\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*\([^)]*\)\s*\{/g)) {
+    blocks.push({ symbol: match[2], exported: true, bodyStart: match.index + match[0].length });
+  }
+
+  for (const match of content.matchAll(/function\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*\([^)]*\)\s*\{/g)) {
+    const prefix = content.slice(Math.max(0, match.index - 16), match.index);
+    if (/export\s+$/.test(prefix)) {
+      continue;
+    }
+    blocks.push({ symbol: match[1], exported: false, bodyStart: match.index + match[0].length });
+  }
+
+  for (const match of content.matchAll(/export\s+const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][A-Za-z0-9_$]*)\s*=>\s*\{/g)) {
+    blocks.push({ symbol: match[1], exported: true, bodyStart: match.index + match[0].length });
+  }
+
+  for (const match of content.matchAll(/const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][A-Za-z0-9_$]*)\s*=>\s*\{/g)) {
+    const prefix = content.slice(Math.max(0, match.index - 16), match.index);
+    if (/export\s+$/.test(prefix)) {
+      continue;
+    }
+    blocks.push({ symbol: match[1], exported: false, bodyStart: match.index + match[0].length });
+  }
+
+  return blocks
+    .map((block) => ({ ...block, body: sliceBalancedBlock(content, block.bodyStart) }))
+    .filter((block) => block.body);
+}
+
+function sliceBalancedBlock(content, startIndex) {
+  let depth = 1;
+  for (let index = startIndex; index < content.length; index += 1) {
+    const char = content[index];
+    if (char === '{') {
+      depth += 1;
+    }
+    if (char === '}') {
+      depth -= 1;
+    }
+    if (depth === 0) {
+      return content.slice(startIndex, index);
+    }
+  }
+  return '';
+}
+
+function extractFunctionCalls(filePath, content) {
+  return extractFunctionBlocks(content).map((block) => {
+    const calls = [];
+    for (const match of block.body.matchAll(/(?:\b|\.)([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g)) {
+      const name = match[1];
+      if (!name || CALL_IGNORE_WORDS.has(name)) {
+        continue;
+      }
+      if (!calls.includes(name)) {
+        calls.push(name);
+      }
+    }
+    return {
+      filePath,
+      symbol: block.symbol,
+      exported: block.exported,
+      calls,
+    };
+  });
+}
+
 function buildTestsMap(fileRecords) {
   const testFiles = fileRecords.filter((file) => isLikelyTestFile(file.filePath));
   const sourceFiles = fileRecords.filter((file) => CODE_EXTENSIONS.has(file.ext) && !isLikelyTestFile(file.filePath));

package/src/index/impactCatalog.js

@@ -0,0 +1,126 @@
+const SHARED_IMPACT_PATTERNS = [
+  {
+    regex: /^src\/index\//,
+    label: 'shared-index-runtime',
+  },
+  {
+    regex: /^src\/core\/(runInstallPipeline|applyPlan|buildPlan|diffPlan|metadata|migrateLegacy|uninstall|runtimeConfig|runtimePaths)\.js$/,
+    label: 'shared-install-runtime',
+  },
+  {
+    regex: /^src\/core\/(output|token|compact)\//,
+    label: 'shared-token-runtime',
+  },
+  {
+    regex: /^templates\/\.claude\/hooks\//,
+    label: 'installed-hook-runtime',
+  },
+  {
+    regex: /^templates\/\.claude\/ukit\//,
+    label: 'installed-helper-runtime',
+  },
+  {
+    regex: /^manifests\/platform\.full\.yaml$/,
+    label: 'install-manifest',
+  },
+  {
+    regex: /^templates\//,
+    label: 'published-template-surface',
+  },
+];
+
+const MIRROR_PAIRS = [
+  {
+    source: 'src/index/buildIndex.js',
+    mirror: 'templates/.claude/ukit/index/lib/index-core.mjs',
+    reason: 'installed index-core mirror embeds source index behavior',
+  },
+  {
+    source: 'src/index/queryIndex.js',
+    mirror: 'templates/.claude/ukit/index/lib/index-core.mjs',
+    reason: 'installed index-core mirror embeds source query behavior',
+  },
+  {
+    source: 'src/index/resolveContext.js',
+    mirror: 'templates/.claude/ukit/index/lib/index-core.mjs',
+    reason: 'installed index-core mirror embeds context resolution behavior',
+  },
+  {
+    source: 'src/index/verificationPlan.js',
+    mirror: 'templates/.claude/ukit/index/lib/index-core.mjs',
+    reason: 'installed index-core mirror embeds verification planning behavior',
+  },
+  {
+    source: 'src/index/taskRouting.js',
+    mirror: 'templates/.claude/ukit/index/route-task.mjs',
+    reason: 'installed route-task helper mirrors source task routing behavior',
+  },
+  {
+    source: 'src/index/routeCatalog.js',
+    mirror: 'templates/.claude/ukit/index/route-catalog.mjs',
+    reason: 'installed route catalog must match source route catalog',
+  },
+  {
+    source: 'src/core/output/index.js',
+    mirror: 'templates/.claude/ukit/runtime/output-compression.mjs',
+    reason: 'source output compression runtime should stay aligned with installed hook runtime',
+  },
+  {
+    source: 'src/core/token/index.js',
+    mirror: 'templates/.claude/ukit/runtime/token-utils.mjs',
+    reason: 'source token runtime should stay aligned with installed token utilities',
+  },
+  {
+    source: 'src/core/compact/threshold.js',
+    mirror: 'templates/.claude/ukit/runtime/compact-threshold.mjs',
+    reason: 'source compact threshold runtime should stay aligned with installed compact threshold hook',
+  },
+];
+
+function normalizePath(filePath) {
+  return String(filePath ?? '').trim().replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+export function isSharedImpactFile(filePath) {
+  const normalized = normalizePath(filePath);
+  return SHARED_IMPACT_PATTERNS.some((entry) => entry.regex.test(normalized));
+}
+
+export function classifyImpactRisk(filePaths = []) {
+  const normalizedPaths = [...new Set(filePaths.map(normalizePath).filter(Boolean))];
+  const riskLabels = [];
+
+  for (const filePath of normalizedPaths) {
+    for (const entry of SHARED_IMPACT_PATTERNS) {
+      if (entry.regex.test(filePath) && !riskLabels.includes(entry.label)) {
+        riskLabels.push(entry.label);
+      }
+    }
+  }
+
+  return {
+    changedFiles: normalizedPaths,
+    riskLabels,
+    requiresImpactCheck: riskLabels.length > 0,
+  };
+}
+
+export function findMirrorCounterparts(filePaths = []) {
+  const normalizedSet = new Set(filePaths.map(normalizePath).filter(Boolean));
+  const counterparts = [];
+
+  for (const pair of MIRROR_PAIRS) {
+    if (normalizedSet.has(pair.source)) {
+      counterparts.push({ filePath: pair.mirror, reason: pair.reason, source: pair.source });
+    }
+    if (normalizedSet.has(pair.mirror)) {
+      counterparts.push({ filePath: pair.source, reason: pair.reason, source: pair.mirror });
+    }
+  }
+
+  return counterparts.filter((entry, index, list) => (
+    list.findIndex((candidate) => candidate.filePath === entry.filePath && candidate.source === entry.source) === index
+  ));
+}
+
+export { MIRROR_PAIRS, SHARED_IMPACT_PATTERNS };