Parent Tracking Issue: Package consumption and dev-link readiness

[Yuri-bara]

Goal

Track the staged work needed to make the standalone calculogic-validator package installable, updatable, and usable from other repositories without manual rootization or embedded-path repair.

This is a parent roadmap / tracking issue.

Do not complete this issue with one PR. Each minimal PR should reference this issue with Refs #<issue-number> or Implements part of #<issue-number>.

Do not use closing keywords unless the human owner explicitly asks for automatic closure.

The human owner will close this issue manually after all intended minimal-slice comments are present.

Current model problem

PR #6 rootized the adopted embedded validator into the standalone package, and post-merge verification confirmed the package is broadly healthy:

• npm test passed with 672/672 tests.
• package host bins resolved.
• report examples were deterministic.
• npm pack --dry-run looked structurally sane.

However, the package is not yet fully proven as a consumer-ready tool. A confirmed follow-up concern remains: Tree still appears to emit TREE_VALIDATOR_OWNED_FILE_OUTSIDE_TREE findings that expect calculogic-validator/ as the validator-owned root during standalone --scope=validator scans.

The broader target is not only “standalone repo works,” but “another repo can install, run, update, and optionally live-link the validator without needing manual fixes.”

Target model direction

The validator should support these contexts cleanly:

Embedded development

• target repo root: .
• package root / validator development root: calculogic-validator/

Standalone validator development

• target repo root: .
• package root / validator development root: .

Installed consumer mode

• target repo root: consumer project
• package root: installed dependency/tool package
• validator development root: absent unless explicitly validating the validator package itself

The final package-consumer story should support:

• packed tarball install mode
• GitHub/git install mode
• normal future registry install mode
• local folder install mode, if practical
• npm link / live dev-link mode for developing the validator while testing it in another repo
• repeatable update mode without manual rootization fixes

Minimal slice sequence

Slice 1 — Fix Tree validator-owned root expectation

Acceptance criteria:

• npm run validate:tree -- --scope=validator no longer emits stale validator-owned-root findings merely because standalone files are not under calculogic-validator/.
• Tree preserves the distinction between embedded development, standalone validator development, and installed consumer mode.
• The fix does not suppress findings by broad exception.
• Focused tests cover standalone-root validator-owned file expectations.
• npm test remains green.

Slice 2 — Audit package consumption and dev-link readiness

Acceptance criteria:

• npm pack / tarball install is tested in a temporary consumer repo.
• Public bins resolve from the consumer repo.
• Installed consumer mode does not require a calculogic-validator/ folder in the consumer repo.
• Installed consumer mode does not treat node_modules as normal source unless explicitly targeted.
• Git install, local folder install, and npm link dev mode are inspected and classified.
• Update-mode recommendations are documented.
• Any blockers are classified as package metadata, runtime path/root, Tree/Naming policy, docs-only, or environment-only.

Slice 3 — Implement focused package-consumer fixes, if needed

Acceptance criteria:

• Only confirmed blockers from Slice 2 are fixed.
• Package metadata, files, bin, dependencies, and runtime file access are aligned with the intended install modes.
• No unrelated Naming or Tree policy cleanup is included.
• Packed install and bin smoke checks pass from a temporary consumer repo.

Slice 4 — Document install, update, and dev-link workflows

Acceptance criteria:

• README active usage examples use standalone-root paths, not embedded calculogic-validator/bin/... commands.
• Install/update/dev-link workflows are documented in a way that distinguishes normal consumer use from validator development.
• Historical audit/spec references are not broadly rewritten unless they actively confuse current usage.

Non-goals for this parent issue

Across child/minimal PRs, avoid broadening into:

• unrelated Naming finding cleanup
• broad Tree policy redesign
• broad docs reorganization
• publishing to npm before local package-consumer behavior is proven
• reintroducing embedded runtime assumptions as the default standalone path
• treating advisory validator findings as permission for unrelated cleanup

Suggested verification themes

Minimal PRs under this issue should report the exact commands they run. Useful commands include:

npm test
npm run validate:tree -- --scope=validator
npm run validate:all -- --scope=validator
npm pack --dry-run
npm pack

For package-consumer checks, use a temporary consumer repo and verify installed bins, for example:

npm init -y
npm install /path/to/calculogic-validator-*.tgz
npx calculogic-validate --help
npx calculogic-validate-naming --help
npx calculogic-validate-tree --help
npx calculogic-validator-health --help

Issue update process

Each minimal PR should:

• reference this issue with Refs #<issue-number> or Implements part of #<issue-number>
• avoid closing keywords unless the human owner explicitly asks
• keep scope to one minimal slice
• record exact verification commands and outcomes

After each PR is merged, add a comment to this issue summarizing:

### Slice <number> completed

Merged PR: #<pr-number>

Summary:

- <what changed>
- <what remained intentionally unchanged>

Verification:

- `<command>` — <outcome>
- `<command>` — <outcome>

Next slice:

- <recommended next minimal step>

The human owner will close this issue manually after all intended slice-completion comments are present.