@ngockhoale/ukit 3.4.74 → 3.4.76

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/CHANGELOG.md +110 -95
  2. package/manifests/platform.full.yaml +15 -0
  3. package/package.json +14 -4
  4. package/src/cli/commands/markerStore.js +15 -0
  5. package/src/cli/index.js +7 -0
  6. package/src/core/markerStoreMigration.js +122 -0
  7. package/template_project/.claude/hooks/completion-gate.sh +10 -1
  8. package/template_project/.claude/hooks/handoff-resume.sh +9 -0
  9. package/template_project/.claude/hooks/owner-stop-gate.mjs +41 -0
  10. package/template_project/.claude/hooks/skill-router.sh +262 -28
  11. package/template_project/.claude/settings.json +11 -1
  12. package/template_project/.claude/ukit/index/publication-intent.mjs +144 -18
  13. package/template_project/.claude/ukit/index/route-task.mjs +91 -9
  14. package/template_project/.claude/ukit/runtime/cron-operation-adapter.mjs +11 -4
  15. package/template_project/.claude/ukit/runtime/execution-ledger.mjs +369 -29
  16. package/template_project/.claude/ukit/runtime/operation-evidence.mjs +9 -0
  17. package/template_project/.claude/ukit/runtime/resumable-run.mjs +33 -11
  18. package/template_project/.claude/ukit/runtime/stop-coordinator.mjs +161 -32
  19. package/template_project/.omp/hooks/pre/ukit-bridge.js +552 -4
  20. package/scripts/bug/triage.mjs +0 -76
  21. package/scripts/dev/worktree-preflight.mjs +0 -166
  22. package/scripts/docs/render-instructions.mjs +0 -66
  23. package/scripts/index/build-index.mjs +0 -102
  24. package/scripts/index/query-index.mjs +0 -128
  25. package/scripts/index/refresh-index.mjs +0 -195
  26. package/scripts/install/sync-installed-mirror.mjs +0 -263
  27. package/scripts/measure-decision-gateway.mjs +0 -306
  28. package/scripts/probe/codex-capability-probe.mjs +0 -169
  29. package/scripts/skill/audit-skill.mjs +0 -68
  30. package/scripts/test/run-handoff-isolated.mjs +0 -178
