@skitterbyte/skitterspec 20.0.0 → 22.0.0

package/src/env/serve.js

@@ -37,6 +37,8 @@ const {
   resolveBaseBranch,
 } = require('./resolve.js')
 const { loadEnvConfig } = require('./config.js')
+const { specDocsIn } = require('./classify.js')
+const { liveStateFor } = require('./live.js')
 const {
   rawGitReader,
   collectReview,
@@ -45,6 +47,7 @@ const {
   reviewOutPath,
   validateNotesBlob,
   readPending,
+  passState: readPassState,
   writePending,
   addPending,
   readNotes,
@@ -84,6 +87,15 @@ function routeFor(url, { token = null } = {}) {
   if (segments.length === 0) return { kind: 'index' }
   if (segments.length > 1) return { kind: 'notfound' }
 
+  // `?pass=<code>` asks what became of ONE pass, and it is checked BEFORE
+  // `?branch` because it is not a view of the diff at all — it is the page
+  // finding out whether the verdict it sent was picked up. Deliberately only
+  // ever one code wide: a route that listed what is waiting would hand a
+  // prober exactly what the six digits are bought to withhold, and the POST
+  // route was kept from being that oracle for the same reason.
+  const pass = query.get('pass')
+  if (pass !== null) return { kind: 'pass', spec: segments[0], code: pass }
+
   // `?branch` and `?branch=1` both mean the whole-spec view; `?branch=0` does
   // not, so a link can turn it off as well as on.
   const raw = query.get('branch')
@@ -167,19 +179,134 @@ ${body}
 }
 
 /**
- * Resolve the specs worth listing: every spec with a worktree of its own.
+ * WHICH VIEW A SPEC GETS, decided in one place so every route agrees.
+ *
+ * `worktree` — it has one, so the page is its branch's diff, exactly as before.
+ * `docs` — it has none, so the page is its own uncommitted documents read from
+ *   the checkout this server is anchored to. That is the authoring page
+ *   `spec-env review --docs` writes, and this is what lets it be SERVED: a
+ *   `file://` page has no server to POST to, so without this the authoring page
+ *   exists and its verdict buttons have nowhere to go.
+ * `null` — neither: no worktree and nothing uncommitted of its own, which is
+ *   the ordinary state of most of `specs/` and a 404 rather than an error.
+ *
+ * WHAT WOULD FOOL A WORKTREE-ONLY VERSION of this — which is what shipped, and
+ * what 404'd a page rendered minutes earlier: an authoring page belongs to a
+ * spec with no worktree BY DEFINITION, so gating the route on a worktree
+ * excludes precisely the specs the docs view exists for.
+ */
+function viewFor(dir, config, spec, git, { fallback = false } = {}) {
+  if (!spec) return null
+  // LIVE COMES FIRST, because while a spec is live its worktree still exists —
+  // detached — and would win the check below while holding none of the work.
+  // `live take` checks the branch out HERE, and a fix made while live is made
+  // here too, so this checkout is the tree that answers.
+  if (spec.branch && headBranchOf(git) === spec.branch) return { kind: 'live', tree: dir }
+  const wt = spec.worktreePath
+  if (wt && wt !== dir && fs.existsSync(wt)) return { kind: 'worktree', tree: wt }
+  const found = specDocsIn(dir, spec, config, trimmedGitReader(dir))
+  // `error` is cannot-tell — not a page, and not an error page either (rule 4:
+  // the harmless branch).
+  if (found.error) return null
+  if (!found.empty) return { kind: 'docs', tree: found.tree, owned: found.owned }
+
+  // NOTHING UNCOMMITTED IS NOT NOTHING TO SHOW, on this route. A `--docs` page
+  // renders a spec's uncommitted documents, so HONOURING THE VERDICT PRESSED ON
+  // IT is what removes them: the reader presses `Commit`, the agent commits, and
+  // a reload 404s. The link was valid, the server was up and the network was
+  // fine — the page had been deliberately destroyed by the thing it asked for.
+  //
+  // So fall back to what the spec now IS, which mirrors the phase page's
+  // clean-tree fallback for the same reason: the page is rendered before the
+  // commit and read after it.
+  //
+  // ONLY FOR A NAMED PAGE, never for the index. The two routes ask different
+  // questions: the index is a menu of what AWAITS review, and every completed
+  // spec in the repo falling back would fill it with dozens of finished ones —
+  // the doorway would be wrong about a healthy repo, which is the reason it
+  // omits them in the first place. A direct request is someone opening an
+  // address they were given, and that has to keep resolving.
+  if (!fallback) return null
+  const committed = committedDocsFor(dir, config, spec)
+  if (!committed) return null
+  return { kind: 'docs-committed', tree: dir, owned: committed }
+}
+
+/**
+ * The spec's committed document paths at `HEAD`, or null when it has none.
  *
- * A spec with no worktree is OMITTED, not listed as an error. An unstarted spec
- * has nothing to diff, which is the ordinary state of most of `specs/` — and a
- * doorway that lists them as failures would be wrong about a healthy repo.
+ * KEPT ONLY WHERE IT FINDS SOMETHING, exactly as the branch fallback is: a name
+ * that is no spec at all must stay a 404 rather than render an empty page with
+ * a commit button on it.
+ */
+function committedDocsFor(dir, config, spec) {
+  const git = trimmedGitReader(dir)
+  const out = git(['ls-files', '--', `specs/*/${spec.folder}/*`])
+  if (out == null) return null
+  const paths = String(out)
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean)
+  return paths.length ? paths : null
+}
+
+/**
+ * The tier rows the PAGE needs, from config alone.
+ *
+ * DELIBERATELY NOT `reviewTierStack`. That stack answers "where can this be
+ * read", which needs the server's bind, the machine's addresses and any
+ * published URL. The page needs only the half it can act on: which tiers are
+ * OFF, so it can offer the press that turns one on. An `off` tier has no URL by
+ * definition, so none of that machinery is required — and an `on` tier
+ * contributes nothing here, because the reader is standing on one of them.
+ */
+function pageTiers(config) {
+  const r = (config && config.review) || {}
+  return [
+    { tier: 'network', off: !r.allowNetwork },
+    { tier: 'remote', off: !r.allowRemote },
+  ]
+}
+
+/**
+ * The branch name a git reader's checkout is on, or null.
+ *
+ * NULL FOR A DETACHED HEAD, which `rev-parse --abbrev-ref` spells `HEAD` — a
+ * name no branch has, and one that must never compare equal to a spec's.
+ * Returning it verbatim would make a detached checkout look like a spec called
+ * `HEAD`; the cannot-tell answer is null (`.claude/rules/negative-checks.md`).
+ */
+function headBranchOf(git) {
+  const out = git ? git(['rev-parse', '--abbrev-ref', 'HEAD']) : null
+  if (out == null) return null
+  const name = String(out).trim()
+  return name && name !== 'HEAD' ? name : null
+}
+
+// `specDocsIn` wants a reader that TRIMS, because it compares whole paths.
+function trimmedGitReader(treePath) {
+  const git = rawGitReader(treePath)
+  return (argv) => {
+    const out = git(argv)
+    return out == null ? null : String(out).trim()
+  }
+}
+
+/**
+ * Resolve the specs worth listing: every spec this server can render a page for.
+ *
+ * A spec with neither a worktree nor uncommitted documents of its own is
+ * OMITTED, not listed as an error — that is the ordinary state of most of
+ * `specs/`, and a doorway listing them as failures would be wrong about a
+ * healthy repo.
+ *
+ * IT INCLUDES WORKTREE-LESS SPECS NOW, and both halves are needed together: a
+ * page that serves but is absent from the index is a page nobody finds.
  */
 function servableSpecs(dir, config, git) {
   const worktreePaths = liveWorktreePaths(git)
   return allSpecs(dir, config, worktreePaths)
-    .filter((s) => {
-      const wt = s.worktreePath
-      return wt && wt !== dir && worktreePaths.has(path.resolve(wt))
-    })
+    .filter((s) => Boolean(viewFor(dir, config, s, git)))
     .sort((a, b) => a.folder.localeCompare(b.folder))
 }
 
@@ -207,7 +334,15 @@ function servableSpecs(dir, config, git) {
  * which is the harmless direction.
  */
 function receivePass(dir, config, spec, blob) {
-  if (!spec || !fs.existsSync(spec.worktreePath)) return null
+  // A VIEW, NOT A WORKTREE. The pending store lives in the checkout this server
+  // is anchored to, so accepting a pass needs no worktree — and requiring one
+  // rejected every verdict sent from an authoring page, which is the one page
+  // whose spec never has a worktree.
+  // `fallback: true` so the POST follows the PAGE. A reader who reloads a
+  // committed docs page gets buttons; rejecting what they press would be the
+  // failure this whole area keeps producing — a control that appears to do
+  // nothing. Whether the verdict is worth acting on is the routing's call.
+  if (!spec || !viewFor(dir, config, spec, rawGitReader(dir), { fallback: true })) return null
   let parsed
   try {
     parsed = validateNotesBlob(blob, spec.folder)
@@ -234,9 +369,43 @@ function receivePass(dir, config, spec, blob) {
 }
 
 function renderSpecPage(dir, config, spec, { branch = false } = {}) {
-  if (!spec || !fs.existsSync(spec.worktreePath)) return null
+  const view = viewFor(dir, config, spec, rawGitReader(dir), { fallback: true })
+  if (!view) return null
+
+  // THE DOCS VIEW IS A DIFFERENT TREE AND A DIFFERENT FILE SET, and it takes
+  // the authoring buttons: a spec with no worktree has no phase in flight, so
+  // "commit and build the next phase" is the wrong offer for it.
+  if (view.kind === 'docs' || view.kind === 'docs-committed') {
+    const docsGit = rawGitReader(view.tree)
+    const out = reviewOutPath(dir, spec.folder, null)
+    const notes = readNotes(out, spec.folder).notes
+    const gateRead = readGate(out, spec.folder)
+    const data = collectReview({
+      spec,
+      git: docsGit,
+      mode: view.kind,
+      // A committed view diffs against the commit BEFORE HEAD's spec content —
+      // there is nothing uncommitted to compare, so the whole document is the
+      // content, exactly as an untracked file renders.
+      ref: view.kind === 'docs-committed' ? 'HEAD~1' : 'HEAD',
+      now: new Date().toISOString(),
+      notes,
+      gate: gateRead.corrupt ? null : gateRead.gate,
+      buttons: 'authoring',
+      only: view.owned,
+      treePath: view.tree,
+    })
+    return {
+      html: renderReviewPage(data, { reviewHtml: renderReviewBlock(data.review) }),
+      totals: data.totals,
+      mode: data.mode,
+      fellBack: false,
+    }
+  }
 
-  const git = rawGitReader(spec.worktreePath)
+  // `view.tree` rather than `spec.worktreePath`: the two differ for a live
+  // spec, whose branch is checked out here instead.
+  const git = rawGitReader(view.tree || spec.worktreePath)
   const trimmed = (argv) => {
     const out = git(argv)
     return out == null ? null : String(out).trim() || null
@@ -270,7 +439,30 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
   // is a convenience and the gate is not what it is for.
   const gate = gateRead.corrupt ? null : gateRead.gate
 
-  let data = collectReview({ spec, git, mode, ref, base: baseName, now, notes, gate })
+  // WHERE ELSE THIS REVIEW LIVES, and whether it is also running — the block
+  // above the verdicts. Worktree views only: a `--docs` page returns above,
+  // because a spec with no branch has nothing to put live.
+  const live = liveStateFor(spec, {
+    isolated: true,
+    onBase: headBranchOf(rawGitReader(dir)) !== spec.branch,
+    primaryBranch: headBranchOf(rawGitReader(dir)),
+    receipt: null,
+    worktreeExists: Boolean(spec.worktreePath && fs.existsSync(spec.worktreePath)),
+  })
+  const tiers = pageTiers(config)
+
+  let data = collectReview({
+    spec,
+    git,
+    mode,
+    ref,
+    base: baseName,
+    now,
+    notes,
+    gate,
+    live,
+    tiers,
+  })
 
   if (!branch && data.totals.files === 0) {
     const fallbackBase = base()
@@ -285,6 +477,8 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
         now,
         notes,
         gate,
+        live,
+        tiers,
         fellBack: true,
       })
       if (wider.totals.files > 0) {
@@ -311,9 +505,51 @@ function renderSpecPage(dir, config, spec, { branch = false } = {}) {
  * same question in one call per spec; untracked files are counted separately
  * because `git diff` cannot see them.
  */
-function specSummary(spec) {
-  if (!spec || !fs.existsSync(spec.worktreePath)) return null
-  const git = rawGitReader(spec.worktreePath)
+/**
+ * Counts for a docs view: numstat over just this spec's owned paths.
+ *
+ * Untracked files are counted with `--no-index` against /dev/null, which is the
+ * only way git will diff a file it does not track — and a brand-new spec is
+ * entirely untracked, so without that half the index would show a spec with
+ * four documents as `0 files`.
+ */
+function docsSummary(view) {
+  const git = rawGitReader(view.tree)
+  const totals = { files: 0, additions: 0, deletions: 0 }
+  const add = (row) => {
+    const [a, d] = String(row).split('\t')
+    totals.files += 1
+    if (a === '-' || d === '-') return
+    totals.additions += Number(a) || 0
+    totals.deletions += Number(d) || 0
+  }
+  for (const rel of view.owned) {
+    const tracked = git(['diff', '--numstat', 'HEAD', '--', rel])
+    const rows = String(tracked || '').split('\n').filter(Boolean)
+    if (rows.length) {
+      rows.forEach(add)
+      continue
+    }
+    const untracked = git(['diff', '--no-index', '--numstat', '--', '/dev/null', rel])
+    String(untracked || '')
+      .split('\n')
+      .filter(Boolean)
+      .forEach(add)
+  }
+  return totals
+}
+
+function specSummary(spec, dir = null, config = null) {
+  // The index counts whatever the page would show, so it takes the same view.
+  // `dir`/`config` are optional so an existing caller counting a worktree spec
+  // is unchanged; without them only the worktree view can be counted.
+  const view = dir ? viewFor(dir, config, spec, rawGitReader(dir)) : null
+  if (view && view.kind === 'docs') return docsSummary(view)
+  // The tree the page would read, which for a live spec is this checkout. The
+  // worktree fallback keeps the callers that pass no `dir` working unchanged.
+  const tree = view && view.tree ? view.tree : spec && spec.worktreePath
+  if (!tree || !fs.existsSync(tree)) return null
+  const git = rawGitReader(tree)
 
   const totals = { files: 0, additions: 0, deletions: 0 }
   const add = (row) => {
@@ -388,7 +624,7 @@ function readBody(req, limit = MAX_PASS_BYTES) {
   })
 }
 
-function createReviewServer({ resolveEntries, render, receive = null, token = null }) {
+function createReviewServer({ resolveEntries, render, receive = null, passState = null, token = null }) {
   return http.createServer((req, res) => {
     const send = (code, body, type = 'text/html; charset=utf-8') => {
       res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store' })
@@ -425,6 +661,22 @@ function createReviewServer({ resolveEntries, render, receive = null, token = nu
       return
     }
 
+    // THE READ THAT IS NOT A RENDER. It answers three words and never a diff,
+    // so a page polling it costs the server a file read rather than a patch.
+    //
+    // A SERVER BUILT WITHOUT THE LOOKUP SAYS SO, rather than 404ing or falling
+    // through to the diff page. An older daemon still running beside a newer
+    // page is the ordinary way here, and both of those answers would be read as
+    // something they are not — a 404 as "that pass does not exist", HTML as a
+    // parse failure. `unknown` is the one answer that keeps the command on the
+    // reader's screen, which is where it belongs when nothing can be
+    // established.
+    if (route.kind === 'pass') {
+      const out = passState ? passState(route.spec, route.code) : null
+      const state = out && typeof out.state === 'string' ? out.state : 'unknown'
+      return send(200, JSON.stringify({ state }), 'application/json; charset=utf-8')
+    }
+
     try {
       if (route.kind === 'index') return send(200, renderIndex(resolveEntries(), { token }))
       const out = render(route.spec, { branch: route.branch })
@@ -496,10 +748,26 @@ function engineVersionFor(scriptPath) {
  * (a bundled build, an odd install layout). Both are answered `unknown`, and
  * neither is evidence of anything.
  */
-function staleServer(recorded, running) {
+function staleServer(recorded, running, recordedMtime, runningMtime) {
   if (typeof recorded !== 'string' || !recorded) return 'unknown'
   if (typeof running !== 'string' || !running) return 'unknown'
-  return recorded === running ? 'current' : 'stale'
+  if (recorded !== running) return 'stale'
+
+  // SAME VERSION IS NOT SAME CODE, which is the whole of this addition. The
+  // daemon runs a built copy of the engine — in this repo a symlink to the
+  // gitignored dist — so a rebuild moves the file without moving the version,
+  // and a version-only comparison adopted a process running last week's code.
+  // It cost two confidently wrong diagnoses in one session: a page reported as
+  // 404ing that the new code serves, and a regression reported as unfixed that
+  // had already been fixed.
+  //
+  // CANNOT TELL ADOPTS. A settings file written before this existed records no
+  // mtime, and an unreadable script has none to offer — restarting a healthy
+  // server over an absent field is the destructive reading, so an absent half
+  // falls back to the version verdict (rule 4).
+  const both = Number.isFinite(recordedMtime) && Number.isFinite(runningMtime)
+  if (both && recordedMtime !== runningMtime) return 'stale'
+  return 'current'
 }
 
 module.exports = {
@@ -509,6 +777,9 @@ module.exports = {
   engineVersionFor,
   staleServer,
   specSummary,
+  viewFor,
+  headBranchOf,
+  pageTiers,
   routeFor,
   renderIndex,
   servableSpecs,
@@ -550,7 +821,7 @@ if (require.main === module) {
       return {
         folder: s.folder,
         branch: one ? one.branch : '',
-        totals: specSummary(one),
+        totals: specSummary(one, dir, config),
       }
     })
 
@@ -558,6 +829,14 @@ if (require.main === module) {
     resolveEntries,
     render: (folder, opts) => renderSpecPage(dir, config, resolveOne(folder), opts),
     receive: (folder, blob) => receivePass(dir, config, resolveOne(folder), blob),
+    // A spec this daemon cannot resolve is not a pass that was claimed — it is
+    // a lookup that could not see, so it says nothing rather than reporting the
+    // comfortable answer. Same rule the engine's own three states follow.
+    passState: (folder, code) => {
+      const one = resolveOne(folder)
+      if (!one) return { state: 'unknown' }
+      return readPassState(reviewOutPath(dir, one.folder, null), one.folder, code)
+    },
     token,
   })
   startReviewServer(server, { port, host }).then(

package/src/env/supervise.js

@@ -147,4 +147,11 @@ async function waitHealthy(
   return false
 }
 
-module.exports = { startProcess, stopProcess, waitHealthy, isAlive, readPid }
+// `signalGroup` is exported for TESTS that need to simulate a process dying.
+// Killing the recorded pid alone is not that simulation: the pid is the detached
+// `sh -c` leader, and where the shell forks rather than execs, the real server
+// is its child and survives. A test that reaches for `process.kill(pid, …)`
+// therefore kills the wrapper, leaves the server holding its port, and then
+// blames whatever it asserts next. Killing the group is what `stopProcess` does
+// and what a test must do to mean "it died".
+module.exports = { startProcess, stopProcess, waitHealthy, isAlive, readPid, signalGroup }

package/src/init.js

@@ -39,14 +39,23 @@ function listCommands() {
   }
 }
 
-// Hook scripts shipped as `assets/hooks/*.js`, installed to `.claude/hooks/`.
-// Discovered from the bundled tree like everything else, so a distribution
-// installs precisely what it ships and a hook can be retired by deleting it.
+// Hook scripts shipped as `assets/hooks/*.cjs` (or `*.mjs`), installed to
+// `.claude/hooks/`. Discovered from the bundled tree like everything else, so a
+// distribution installs precisely what it ships and a hook can be retired by
+// deleting it.
+//
+// A BARE `.js` IS DELIBERATELY NOT DISCOVERED. These files are copied into the
+// TARGET project, where that project's `package.json` — the one file skitterspec
+// does not control — decides how node parses a `.js`. Shipping CommonJS as `.js`
+// crashed the review-gate hook in every `"type": "module"` project, on every
+// Bash tool call. The extension is the only thing that settles it at the file,
+// so both accepted forms pin it; `env-review-hook.test.js` asserts the rule over
+// the whole directory rather than over this filter.
 function listHooks() {
   try {
     return fs
       .readdirSync(path.join(ASSETS, 'hooks'))
-      .filter((f) => f.endsWith('.js'))
+      .filter((f) => f.endsWith('.cjs') || f.endsWith('.mjs'))
       .sort()
   } catch {
     return [] // a distribution may ship no hooks
@@ -170,7 +179,7 @@ function assertComposedAssets() {
 const SPEC_MARKER_START = '<!-- skitterspec:start -->'
 const SPEC_MARKER_END = '<!-- skitterspec:end -->'
 
-const report = { created: [], updated: [], skipped: [], refused: [], removed: [], customized: [], healed: [], warnings: [] }
+const report = { created: [], updated: [], skipped: [], refused: [], removed: [], customized: [], adopted: [], healed: [], warnings: [] }
 
 function resetReport() {
   for (const k of Object.keys(report)) report[k].length = 0
@@ -232,16 +241,31 @@ function managedTargets(dir) {
 }
 
 // Read the manifest (tolerant: missing/malformed → an empty baseline).
+// `baselined` answers a question `files` cannot: could this manifest have SEEN
+// a path? It is true only when the file parsed into the expected shape AND
+// records at least one entry — a POSITIVE signal, not an absence, which is what
+// lets `managedState` read a path's absence from it as evidence of anything
+// (`.claude/rules/negative-checks.md` rule 1).
+//
+// WHAT WOULD FOOL IT: nothing silently. A missing manifest and a malformed one
+// both fall into the same empty baseline below — correct for reading hashes,
+// and useless for reasoning about absence, since on a repo with no manifest yet
+// EVERY path is absent. Both answer `baselined: false`, so the one conclusion
+// that depends on it is simply not drawn.
 function readManifest(dir) {
   try {
     const parsed = JSON.parse(fs.readFileSync(path.join(dir, MANIFEST_FILE), 'utf8'))
     if (parsed && typeof parsed === 'object' && parsed.files && typeof parsed.files === 'object') {
-      return { version: parsed.version || MANIFEST_VERSION, files: parsed.files }
+      return {
+        version: parsed.version || MANIFEST_VERSION,
+        files: parsed.files,
+        baselined: Object.keys(parsed.files).length > 0,
+      }
     }
   } catch {
     /* missing or malformed → empty baseline */
   }
-  return { version: MANIFEST_VERSION, files: {} }
+  return { version: MANIFEST_VERSION, files: {}, baselined: false }
 }
 
 function writeManifest(dir, files) {
@@ -256,6 +280,29 @@ function writeManifest(dir, files) {
 //   missing    — not on disk
 //   pristine   — ours to update: it matches the package asset, or the hash we recorded
 //   customized — on disk but differs from both — a user edit; keep it
+//   adopted    — a path this version has NEWLY CLAIMED, where the project
+//                already had a file: it differs from what we ship, and the
+//                manifest that could have named it does not. Keep it too — the
+//                two states differ only in what the report CLAIMS about it.
+//
+// The split exists because `customized` made a false statement about the second
+// case. "Your edit — kept" describes our file at a path upstream had not
+// claimed, and the reader acts on it: v21 renamed the commit hook to
+// `review-gate.cjs`, which is the same name anyone would have picked to work
+// around v20's ESM crash — so their shim was kept, the real hook was never
+// installed, and `review-gate.js` was pruned out from under it. The shim fails
+// open, so the gate went silently absent under a report that said success.
+//
+// WHAT WOULD FOOL THIS, and why neither does:
+//   - A repo with no manifest (or an unreadable one) has EVERY path absent.
+//     `baselined` is the positive signal that gates the conclusion, so those
+//     fall back to `customized` — which keeps the file either way
+//     (`.claude/rules/negative-checks.md` rules 1 and 4).
+//   - The signal is ONE-SHOT. `flushManifest`'s migration seed gives any
+//     present managed file an entry on the very next run, so an adopted path
+//     reads `customized` from then on. Anyone who already upgraded has spent
+//     it — which is why the `.cjs` trap is also written into MIGRATION.md,
+//     where that reader is actually looking.
 //
 // `bundled` (the current package asset) is optional but decisive: a file whose
 // CONTENT equals what we ship is not customized, whatever the manifest says.
@@ -271,7 +318,8 @@ function managedState(dir, relPath, manifest, bundled) {
   const onDisk = fs.readFileSync(abs, 'utf8')
   if (bundled !== undefined && onDisk === bundled) return 'pristine'
   const known = manifest.files[relPath]
-  return known && sha1(onDisk) === known ? 'pristine' : 'customized'
+  if (known) return sha1(onDisk) === known ? 'pristine' : 'customized'
+  return manifest.baselined ? 'adopted' : 'customized'
 }
 
 // Reconcile and persist the manifest after an install/resync run: keep prior
@@ -412,6 +460,12 @@ function registerReviewGateHook(dir) {
     report.created.push(label)
   } else if (res.reason === 'added') {
     report.updated.push(label)
+  } else if (res.reason === 'migrated') {
+    // A WRITE, so it may not fall through to `skipped`. It was doing exactly
+    // that: rewriting the registered path and then reporting "already
+    // registered" — a run that acts and says it did not, which is the shape of
+    // the bug this whole change exists to fix.
+    report.updated.push('.claude/settings.json (review-gate hook repointed at the renamed script)')
   } else {
     report.skipped.push('.claude/settings.json (review-gate hook already registered)')
   }
@@ -612,6 +666,8 @@ function checkSync(dir, { claudeMd = true, log = console.log } = {}) {
     const state = managedState(dir, relPath, manifest, bundled)
     if (state === 'missing') rows.push([relPath, 'missing — would be created'])
     else if (state === 'customized') rows.push([relPath, 'your edit — kept (--force overwrites)'])
+    else if (state === 'adopted')
+      rows.push([relPath, 'adopted upstream — yours kept, theirs not installed (--force takes theirs)'])
     else if (fs.readFileSync(abs, 'utf8') !== bundled) rows.push([relPath, 'out of date — would be updated'])
   }
   const section = claudeMd ? claudeMdSectionState(dir) : 'fresh'
@@ -699,14 +755,16 @@ function resyncManagedFile(dir, target, manifest, force) {
     report[bucket].push(relPath)
   }
   if (state === 'missing') return write('created')
-  if (state === 'customized') {
+  // `adopted` writes exactly as `customized` does — keep unless forced. Only the
+  // bucket differs, because only the REPORT was ever wrong about it.
+  if (state === 'customized' || state === 'adopted') {
     if (force) return write('updated')
     writtenHashes[relPath] = manifest.files[relPath] || writtenHashes[relPath] // keep baseline
     // Carry the change the user just DECLINED. A bare filename tells them a
     // decision was made on their behalf but not what it was, which leaves
     // "clobber and re-apply my edits by hand" as the only safe way to upgrade.
     const { added, removed, hunks } = linesDiff(fs.readFileSync(abs, 'utf8'), bundled)
-    return report.customized.push({ relPath, added, removed, hunks })
+    return report[state].push({ relPath, added, removed, hunks })
   }
   // pristine — update only if the bundled content actually changed
   if (fs.readFileSync(abs, 'utf8') === bundled) {
@@ -728,6 +786,15 @@ function resync(dir, { force = false, claudeMd = true, diff = false } = {}) {
   installFolders(dir)
   removeRetiredFiles(dir)
   pruneRetiredManaged(dir, manifest)
+  // The hook SCRIPT arrives above, as one more managed target; registering it is
+  // a separate write to a file we do not manage, so it has to be asked for here.
+  // It is easy to read this as duplication of `installHooks()` and delete it —
+  // it is not. `installHooks()` is unreachable from this path, and the two
+  // halves being in different functions is exactly how they drifted apart once:
+  // `update` copied `.claude/hooks/` and registered nothing, for every upgrading
+  // project, while reporting a file created. `init-review-gate-hook.test.js`
+  // asserts over the entry points rather than over this call.
+  registerReviewGateHook(dir)
   if (claudeMd) installClaudeMd(dir, { mode: 'update' })
   flushManifest(dir)
   printReport(dir, 'resync', { diff })
@@ -812,6 +879,10 @@ function printReport(dir, mode, { diff = false } = {}) {
     'customized (kept)',
     report.customized.map((c) => `${c.relPath}  +${c.added} \u2212${c.removed}`),
   )
+  line(
+    'adopted upstream (kept — ours was never installed)',
+    report.adopted.map((c) => `${c.relPath}  +${c.added} \u2212${c.removed}`),
+  )
   line('manifest repaired', report.healed)
   line('unchanged', report.skipped)
   if (report.refused.length) {
@@ -827,13 +898,17 @@ function printReport(dir, mode, { diff = false } = {}) {
     process.stdout.write('\nwarnings:\n')
     for (const w of report.warnings) process.stdout.write(`  ! ${w}\n`)
   }
+  const declined = [
+    ...report.customized.map((c) => [c, 'kept — this is what you declined']),
+    ...report.adopted.map((c) => [c, 'kept — this is what was not installed']),
+  ]
   if (diff) {
-    for (const c of report.customized) {
+    for (const [c, why] of declined) {
       if (!c.hunks.length) continue
-      process.stdout.write(`\n--- ${c.relPath} (kept — this is what you declined)\n`)
+      process.stdout.write(`\n--- ${c.relPath} (${why})\n`)
       for (const h of c.hunks) process.stdout.write(`${h}\n`)
     }
-  } else if (report.customized.length) {
+  } else if (declined.length) {
     process.stdout.write('\nRe-run with --diff to see the changes those files declined.\n')
   }
   const isolationOn = fs.existsSync(path.join(dir, 'specs', '.core', 'env.config.json'))