@smartmemory/compose 0.1.6-beta → 0.1.8-beta

package/README.md

@@ -34,9 +34,20 @@ compose build TODO-1
 
 Prerequisites: Node.js 18+ and `stratum-mcp` on PATH (`pip install stratum`). Codex steps additionally need the OpenAI `codex` CLI. Full prereqs in [docs/install.md](docs/install.md).
 
+The package is published to npm as `@smartmemory/compose`. Pick one install style:
+
+**Option A — npm (recommended for users):**
+
+```bash
+npm install -g @smartmemory/compose
+compose setup                # global skill + stratum-mcp registration
+```
+
+**Option B — git clone (for development):**
+
 ```bash
 git clone https://github.com/smartmemory/compose.git && cd compose && npm install
-npx compose setup            # global skill + stratum-mcp registration
+npx @smartmemory/compose setup   # or: node bin/compose.js setup
 ln -s "$(pwd)/bin/compose.js" ~/bin/compose && chmod +x ~/bin/compose   # optional: bare `compose` command
 ```
 
@@ -44,15 +55,31 @@ Then in your project:
 
 ```bash
 cd /path/to/your/project
-npx compose init             # writes .compose/, registers MCP, scaffolds ROADMAP and pipeline specs
-npx compose new "what you want to build"
+compose init                 # writes .compose/, registers MCP, scaffolds ROADMAP and pipeline specs
+compose new "what you want to build"
 ```
 
 Add an isolated feature to an existing project:
 
 ```bash
-npx compose feature AUTH-1 "JWT middleware with refresh tokens"
-npx compose build AUTH-1
+compose feature AUTH-1 "JWT middleware with refresh tokens"
+compose build AUTH-1
+```
+
+## Upgrading
+
+One command — auto-detects whether compose was installed via npm or git clone:
+
+```bash
+compose update
+```
+
+For npm installs, this runs `npm install -g @smartmemory/compose@latest`. For git clones, it runs `git pull --ff-only && npm install`. Either way it then refreshes the global skill and (if invoked from inside a Compose project) re-runs `compose init` to refresh `.mcp.json` and pipeline templates. Use `compose update --force` to bypass the dirty-tree check on git clones.
+
+Check what you're running:
+
+```bash
+compose --version
 ```
 
 ## Documentation

package/bin/compose.js

@@ -10,7 +10,7 @@
  * compose fix      — headless bug-fix lifecycle runner (pipelines/bug-fix.stratum.yaml)
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, rmSync, readdirSync } from 'fs'
-import { resolve, join, basename, dirname } from 'path'
+import { resolve, join, basename, dirname, sep } from 'path'
 import { homedir } from 'os'
 import { spawn, spawnSync } from 'child_process'
 import { fileURLToPath } from 'url'
@@ -23,7 +23,8 @@ const PACKAGE_ROOT = resolve(__dirname, '..')
 // --team flag (COMP-TEAMS)
 // ---------------------------------------------------------------------------
 import { parseTeamFlag } from '../lib/team-flag.js';
-import { loadDeps, checkExternalSkills, printDepReport } from '../lib/deps.js';
+import { loadDeps, checkExternalSkills, printDepReport, buildDepReport } from '../lib/deps.js';
+import { checkLatestVersion } from '../lib/version-check.js';
 
 const [,, cmd, ...args] = process.argv
 
@@ -31,6 +32,20 @@ const [,, cmd, ...args] = process.argv
 // Help
 // ---------------------------------------------------------------------------
 