@@ -1,195 +0,0 @@
1
- #!/usr/bin/env node
2
- import fs from 'node:fs/promises';
3
- import path from 'node:path';
4
-
5
- import {
6
- buildCodeIndex,
7
- inspectIndexStaleness,
8
- mapLimit,
9
- INDEX_IO_CONCURRENCY,
10
- DEFAULT_INDEX_CACHE_MAX_AGE_MS,
11
- } from '../../src/index/buildIndex.js';
12
-
13
- async function main() {
14
- const args = process.argv.slice(2);
15
- const { value: rootArg, args: afterRootArgs } = extractFlagValue(args, '--root');
16
- const { value: changedArg, args: remainingArgs } = extractFlagValue(afterRootArgs, '--changed');
17
- const force = remainingArgs.includes('--force');
18
- const unexpected = remainingArgs.filter((arg) => arg !== '--force');
19
- if (unexpected.length > 0) {
20
- throw new Error(`unexpected argument: ${unexpected[0]}`);
21
- }
22
-
23
- const rootDir = rootArg ? path.resolve(rootArg) : process.cwd();
24
- const hintedFiles = changedArg
25
- ? changedArg.split(',').map((item) => item.trim()).filter(Boolean)
26
- : [];
27
-
28
- // Hints that exist but cannot be read would be silently dropped by the parse
29
- // worker; surface them and keep them out of the merge set. ENOENT hints are
30
- // kept — a deleted file is a legitimate removal hint.
31
- const { readable: changedFiles, unreadable: unreadableHints } = await partitionReadableHints(rootDir, hintedFiles);
32
- for (const filePath of unreadableHints) {
33
- console.error(`[index:refresh] skipped unreadable file: ${filePath}`);
34
- }
35
-
36
- const lastRefreshMs = await getLastRefreshTime(rootDir);
37
-
38
- if (changedFiles.length > 0 && !force) {
39
- // Hints carry the change set, so no staleness enumeration is needed:
40
- // buildCodeIndex merges the hinted paths into the existing artifacts and
41
- // falls back to the bounded full discovery path on its own when the hints
42
- // are unsafe or the previous artifacts cannot be merged (TASK-023).
43
- const summary = await buildCodeIndex({ rootDir, changedFiles });
44
-
45
- console.log('[index:refresh] completed');
46
- console.log(`mode: ${summary.mode}`);
47
- if (lastRefreshMs !== null) {
48
- console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
49
- }
50
- console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
51
- console.log(`root: ${rootDir}`);
52
- console.log(`files: ${summary.fileCount}`);
53
- console.log(`parsed: ${summary.parsedCodeFileCount}`);
54
- console.log(`reused: ${summary.reusedCodeFileCount}`);
55
- if (summary.removedFiles.length > 0) {
56
- console.log(`removed: ${summary.removedFiles.length}`);
57
- }
58
- console.log(`indexDir: ${summary.indexDir}`);
59
- return;
60
- }
61
-
62
- // One enumeration serves the staleness check, the readability check, and the
63
- // build: the snapshot is handed to buildCodeIndex, which reuses it.
64
- const staleness = await inspectIndexStaleness({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
65
- const stale = force || staleness.stale;
66
-
67
- if (!stale) {
68
- console.log('[index:refresh] skipped (cache fresh)');
69
- if (lastRefreshMs !== null) {
70
- console.log(`lastRefresh: ${new Date(lastRefreshMs).toISOString()}`);
71
- }
72
- if (changedFiles.length > 0) {
73
- console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
74
- }
75
- console.log(`root: ${rootDir}`);
76
- return;
77
- }
78
-
79
- const unreadable = await collectUnreadableFiles(rootDir, staleness.snapshot?.files ?? []);
80
- for (const filePath of unreadable) {
81
- console.error(`[index:refresh] skipped unreadable file: ${filePath}`);
82
- }
83
-
84
- const summary = await buildCodeIndex({
85
- rootDir,
86
- discoverySnapshot: staleness.snapshot,
87
- });
88
-
89
- console.log('[index:refresh] completed');
90
- console.log(`mode: ${summary.mode}`);
91
- if (lastRefreshMs !== null) {
92
- console.log(`lastRefreshBefore: ${new Date(lastRefreshMs).toISOString()}`);
93
- }
94
- if (changedFiles.length > 0) {
95
- console.log(`changed-files-hint: ${changedFiles.join(', ')}`);
96
- }
97
- console.log(`root: ${rootDir}`);
98
- console.log(`files: ${summary.fileCount}`);
99
- console.log(`parsed: ${summary.parsedCodeFileCount}`);
100
- console.log(`reused: ${summary.reusedCodeFileCount}`);
101
- if (unreadable.length > 0) {
102
- console.log(`skipped-unreadable: ${unreadable.length}`);
103
- }
104
- console.log(`indexDir: ${summary.indexDir}`);
105
- }
106
-
107
- // The parse worker inside buildCodeIndex skips files it cannot read; the CLI
108
- // surfaces them so a partial index is never silent.
109
- async function collectUnreadableFiles(rootDir, entries) {
110
- const unreadable = await mapLimit(entries, INDEX_IO_CONCURRENCY, async (entry) => {
111
- try {
112
- await fs.access(entry.absolutePath, fs.constants.R_OK);
113
- return null;
114
- } catch {
115
- return path.relative(rootDir, entry.absolutePath).split(path.sep).join('/');
116
- }
117
- });
118
- return unreadable.filter(Boolean).sort();
119
- }
120
-
121
- async function partitionReadableHints(rootDir, hints) {
122
- const readable = [];
123
- const unreadable = [];
124
- for (const hint of hints) {
125
- try {
126
- await fs.access(path.resolve(rootDir, hint), fs.constants.R_OK);
127
- readable.push(hint);
128
- } catch (error) {
129
- if (error?.code === 'ENOENT') {
130
- readable.push(hint); // deleted file — a legitimate removal hint
131
- } else {
132
- unreadable.push(hint);
133
- }
134
- }
135
- }
136
- return { readable, unreadable };
137
- }
138
-
139
- function extractFlagValue(argv, flag) {
140
- let value = null;
141
- const nextArgs = [];
142
-
143
- for (let i = 0; i < argv.length; i += 1) {
144
- const arg = argv[i];
145
-
146
- if (arg === flag) {
147
- if (value !== null) {
148
- nextArgs.push(arg);
149
- continue;
150
- }
151
- const maybeValue = argv[i + 1];
152
- if (!maybeValue || maybeValue.startsWith('--')) {
153
- throw new Error(`Missing value for ${flag}.`);
154
- }
155
- value = maybeValue;
156
- i += 1;
157
- continue;
158
- }
159
-
160
- if (arg.startsWith(`${flag}=`)) {
161
- if (value === null) {
162
- value = arg.slice(flag.length + 1);
163
- continue;
164
- }
165
- }
166
-
167
- nextArgs.push(arg);
168
- }
169
-
170
- return { value, args: nextArgs };
171
- }
172
-
173
- async function getLastRefreshTime(rootDir) {
174
- const filesPath = path.join(rootDir, '.cache', 'index', 'files.json');
175
-
176
- try {
177
- const raw = await fs.readFile(filesPath, 'utf8');
178
- const artifact = JSON.parse(raw);
179
- const generatedAtRaw = String(artifact?.generatedAt ?? '').trim();
180
- if (!generatedAtRaw) {
181
- return null;
182
- }
183
- const generatedAtMs = Date.parse(generatedAtRaw);
184
- return Number.isNaN(generatedAtMs) ? null : generatedAtMs;
185
- } catch {
186
- return null;
187
- }
188
- }
189
-
190
- try {
191
- await main();
192
- } catch (error) {
193
- console.error(error && error.message ? error.message : error);
194
- process.exit(1);
195
- }
@@ -1,263 +0,0 @@
1
- #!/usr/bin/env node
2
- // C5 (docs/AI_REPORT/archive/2026-09-20-CORRECTNESS.md §C5) — scoped mirror sync/check.
3
- //
4
- // The installed `.claude/` + `.omp/` mirror is a *rendered* copy of `template_project/.claude`
5
- // + `template_project/.omp`, and hand-copying it drifted three separate ways this cycle:
6
- // a template change never re-copied, a raw copy that kept its literal `{{token}}`
7
- // because nobody rendered it, and `settings.json`'s two gateway-injected env keys,
8
- // which make whole-file byte identity impossible by construction. Parallel lanes
9
- // overwrote each other because there was no tool — only whoever remembered.
10
- //
11
- // node scripts/install/sync-installed-mirror.mjs --check report drift, exit non-zero
12
- // node scripts/install/sync-installed-mirror.mjs rewrite drifted targets
13
- //
14
- // This reuses the real install pipeline (`buildInstallPlan` → `diffInstallPlan` →
15
- // `applyDiffResults` → `applyGatewayResilienceEnv`) rather than reimplementing it, so
16
- // "drift" is decided by exactly the code `ukit install` uses — including the
17
- // gateway-env carve-out in `src/core/diffPlan.js` and the render step in
18
- // `src/render/buildTemplateVariables.js`. Render-tokenized templates are compared in
19
- // rendered form; `settings.json` is compared section-wise, never byte-wise.
20
- //
21
- // Scope is deliberately narrow — the tool only ever considers plan targets that live
22
- // under `.claude/**` or `.omp/**`, so it can never touch `src/`, `docs/`, or any
23
- // user-authored file:
24
- //
25
- // * `mergeStrategy: 'skip'` entries (e.g. `.claude/settings.local.json`) are
26
- // user-owned, not template-derived. They are excluded from drift AND from apply —
27
- // a hands-off file must never read as drift, and this tool is not an installer.
28
- // * Mirror-only detection is limited to the target directories of *selected,
29
- // non-link* manifest items — directories UKit owns wholesale from `template_project/`.
30
- // A blanket walk of `.claude/` reports ~226 false positives, because pack-gated
31
- // skill libraries (e.g. `.claude/skills/frontend-vue/**` on a `core`-only project)
32
- // are present in the mirror but intentionally outside the current plan. Those
33
- // directories are covered by `tests/consistency/templateParity.test.js` instead.
34
- import fs from 'node:fs/promises';
35
- import path from 'node:path';
36
- import { fileURLToPath } from 'node:url';
37
-
38
- import { buildPathConfig } from '../../src/core/paths.js';
39
- import { loadManifest } from '../../src/manifest/loadManifest.js';
40
- import { detectStack } from '../../src/stack/detectStack.js';
41
- import { detectProjectContext } from '../../src/context/detectProjectContext.js';
42
- import { detectProviders } from '../../src/context/detectProviders.js';
43
- import { loadRuntimeConfig } from '../../src/core/runtimeConfig.js';
44
- import { buildTemplateVariables } from '../../src/render/buildVariables.js';
45
- import { buildInstallPlan } from '../../src/core/buildPlan.js';
46
- import { diffInstallPlan } from '../../src/core/diffPlan.js';
47
- import { applyDiffResults } from '../../src/core/applyPlan.js';
48
- import { applyGatewayResilienceEnv } from '../../src/core/gatewayResilienceEnv.js';
49
-
50
- const MANAGED_PREFIXES = ['.claude/', '.omp/'];
51
- const USAGE = 'usage: sync-installed-mirror.mjs [--check]';
52
-
53
- function isManaged(relativePath) {
54
- return MANAGED_PREFIXES.some((prefix) => relativePath.startsWith(prefix));
55
- }
56
-
57
- function toRelative(projectRoot, targetPath) {
58
- return path.relative(projectRoot, targetPath).split(path.sep).join('/');
59
- }
60
-
61
- async function readPackageVersion(packageRoot) {
62
- try {
63
- const pkg = JSON.parse(await fs.readFile(path.join(packageRoot, 'package.json'), 'utf8'));
64
- return typeof pkg.version === 'string' ? pkg.version : null;
65
- } catch {
66
- return null;
67
- }
68
- }
69
-
70
- // The full set of paths the plan manages, used to decide whether a file found in the
71
- // mirror is unmanaged. Built from every entry (not just the managed ones) so a path
72
- // that is managed by an out-of-scope entry is never reported as mirror-only.
73
- function buildPlanTargetSet(plan, projectRoot) {
74
- return new Set(
75
- plan.entries
76
- .map((entry) => toRelative(projectRoot, entry.targetPath))
77
- .filter(Boolean),
78
- );
79
- }
80
-
81
- async function collectFilesRecursively(dir, out) {
82
- let entries;
83
- try {
84
- entries = await fs.readdir(dir, { withFileTypes: true });
85
- } catch {
86
- return out; // missing or unreadable directory — the create-drift lane covers it
87
- }
88
-
89
- for (const entry of entries) {
90
- const fullPath = path.join(dir, entry.name);
91
- // Symlinks are the adapter-link lane's business (`type: 'link'` items are excluded
92
- // from mirror-only detection), and following one would walk another tool's tree.
93
- if (entry.isSymbolicLink()) continue;
94
- if (entry.isDirectory()) {
95
- await collectFilesRecursively(fullPath, out);
96
- continue;
97
- }
98
- if (entry.isFile()) out.push(fullPath);
99
- }
100
-
101
- return out;
102
- }
103
-
104
- // Directories UKit installs wholesale from a template directory. Any file inside one
105
- // that the plan does not ship is mirror-only drift rather than user content.
106
- async function collectManagedDirectoryRoots({ plan, templatesRoot }) {
107
- const roots = [];
108
-
109
- for (const item of plan.selectedItems) {
110
- if (item.type === 'link') continue;
111
- const target = String(item.targetPath ?? '');
112
- if (!isManaged(target)) continue;
113
-
114
- const source = path.join(templatesRoot, String(item.sourceTemplate ?? ''));
115
- let stat;
116
- try {
117
- stat = await fs.stat(source);
118
- } catch {
119
- continue;
120
- }
121
- if (stat.isDirectory()) roots.push(target.replace(/\/+$/, ''));
122
- }
123
-
124
- return roots;
125
- }
126
-
127
- async function collectMirrorOnlyPaths({ plan, projectRoot, templatesRoot }) {
128
- const planTargets = buildPlanTargetSet(plan, projectRoot);
129
- const roots = await collectManagedDirectoryRoots({ plan, templatesRoot });
130
- const mirrorOnly = [];
131
-
132
- for (const root of roots) {
133
- const files = await collectFilesRecursively(path.join(projectRoot, root), []);
134
- for (const file of files) {
135
- const relativePath = toRelative(projectRoot, file);
136
- if (!planTargets.has(relativePath)) mirrorOnly.push(relativePath);
137
- }
138
- }
139
-
140
- return [...new Set(mirrorOnly)].sort();
141
- }
142
-
143
- // Hooks write their own state under `<managed dir>/.ukit/storage/` (stop-coordinator, task-watchdog,
144
- // observability). That is protected runtime state, not template drift: it is reported for transparency but never
145
- // fails the check, is never rewritten, and is never offered for deletion. Any other unshipped file stays mirror-only.
146
- const RUNTIME_STATE_SEGMENT = '/.ukit/storage/';
147
- function splitRuntimeState(paths) {
148
- const runtimeState = paths.filter((p) => `/${p}`.includes(RUNTIME_STATE_SEGMENT));
149
- return { mirrorOnly: paths.filter((p) => !runtimeState.includes(p)), runtimeState };
150
- }
151
-
152
- async function main() {
153
- const args = process.argv.slice(2);
154
- const unknown = args.filter((arg) => arg !== '--check');
155
- if (unknown.length > 0) {
156
- console.error(`${USAGE}\nunknown flag: ${unknown[0]}`);
157
- process.exit(2);
158
- }
159
-
160
- const checkOnly = args.includes('--check');
161
- const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
162
- const projectRoot = process.cwd();
163
- const pathConfig = buildPathConfig({ packageRoot, projectRoot });
164
-
165
- const manifest = await loadManifest(pathConfig.manifestPath);
166
- const stackContext = await detectStack(projectRoot);
167
- const projectContext = await detectProjectContext(projectRoot);
168
- const providerContext = await detectProviders(projectRoot);
169
- const runtimeConfig = await loadRuntimeConfig(projectRoot);
170
-
171
- // Same variable set as `runInstallPipeline`, so render-tokenized templates compare
172
- // in the exact form `ukit install` would have written them.
173
- const variables = buildTemplateVariables({
174
- projectContext,
175
- stackContext,
176
- packageVersion: await readPackageVersion(packageRoot),
177
- providerContext,
178
- runtimeConfig,
179
- });
180
-
181
- const plan = await buildInstallPlan({
182
- manifest,
183
- stackContext,
184
- templatesRoot: pathConfig.templatesRoot,
185
- variables,
186
- projectRoot,
187
- // Omitted: `ukit install`'s own default adapter set (claude + codex + omp), so the
188
- // `.omp/**` half of the mirror is in scope.
189
- selectedAdapterItemIds: undefined,
190
- });
191
-
192
- const managedEntries = plan.entries.filter((entry) => {
193
- if (entry.mergeStrategy === 'skip') return false;
194
- return isManaged(toRelative(projectRoot, entry.targetPath));
195
- });
196
- const managedRelativePaths = new Set(managedEntries.map((entry) => toRelative(projectRoot, entry.targetPath)));
197
-
198
- const diffResults = await diffInstallPlan({ entries: managedEntries });
199
- const drift = diffResults
200
- .filter((entry) => entry.action === 'create' || entry.action === 'update')
201
- .map((entry) => ({ entry, relativePath: toRelative(projectRoot, entry.targetPath) }))
202
- .sort((a, b) => a.relativePath.localeCompare(b.relativePath));
203
-
204
- const { mirrorOnly, runtimeState } = splitRuntimeState(await collectMirrorOnlyPaths({
205
- plan,
206
- projectRoot,
207
- templatesRoot: pathConfig.templatesRoot,
208
- }));
209
-
210
- if (checkOnly) {
211
- for (const { entry, relativePath } of drift) {
212
- console.log(`DRIFT ${relativePath} (${entry.action})`);
213
- }
214
- for (const relativePath of mirrorOnly) {
215
- console.log(`MIRROR-ONLY ${relativePath}`);
216
- }
217
- for (const relativePath of runtimeState) {
218
- console.log(`RUNTIME-STATE ${relativePath} (protected; not drift)`);
219
- }
220
-
221
- const stateNote = runtimeState.length ? `, ${runtimeState.length} protected runtime-state file(s) ignored` : '';
222
- if (drift.length === 0 && mirrorOnly.length === 0) {
223
- console.log(`ukit mirror check: clean (${managedRelativePaths.size} scoped targets${stateNote})`);
224
- return 0;
225
- }
226
-
227
- console.log(
228
- `ukit mirror check: ${drift.length} drifted, ${mirrorOnly.length} mirror-only `
229
- + `(${managedRelativePaths.size} scoped targets${stateNote})`,
230
- );
231
- return 1;
232
- }
233
-
234
- const { writes } = await applyDiffResults(
235
- drift.map(({ entry }) => entry),
236
- { backupRoot: pathConfig.backupRoot, projectRoot },
237
- );
238
- for (const write of writes) {
239
- console.log(`${write.action === 'create' ? 'CREATED' : 'UPDATED'} ${toRelative(projectRoot, write.targetPath)}`);
240
- }
241
-
242
- // Re-running the managed-gateway step is what makes a rewritten `settings.json`
243
- // whole again: the rendered template does not carry the two injected env keys, so
244
- // serializing the template alone would drop them.
245
- const gateway = await applyGatewayResilienceEnv({ projectRoot });
246
- if (gateway.changed) {
247
- console.log(`ukit mirror sync: re-applied managed gateway env keys (${[...gateway.applied, ...gateway.migrated].join(', ')})`);
248
- }
249
-
250
- for (const relativePath of mirrorOnly) {
251
- console.log(`MIRROR-ONLY ${relativePath} — not shipped by any template; left in place, remove it by hand if stale`);
252
- }
253
-
254
- console.log(`ukit mirror sync: ${writes.length} written, ${mirrorOnly.length} mirror-only left in place`);
255
- return 0;
256
- }
257
-
258
- try {
259
- process.exit(await main());
260
- } catch (error) {
261
- console.error(error && error.message ? error.message : error);
262
- process.exit(1);
263
- }