@skiesjs/foundation

Fail-closed proof inventory, criteria matrix, affected gates, and repository-local CSM foundations for plain Node.js applications. The package is strict NodeNext ESM and has no runtime dependencies. Its executable is skies-node-foundation.

Closed proof manifest

Put skies.node.json at the workspace root. Unknown keys, references, proof kinds, duplicate IDs/citations, unsafe paths, invalid timeouts, and dependency cycles are configuration errors.

{
  "schemaVersion": 1,
  "git": { "base": "origin/main" },
  "criteria": [
    { "id": "wallet.withdraw.no-overdraw", "statement": "A withdrawal cannot overdraw the wallet." },
    { "id": "wallet.withdraw.audited", "statement": "A successful withdrawal is observable in the audit trail." }
  ],
  "lanes": [
    {
      "id": "wallet-unit",
      "command": ["npm", "exec", "vitest", "run", "src/wallet/withdraw.test.ts"],
      "timeoutMs": 60000,
      "cwd": ".",
      "env": { "NODE_ENV": "test" }
    },
    {
      "id": "wallet-journey",
      "command": ["npm", "exec", "playwright", "test", "e2e/withdraw.spec.ts"],
      "timeoutMs": 180000
    }
  ],
  "proofs": [
    {
      "id": "withdraw-unit",
      "kind": "unit",
      "lane": "wallet-unit",
      "criteria": ["wallet.withdraw.no-overdraw"],
      "sourceScopes": ["src/wallet/**"],
      "description": "Domain proof"
    },
    {
      "id": "withdraw-journey",
      "kind": "journey",
      "lane": "wallet-journey",
      "criteria": ["wallet.withdraw.audited"],
      "sourceScopes": ["src/wallet/**", "e2e/**"],
      "dependsOn": ["withdraw-unit"]
    }
  ],
  "ignoreScopes": ["docs/**"],
  "forceFullScopes": ["package.json", "package-lock.json", "skies.node.json"]
}

Proof kinds are closed to unit, integration, e2e, and journey. Commands are argv arrays: they never pass through a shell. Each selected lane runs once. A missing executable, timeout, signal, nonzero exit, missing proof, uncovered criterion, or unknown impact is red. Unaffected obligations remain not-affected, never pass.

An ignored scope applies only if no proof or force-full scope matches the path. Any other unmapped changed path widens to every proof. dependsOn adds a deterministic transitive proof closure.

Inventory, criteria, and matrix

skies-node-foundation inventory [--json]
skies-node-foundation criteria check [--json]
skies-node-foundation matrix [--json]
skies-node-foundation matrix --receipt .skies/foundation/gate-receipt.json [--json]

inventory shows commands, timeouts, citations, kinds, and source scopes. criteria requires every declared criterion to have at least one cited proof. A matrix without a receipt reports static covered/no-proof states, not execution passes. With a receipt it recomputes pass, fail, not-run, not-affected, and no-proof from the current manifest; a stale, foreign, duplicate, or unknown receipt fails closed.

Gate modes and receipts

# Explicit paths, useful to hooks and orchestration
skies-node-foundation gate --affected --changed src/wallet/withdraw.ts --changed src/shared/clock.ts

# Git merge-base of git.base and HEAD, plus staged, unstaged, and untracked paths
skies-node-foundation gate --affected
skies-node-foundation gate --affected --merge-base origin/release

# Pre-push scope: committed diff base...HEAD, exhaustive fallbacks deferred to CI
skies-node-foundation gate --base origin/main --fast

# Staged index diff, always bounded
skies-node-foundation gate --staged

# Every proof and canonical release artifacts (release automation only)
skies-node-foundation gate --full

Affected, base, and staged gates write .skies/foundation/gate-receipt.json. Full writes VERIFICATION.json and VERIFICATION.md. Override with --report <path> and --markdown <path>, or use --no-report. --fast defers force-full and unmapped-path widening to authoritative CI; --full and --fast conflict. JSON receipts contain the configuration SHA-256, mode/base, normalized changed paths, selection reasons, argv/cwd/timeout, bounded stdout/stderr, exit/signal/timeout/duration, every proof outcome, criteria matrix, findings, and overall verdict. If Git ancestry is unavailable, affected mode widens to full.

The process runner forwards SIGINT, SIGTERM, and SIGHUP to the active process group, terminates timed-out processes, never enables a shell, and caps captured output. Use the exported CommandRunner, GitClient, and clock seams for deterministic embedding/tests.

Repository-local CSM foundations

skies-node-foundation foundations init [--dry-run] [--agent-file AGENTS.md]
skies-node-foundation foundations sync [--dry-run]
# equivalent structured form
skies-node-foundation foundation stack init

The stack creates csm.toml (the shared CSM storage contract, mirroring the .NET side), a pinned lock, managed Node-focused SKILL.md surfaces, versioned empty stores, and one managed protocol block in detected agent files. A legacy csm.json is still read for migration but never written. A custom nested agent file also installs the portable root AGENTS.md surface. Init refuses conflicting managed files; sync updates only recognized owned assets. Plans are preflighted and applied transactionally. Parent traversal, absolute paths, non-files, and symlinks are rejected. Re-running either operation is idempotent.

CSM records are ordinary formatted JSON text beneath the configured storage root:

skies-node-foundation wtw collect --kind invariant --id server-authority \
  --title "Server authority" --statement "The server owns totals." \
  --violation "A client total is accepted."
skies-node-foundation wtw explain
skies-node-foundation wtw guard

skies-node-foundation rtw add --id co-located-tests --title "Co-locate tests" \
  --guidance "Tests stay below src."
skies-node-foundation rtw guide
skies-node-foundation rtw check

skies-node-foundation nya spec --id magic-color --title "Magic color" \
  --lesson "Use a semantic design token."
skies-node-foundation nya recall
skies-node-foundation nya replay
skies-node-foundation nya check

skies-node-foundation nwc collect --id retry-work --title "Retry work" \
  --action "Finish retry handling."
skies-node-foundation nwc wake
skies-node-foundation nwc resolve --id retry-work
skies-node-foundation nwc check

Mutations accept --dry-run; all operations accept --root, and result/list/check operations accept --json.

Bounded workflows

skies-node-foundation context --task "Add retry status" \
  --path src/status.ts --event dependency:retry-ready --limit 8

skies-node-foundation check --task "Review retry status" --affected
skies-node-foundation check --task "Pre-commit review" --staged
skies-node-foundation check --task "Pre-push review" --base origin/main --fast
skies-node-foundation check --task "Release audit" --full
# equivalent:
skies-node-foundation foundation workflow context --task "Add retry status"
skies-node-foundation foundation workflow check --task "Release audit" --full

context reads a bounded WTW → RTW → NYA → NWC view and performs no network or installation mutation. check always runs gate → WTW → RTW → NYA → NWC, preserving later findings after an earlier red step. Unlike the standalone gate default, workflow check requires an explicit scope.

Exit codes

• 0: successful command (an empty affected change is labeled no-changes, not green)
• 1: gate, proof, criteria, record, or foundation finding
• 2: invalid invocation, manifest/configuration, unsafe filesystem state, or incomplete inspection

Use skies-node-foundation --help for the complete command summary.