+if (cmd === '--version' || cmd === '-V' || cmd === 'version') {
+  const pkgPath = join(PACKAGE_ROOT, 'package.json')
+  let version = 'unknown'
+  try { version = JSON.parse(readFileSync(pkgPath, 'utf-8')).version } catch {}
+  console.log(`compose ${version}`)
+  const gitDir = join(PACKAGE_ROOT, '.git')
+  if (existsSync(gitDir)) {
+    const sha = spawnSync('git', ['-C', PACKAGE_ROOT, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf-8' })
+    if (sha.status === 0) console.log(`  git: ${sha.stdout.trim()}`)
+  }
+  console.log(`  root: ${PACKAGE_ROOT}`)
+  process.exit(0)
+}
+
 if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log('Usage: compose <command>')
   console.log('')
@@ -49,7 +64,9 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   console.log('  qa-scope  Show affected routes from a feature\'s changed files')
   console.log('  init      Initialize Compose in the current project')
   console.log('  setup     Install global skill + register stratum-mcp')
+  console.log('  update    Pull latest compose, reinstall deps, refresh global skill')
   console.log('  doctor    Check external skill dependencies')
+  console.log('  --version Print compose version, git SHA, and install root')
   process.exit(0)
 }
 
@@ -195,10 +212,11 @@ function syncSkills(agents) {
 // compose doctor — re-run the external dep check
 // ---------------------------------------------------------------------------
 
-function runDoctor(flags = []) {
+async function runDoctor(flags = []) {
   const json = flags.includes('--json')
   const strict = flags.includes('--strict')
   const verbose = flags.includes('--verbose') || flags.includes('-v')
+  const refresh = flags.includes('--refresh-versions')
 
   const deps = loadDeps(PACKAGE_ROOT)
   if (!deps) {
@@ -206,8 +224,39 @@ function runDoctor(flags = []) {
     process.exit(1)
   }
   const result = checkExternalSkills(deps)
-  const allRequiredPresent = printDepReport(result, { json, verbose })
 
+  // Version drift check — never fails the doctor run.
+  const currentVersion = (() => {
+    try { return JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf-8')).version }
+    catch { return null }
+  })()
+  const versionInfo = await checkLatestVersion(currentVersion, { force: refresh })
+
+  if (json) {
+    // Single top-level JSON document — the deps report and the version block share one root
+    // so consumers like `JSON.parse(stdout)` work. (Previously two concatenated objects.)
+    const report = buildDepReport(result)
+    console.log(JSON.stringify({ ...report, version: versionInfo }, null, 2))
+    const allRequiredPresent = result.missing.every(d => d.optional)
+    if (strict && !allRequiredPresent) process.exit(1)
+    return
+  }
+
+  // Version section — printed first so it's visible above long dep lists.
+  console.log('Version:')
+  console.log(`  installed: ${currentVersion ?? 'unknown'}`)
+  if (versionInfo) {
+    console.log(`  latest:    ${versionInfo.latest} (${versionInfo.source})`)
+    if (versionInfo.behind) {
+      console.log(`  ⚠ behind — run: compose update`)
+    } else {
+      console.log(`  ✓ up to date`)
+    }
+  } else {
+    console.log(`  latest:    unavailable (registry unreachable or cache missing)`)
+  }
+
+  const allRequiredPresent = printDepReport(result, { json: false, verbose })
   if (strict && !allRequiredPresent) process.exit(1)
 }
 
@@ -434,6 +483,114 @@ function runSetup() {
   }
 }
 
+// ---------------------------------------------------------------------------
+// compose update — pull latest, reinstall deps, refresh global skill
+// ---------------------------------------------------------------------------
+
+function detectInstallStyle() {
+  // npm install resolves bin to either:
+  //   - global: /<prefix>/lib/node_modules/@smartmemory/compose/bin/compose.js
+  //   - local:  <project>/node_modules/@smartmemory/compose/bin/compose.js
+  //   - npx cache: ~/.npm/_npx/<hash>/node_modules/@smartmemory/compose/bin/compose.js
+  // git clone places it under any path WITHOUT a node_modules ancestor that
+  // contains the package itself, but WITH a .git directory at PACKAGE_ROOT.
+  if (PACKAGE_ROOT.includes(`${sep}node_modules${sep}`)) {
+    return { style: 'npm', root: PACKAGE_ROOT }
+  }
+  if (existsSync(join(PACKAGE_ROOT, '.git'))) {
+    return { style: 'git', root: PACKAGE_ROOT }
+  }
+  return { style: 'unknown', root: PACKAGE_ROOT }
+}
+
+function getPkgVersion() {
+  try {
+    return JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf-8')).version
+  } catch { return 'unknown' }
+}
+
+function getGitSha(repoPath) {
+  const r = spawnSync('git', ['-C', repoPath, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf-8' })
+  return r.status === 0 ? r.stdout.trim() : null
+}
+
+async function runUpdate(flags) {
+  const force = flags.includes('--force')
+  const cwd = process.cwd()
+  const { style, root } = detectInstallStyle()
+
+  console.log(`compose update — install style: ${style}`)
+  console.log(`  root: ${root}`)
+  console.log(`  current: v${getPkgVersion()}${style === 'git' ? ` @ ${getGitSha(root) || '?'}` : ''}`)
+  console.log('')
+
+  if (style === 'unknown') {
+    console.error('Cannot determine install style. Expected either:')
+    console.error(`  - npm install: PACKAGE_ROOT inside node_modules`)
+    console.error(`  - git clone:   .git directory at ${root}`)
+    console.error('Reinstall with: npm install -g @smartmemory/compose')
+    process.exit(1)
+  }
+
+  if (style === 'npm') {
+    // Decide global vs local: global if root is under a global prefix.
+    const npmPrefix = spawnSync('npm', ['prefix', '-g'], { encoding: 'utf-8' }).stdout.trim()
+    const isGlobal = npmPrefix && root.startsWith(npmPrefix)
+    const installCmd = isGlobal
+      ? ['install', '-g', '@smartmemory/compose@latest']
+      : ['install', '@smartmemory/compose@latest']
+    console.log(`Running: npm ${installCmd.join(' ')}`)
+    const r = spawnSync('npm', installCmd, { stdio: 'inherit' })
+    if (r.status !== 0) {
+      console.error('npm install failed')
+      process.exit(r.status || 1)
+    }
+  } else {
+    // git clone — check clean, fast-forward pull, npm install
+    const status = spawnSync('git', ['-C', root, 'status', '--porcelain'], { encoding: 'utf-8' })
+    if (status.stdout.trim() && !force) {
+      console.error(`Working tree at ${root} has uncommitted changes.`)
+      console.error('Commit/stash them, or re-run with --force to skip the check.')
+      process.exit(1)
+    }
+    const beforeSha = getGitSha(root)
+    console.log(`Running: git fetch && git pull --ff-only`)
+    const fetch = spawnSync('git', ['-C', root, 'fetch'], { stdio: 'inherit' })
+    if (fetch.status !== 0) { process.exit(fetch.status || 1) }
+    const pull = spawnSync('git', ['-C', root, 'pull', '--ff-only'], { stdio: 'inherit' })
+    if (pull.status !== 0) {
+      console.error('git pull --ff-only failed (likely diverged from remote).')
+      console.error(`Reconcile manually in ${root}, then re-run compose update.`)
+      process.exit(pull.status || 1)
+    }
+    const afterSha = getGitSha(root)
+    if (beforeSha === afterSha) {
+      console.log(`Already up to date at ${afterSha}.`)
+    } else {
+      console.log(`Updated ${beforeSha} → ${afterSha}`)
+    }
+
+    console.log('Running: npm install')
+    const ni = spawnSync('npm', ['install'], { cwd: root, stdio: 'inherit' })
+    if (ni.status !== 0) { process.exit(ni.status || 1) }
+  }
+
+  // Refresh global skill + stratum-mcp registration
+  console.log('')
+  console.log('Refreshing global skill installation...')
+  runSetup()
+
+  // If invoked from inside a Compose project, refresh project artifacts too
+  if (existsSync(join(cwd, '.compose', 'compose.json'))) {
+    console.log('')
+    console.log(`Refreshing project at ${cwd}...`)
+    await runInit([])
+  }
+
+  console.log('')
+  console.log(`compose updated to v${getPkgVersion()}${style === 'git' ? ` @ ${getGitSha(root) || '?'}` : ''}`)
+}
+
 // ---------------------------------------------------------------------------
 // Command dispatch
 // ---------------------------------------------------------------------------
@@ -449,7 +606,12 @@ if (cmd === 'setup') {
 }
 
 if (cmd === 'doctor') {
-  runDoctor(args)
+  await runDoctor(args)
+  process.exit(0)
+}
+
+if (cmd === 'update' || cmd === 'upgrade') {
+  await runUpdate(args)
   process.exit(0)
 }
 
@@ -1180,92 +1342,129 @@ if (cmd === 'hooks') {
   const hooksDir = pjoin(gitDir, 'hooks')
   const { mkdirSync: mSync } = await import('fs')
   mSync(hooksDir, { recursive: true })
-  const hookPath = pjoin(hooksDir, 'post-commit')
-
-  // Marker line used to identify our hooks
-  const HOOK_MARKER = '# Compose post-commit hook —'
 
   // Resolve absolute paths for substitution
   const composeBin = presolve(presolve(futp(import.meta.url), '..'), 'compose.js')
   const composeNode = process.execPath
 
-  if (sub === 'install') {
-    // Read template
-    const templatePath = pjoin(presolve(futp(import.meta.url), '..'), 'git-hooks', 'post-commit.template')
+  // Hook-type table. Each entry knows its template, marker, and destination.
+  const HOOK_TYPES = {
+    'post-commit': {
+      template: pjoin(presolve(futp(import.meta.url), '..'), 'git-hooks', 'post-commit.template'),
+      marker:   '# Compose post-commit hook —',
+      dest:     pjoin(hooksDir, 'post-commit'),
+    },
+    'pre-push': {
+      template: pjoin(presolve(futp(import.meta.url), '..'), 'git-hooks', 'pre-push.template'),
+      marker:   '# Compose pre-push hook —',
+      dest:     pjoin(hooksDir, 'pre-push'),
+    },
+  }
+
+  // Determine which hook types this invocation operates on.
+  // Flags: --pre-push, --post-commit, or none (default = post-commit, back-compat).
+  const selectedTypes = []
+  if (hookFlags['pre-push']) selectedTypes.push('pre-push')
+  if (hookFlags['post-commit']) selectedTypes.push('post-commit')
+  if (selectedTypes.length === 0) selectedTypes.push('post-commit') // default = back-compat
+
+  function installOne(type) {
+    const { template: tplPath, marker, dest } = HOOK_TYPES[type]
     let template
     try {
-      template = rfSync(templatePath, 'utf-8')
+      template = rfSync(tplPath, 'utf-8')
     } catch (err) {
-      console.error(`Error: could not read hook template: ${err.message}`)
-      process.exit(1)
+      console.error(`Error: could not read ${type} template: ${err.message}`)
+      return 1
     }
-
-    // Check existing hook
-    if (exSync(hookPath)) {
-      const existing = rfSync(hookPath, 'utf-8')
-      const isOurs = existing.includes(HOOK_MARKER)
+    if (exSync(dest)) {
+      const existing = rfSync(dest, 'utf-8')
+      const isOurs = existing.includes(marker)
       if (!isOurs && !hookFlags.force) {
-        console.error('Error: a foreign post-commit hook already exists at ' + hookPath)
+        console.error(`Error: a foreign ${type} hook already exists at ${dest}`)
         console.error('')
-        console.error('To chain our hook after yours, add this to your existing hook:')
-        console.error('')
-        console.error(`  "${composeNode}" "${composeBin}" record-completion ...`)
-        console.error('')
-        console.error('Or run `compose hooks install --force` to overwrite.')
-        process.exit(1)
+        console.error(`Run \`compose hooks install --${type} --force\` to overwrite.`)
+        return 1
       }
     }
-
-    // Substitute placeholders
     const substituted = template
       .replace(/__COMPOSE_NODE__/g, composeNode)
       .replace(/__COMPOSE_BIN__/g, composeBin)
-
-    wfSync(hookPath, substituted)
-    chmodSync(hookPath, 0o755)
-    console.log(`Installed post-commit hook at ${hookPath}`)
+    wfSync(dest, substituted)
+    chmodSync(dest, 0o755)
+    console.log(`Installed ${type} hook at ${dest}`)
     console.log(`  COMPOSE_NODE=${composeNode}`)
     console.log(`  COMPOSE_BIN=${composeBin}`)
-    process.exit(0)
+    return 0
   }
 
-  if (sub === 'uninstall') {
-    if (!exSync(hookPath)) {
-      console.log('No post-commit hook installed.')
-      process.exit(0)
+  function uninstallOne(type) {
+    const { marker, dest } = HOOK_TYPES[type]
+    if (!exSync(dest)) {
+      console.log(`No ${type} hook installed.`)
+      return 0
     }
-    const content = rfSync(hookPath, 'utf-8')
-    if (!content.includes(HOOK_MARKER)) {
-      console.warn('Warning: post-commit hook exists but does not appear to be a Compose hook (marker not found). Leaving alone.')
-      process.exit(0)
+    const content = rfSync(dest, 'utf-8')
+    if (!content.includes(marker)) {
+      console.warn(`Warning: ${type} hook exists but does not appear to be a Compose hook (marker not found). Leaving alone.`)
+      return 0
     }
-    const { rmSync: rmS } = await import('fs')
-    rmS(hookPath)
-    console.log(`Removed post-commit hook at ${hookPath}`)
-    process.exit(0)
+    const { rmSync: rmS } = require('fs')
+    rmS(dest)
+    console.log(`Removed ${type} hook at ${dest}`)
+    return 0
   }
 
-  // status (default)
-  if (!sub || sub === 'status') {
-    if (!exSync(hookPath)) {
-      console.log('absent — no post-commit hook installed')
-      process.exit(0)
+  function statusOne(type) {
+    const { marker, dest } = HOOK_TYPES[type]
+    if (!exSync(dest)) {
+      console.log(`${type}: absent — no hook installed`)
+      return
     }
-    const content = rfSync(hookPath, 'utf-8')
-    if (!content.includes(HOOK_MARKER)) {
-      console.log('foreign — post-commit hook exists but is not a Compose hook')
-      process.exit(0)
+    const content = rfSync(dest, 'utf-8')
+    if (!content.includes(marker)) {
+      console.log(`${type}: foreign — hook exists but is not a Compose hook`)
+      return
     }
-    // Check if paths match current
-    const nodeMatch   = content.includes(`COMPOSE_NODE="${composeNode}"`)
-    const binMatch    = content.includes(`COMPOSE_BIN="${composeBin}"`)
+    const nodeMatch = content.includes(`COMPOSE_NODE="${composeNode}"`)
+    const binMatch  = content.includes(`COMPOSE_BIN="${composeBin}"`)
     if (nodeMatch && binMatch) {
-      console.log('installed (current)')
+      console.log(`${type}: installed (current)`)
     } else {
-      console.log('installed (stale paths — re-run install)')
+      console.log(`${type}: installed (stale paths — re-run install)`)
       if (!nodeMatch) console.log(`  expected COMPOSE_NODE="${composeNode}"`)
       if (!binMatch)  console.log(`  expected COMPOSE_BIN="${composeBin}"`)
     }
+  }
+
+  if (sub === 'install') {
+    let exitCode = 0
+    for (const t of selectedTypes) exitCode = installOne(t) || exitCode
+    process.exit(exitCode)
+  }
+
+  if (sub === 'uninstall') {
+    const { rmSync: _rmS } = await import('fs') // ensure fs.rmSync is available
+    // uninstallOne calls require('fs') but we're ESM — replace with import-based deletion
+    for (const t of selectedTypes) {
+      const { marker, dest } = HOOK_TYPES[t]
+      if (!exSync(dest)) { console.log(`No ${t} hook installed.`); continue }
+      const content = rfSync(dest, 'utf-8')
+      if (!content.includes(marker)) {
+        console.warn(`Warning: ${t} hook exists but does not appear to be a Compose hook (marker not found). Leaving alone.`)
+        continue
+      }
+      _rmS(dest)
+      console.log(`Removed ${t} hook at ${dest}`)
+    }
+    process.exit(0)
+  }
+
+  // status (default)
+  if (!sub || sub === 'status') {
+    // Status reports on ALL known hook types (selection flags ignored), so users
+    // see the full picture. Selection only affects install/uninstall.
+    for (const t of Object.keys(HOOK_TYPES)) statusOne(t)
     process.exit(0)
   }
 
@@ -1273,6 +1472,100 @@ if (cmd === 'hooks') {
   process.exit(1)
 }
 
+if (cmd === 'validate') {
+  // compose validate [--scope=feature|project] [--code=CODE] [--block-on=error|warning|info] [--json]
+  let scope = 'project'
+  let code = null
+  let blockOn = 'error'
+  let asJson = false
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--help' || a === '-h') {
+      console.log(`Usage: compose validate [options]
+
+Options:
+  --scope=feature|project     Scope (default: project)
+  --code=CODE                 Feature code (required when scope=feature)
+  --block-on=LEVEL            Exit non-zero if any finding >= LEVEL (default: error)
+                              LEVEL: error | warning | info
+  --json                      Emit findings as JSON (default: human-readable)
+
+Exit codes:
+  0   no findings >= block-on threshold
+  1   findings >= block-on threshold present
+  2   usage error`)
+      process.exit(0)
+    }
+    if (a === '--json') { asJson = true; continue }
+    if (a.startsWith('--scope=')) scope = a.slice('--scope='.length)
+    else if (a === '--scope') scope = args[++i]
+    else if (a.startsWith('--code=')) code = a.slice('--code='.length)
+    else if (a === '--code') code = args[++i]
+    else if (a.startsWith('--block-on=')) blockOn = a.slice('--block-on='.length)
+    else if (a === '--block-on') blockOn = args[++i]
+    else if (a.startsWith('--')) {
+      console.error(`Unknown flag: ${a}`)
+      process.exit(2)
+    }
+  }
+  if (!['feature', 'project'].includes(scope)) {
+    console.error(`Invalid --scope=${scope}; expected feature or project`)
+    process.exit(2)
+  }
+  if (scope === 'feature' && !code) {
+    console.error(`--scope=feature requires --code=<CODE>`)
+    process.exit(2)
+  }
+  if (!['error', 'warning', 'info'].includes(blockOn)) {
+    console.error(`Invalid --block-on=${blockOn}; expected error, warning, or info`)
+    process.exit(2)
+  }
+
+  const { validateFeature, validateProject } = await import('../lib/feature-validator.js')
+  let result
+  try {
+    result = scope === 'feature'
+      ? await validateFeature(process.cwd(), code)
+      : await validateProject(process.cwd())
+  } catch (err) {
+    if (err.code === 'INVALID_INPUT') {
+      console.error(`Error [INVALID_INPUT]: ${err.message}`)
+      process.exit(2)
+    }
+    console.error(`Error: ${err.message}`)
+    process.exit(2)
+  }
+
+  // Threshold: findings at or above this severity block the exit code
+  const SEV_RANK = { error: 3, warning: 2, info: 1 }
+  const threshold = SEV_RANK[blockOn]
+  const blocking = result.findings.filter((f) => SEV_RANK[f.severity] >= threshold)
+
+  if (asJson) {
+    console.log(JSON.stringify(result, null, 2))
+  } else {
+    const byKind = {}
+    for (const f of result.findings) {
+      const sev = f.severity.toUpperCase()
+      const tag = `[${sev}] ${f.kind}${f.feature_code ? ' ' + f.feature_code : ''}`
+      if (!byKind[tag]) byKind[tag] = []
+      byKind[tag].push(f.detail)
+    }
+    if (result.findings.length === 0) {
+      console.log(`compose validate: no findings (scope=${scope}${code ? ' code=' + code : ''})`)
+    } else {
+      console.log(`compose validate findings (scope=${scope}${code ? ' code=' + code : ''}):`)
+      for (const tag of Object.keys(byKind).sort()) {
+        console.log(`  ${tag}`)
+        for (const detail of byKind[tag]) console.log(`    - ${detail}`)
+      }
+      console.log(`\n${result.findings.length} finding(s); ${blocking.length} at or above --block-on=${blockOn}`)
+    }
+  }
+
+  process.exit(blocking.length > 0 ? 1 : 0)
+}
+
 if (cmd === 'pipeline') {
   const { runPipelineCli } = await import('../lib/pipeline-cli.js')
   try {

package/bin/git-hooks/pre-push.template

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Compose pre-push hook — runs `compose validate` and blocks the push on
+# any error-severity drift finding. Installed by `compose hooks install --pre-push`;
+# placeholders below are substituted at install time.
+
+set -u
+COMPOSE_NODE="__COMPOSE_NODE__"
+COMPOSE_BIN="__COMPOSE_BIN__"
+LOG="${COMPOSE_HOOK_LOG:-.compose/data/pre-push.log}"
+mkdir -p "$(dirname "$LOG")" 2>/dev/null || true
+
+OUTPUT=$("$COMPOSE_NODE" "$COMPOSE_BIN" validate --scope=project --block-on=error 2>&1)
+EXIT_CODE=$?
+
+if [ "$EXIT_CODE" -ne 0 ]; then
+  echo "$OUTPUT" | tee -a "$LOG" >&2
+  echo "" >&2
+  echo "compose validate found error-severity drift. Push aborted." >&2
+  echo "Run \`compose validate\` to see findings, then fix and retry." >&2
+  echo "Bypass at your own risk: git push --no-verify" >&2
+  exit "$EXIT_CODE"
+fi
+
+# Below-threshold findings (warnings/info) are still printed for visibility.
+echo "$OUTPUT"
+exit 0