feat: npm publish readiness — version, update-check, install scripts (#286–#289)

[flyingrobots]

Summary

• Add files whitelist, publishConfig, and version export for npm publish readiness (feat: npm install -g readiness — files field, publishConfig, --version flag #286)
• Add --version flag and update-check notifications with hexagonal architecture and Alfred resilience (feat: update check notifications — non-blocking version detection #287)
• Add install.sh and uninstall.sh for ~/.local/bin support (feat: install.sh and uninstall.sh for ~/.local/bin support #288)
• Rename package from @neuroglyph/git-mind to @flyingrobots/git-mind (chore: transfer repo from neuroglyph to flyingrobots org #289)
• Docker-isolated integration test runner for publish verification (feat: update check notifications — non-blocking version detection #287)
• Full test coverage for version module and update-check (feat: npm install -g readiness — files field, publishConfig, --version flag #286, feat: update check notifications — non-blocking version detection #287)
• Remove unused policy variable lint violation (Dogfood git-mind suggest action with Claude CLI #293)

Problem Statement

Package is not publishable to npm — missing files whitelist, publishConfig, version export, install scripts, and correct package name. Users cannot install via npm or run update checks.

ADR Compliance (Required)

Relevant ADR(s)

• None

Compliance Declaration

• This PR is fully compliant with all checked ADRs.

---

Architecture Laws Checklist (Hard Gates)

Canonical Truth & Context

• Graph remains canonical truth (no dual truth with generated files).
• No hidden worktree coupling introduced in core/domain/materialization paths.
• Context-sensitive behavior is explicit (--at, --observer, --trust) or deterministically defaulted.
• Resolved context is surfaced in output metadata where applicable.

Determinism & Provenance

• Pure query/materialization paths remain deterministic for identical inputs.
• Mutations/materializations include provenance receipts/envelopes where required.
• Cache keys (if used) are derived only from semantic inputs + pinned versions.

Artifact Hygiene

• No forbidden generated artifact paths are tracked.
• Any generated artifacts intentionally tracked are in allowlisted publish paths only.
• Pre-commit/CI policy checks updated or confirmed valid.

Contracts & Compatibility

• Machine-facing outputs are schema-versioned.
• Breaking contract changes include version bump + migration notes.
• Backward compatibility impact is documented below.

Extension/Effects Safety (if applicable)

• Extension behavior does not bypass capability restrictions.
• Effectful operations use explicit plan/apply semantics and emit receipts.
• Timeouts/resource bounds are defined for new script/effect paths.

---

Scope Control

• PR is single-purpose/cohesive (no unrelated refactors).
• Any non-essential refactor is split into separate PR(s) or explicitly justified.

Backward Compatibility

• CLI/API contract changes: Added --version flag (additive). Package renamed from @neuroglyph/git-mind to @flyingrobots/git-mind (breaking for existing installs).
• Data model/storage changes: None
• Migration required?: Users must npm install @flyingrobots/git-mind instead of old package name
• User-facing behavior changes: --version flag prints version and exits. Update-check notification on CLI startup.

Test Plan (Required)

Unit

• Added/updated tests for changed logic
• Commands:

npm test -- test/version.test.js test/update-check.test.js

Integration

• Added/updated integration tests
• Commands:

# Docker-isolated integration test runner
docker build -f test/Dockerfile -t git-mind-test .

Determinism

• Determinism assertions included for relevant paths
• Method: Update-check uses deterministic cache key derivation
• Commands:

npm test

Contract/Schema

• Schema validation updated/passing
• Commands:

npm run lint

Policy Gates

• Mechanical architecture gates pass
• Commands:

npm test && npm run lint

---

Security / Trust Impact

• Threat surface changed?: Update-check fetches from npm registry (network call, bounded by Alfred timeout/retry policy)
• Trust policy impact: None
• Provenance/audit impact: None
• New failure modes introduced: Network timeout on update check (gracefully handled, non-blocking)

Performance Impact

• Hot path affected?: No — update check is async and non-blocking on CLI startup
• Expected impact (latency/memory/io): Minimal — single HTTP fetch with 3s timeout, cached for 24h
• Benchmarks or profiling evidence: N/A

Observability / Debuggability

• Errors are actionable and include context.
• Logs/diagnostics added or updated where needed.
• git mind status / diagnostics updated if writeback/eventing behavior changed.

Operational Notes

• Feature flag (if any): None
• Rollback strategy: Revert commits
• Operational caveats: ANTHROPIC_API_KEY not needed for this PR

Linked Issues / Milestones

• Closes feat: npm install -g readiness — files field, publishConfig, --version flag #286
• Closes feat: update check notifications — non-blocking version detection #287
• Closes feat: install.sh and uninstall.sh for ~/.local/bin support #288
• Closes chore: transfer repo from neuroglyph to flyingrobots org #289
• Milestone: npm publish readiness

---

Reviewer Quick Verdict Block (for maintainers)

MUST (Hard Gates)

•	PASS
•	CONDITIONAL
•	FAIL

SHOULD (Quality)

•	PASS
•	CONDITIONAL
•	FAIL

Verdict

•	APPROVE
•	APPROVE WITH CHANGES
•	REJECT