CLI crashes on any registry-loading invocation (e.g. `--help`): Cannot find module 'quality/metrics-collector' (5.2.9 and 5.3.0)

[pradeaguiar]

Summary

After a clean install via npx -y aiox-core@5.3.0 install --ci --merge --ide claude-code, any CLI invocation that loads the command registry crashes at require time. Reproduced identically on 5.2.9 and 5.3.0 (@aiox-squads/core-internal).

Repro

npx -y aiox-core@5.3.0 install --ci --merge --ide claude-code   # completes OK, all checks passed
node .aiox-core/cli/index.js --help

Error

Error: Cannot find module '../../../quality/metrics-collector'
Require stack:
- .aiox-core/cli/commands/metrics/record.js
- .aiox-core/cli/commands/metrics/index.js
- .aiox-core/cli/index.js

Root cause (as observed in the installed tree)

• cli/commands/metrics/{record,show,cleanup}.js:12 do const { MetricsCollector } = require('../../../quality/metrics-collector');
• That resolves to .aiox-core/quality/metrics-collector, but no quality/ directory exists anywhere in the installed tree (checked recursively).
• The metrics command module is loaded eagerly by cli/index.js via cli/commands/metrics/index.js, so even --help dies — the whole CLI is unusable, not just the metrics subcommands.

Environment

• macOS (darwin 25.5), Node v22.21.0
• Installed payload: @aiox-squads/core-internal@5.3.0 (also verified on the previously vendored 5.2.9 — same files, same missing module)

Suggested fixes (either works)

1. Ship quality/metrics-collector in the published payload package, or
2. Lazy-require MetricsCollector inside the metrics command handlers (and/or guard the require) so a missing optional module cannot brick the entire CLI registry load.

🤖 Filed with Claude Code on behalf of a project using AIOX.

[maiquelfrantz]

Reproduced on Windows 11 / Node v24.19.0 with a vendored @aiox-squads/core-internal@5.3.0 tree — same crash, same require stack. But the root cause on 5.3.0 is not the same as #782, and I think that changes the fix.

The published tarball is fine — the installed tree isn't

npm pack @aiox-squads/core@5.3.0 and unpack: package/.aiox-core/quality/ is present, with all four files.

package/.aiox-core/quality/metrics-collector.js
package/.aiox-core/quality/metrics-hook.js
package/.aiox-core/quality/seed-metrics.js
package/.aiox-core/quality/schemas/quality-metrics.schema.json

So for 5.3.0 this is an install-time gap, not a publish gap. #782 (published without quality/) was a different bug at 5.2.9.

It's 28 files, not 4

Diffing the tarball's .aiox-core/ against the installed tree (normalizing CRLF→LF, otherwise Windows shows 100% divergence on line endings alone):

Group	Count	Files
quality/	4	metrics-collector.js, metrics-hook.js, seed-metrics.js, schemas/quality-metrics.schema.json
hooks/	13	ids-post-commit.js, ids-pre-push.js, gemini/* (6), unified/* (5)
utils/	7	aiox-validator.js, format-duration.js, filters/* (5)
root config	4	framework-config.yaml, project-config.yaml, local-config.yaml.template, governance/global-heuristic-hints.yaml

Nothing was gitignored — the files simply never arrived.

The correlation that explains it: install-manifest.yaml

.aiox-core files in the published 5.3.0 tarball : 1208
declared in install-manifest.yaml               : 1164
in the package but NOT declared                 :   44

of the 28 files missing from the install:
  declared in the manifest     :  0
  NOT declared in the manifest : 28

Every single missing file is one the manifest doesn't declare. The other 16 undeclared files did land (constitution.md, core/docs/*, docs/standards/*, schemas/*, presets/README.md), which reads like they're copied by explicit installer rules rather than by the manifest.

So the generator behind install-manifest.yaml isn't covering the full payload, and whatever it omits gets dropped at install time unless something else special-cases it.

Consequence: aiox validate can't see this

$ aiox validate
Integrity Score: 100%
Total files: 1164 | Valid: 1162 | Corrupted: 2

100% integrity on a tree where the CLI can't even print --help — because validation only walks the 1164 declared files. This class of breakage is invisible to the tool built to catch it, which is probably the more important half of the bug.

Suggested fix, refining the two options already in this issue

1. Make the manifest cover the whole payload. Either fix scripts/generate-install-manifest.js so file_count matches what ships, or stop using the manifest as the copy list and use it only for change detection. Right now it's silently both, and the two roles disagree.
2. Keep the guarded require anyway (option 2 in the issue body) as defense in depth. cli/index.js requires all eleven command groups at module top level, so one missing file takes down doctor, sdc, wave, qa, config — everything. I prototyped it: wrapping each group in a safeRequire that tolerates only MODULE_NOT_FOUND, collects the failures, and prints them on stderr turned "framework dead" into "one command group unavailable, and here's why". Small patch, and it would have made this issue a one-line warning instead of a full outage.

Worth noting the two are independent: (1) alone leaves the CLI brittle to any future packaging slip; (2) alone leaves the tree incomplete but at least legible.

After restoring the 28 files, the next wall is #808

With quality/ back in place the CLI still died on Cannot find module 'ajv-formats' — which is exactly #808. Confirming that one from a second platform: .aiox-core/package.json (core-internal) declares 15 deps, but .aiox-core/ code hard-requires ajv-formats, handlebars, chokidar and asciichart, all of which are declared only in the root package.json of the published package — and that file isn't part of the vendored payload.

ajv-formats -> core/config/config-resolver.js, core/registry/validate-registry.js,
               product/templates/engine/validator.js, quality/metrics-collector.js
handlebars  -> product/templates/engine/renderer.js          (top-level require)
chokidar    -> core/ids/registry-updater.js                  (lazy, unguarded)
asciichart  -> core/graph-dashboard/renderers/stats-renderer.js

(require('yaml') also shows up in core/code-intel/providers/registry-provider.js and utils/filters/index.js, but both are guarded fallbacks after js-yaml, which is declared — not a bug, listing it so nobody else chases it.)

Repro

npm pack @aiox-squads/core@5.3.0
tar -xzf aiox-squads-core-5.3.0.tgz
diff <(cd package/.aiox-core && find . -type f | sort) \
     <(cd <project>/.aiox-core && find . -type f -not -path './node_modules/*' | sort)

Workaround in use

Restored the 28 files from the published tarball at the matching version and declared the four missing deps in the consuming project's root package.json — Node resolution walks up the directory tree, so .aiox-core/ finds them without editing any framework file (editing .aiox-core/package.json would make aiox validate flag it as corrupted forever). aiox doctor went from 13 PASS / 2 FAIL to 15 PASS / 0 FAIL.

🤖 Investigated with Claude Code on behalf of a project using AIOX.