tackbox 0.1.97 → 0.1.98

package/README.md

@@ -163,12 +163,12 @@ past (argparse misuse, and the per-command cases below).
   `--draft` is a generator, not a gate: `0` when every uncovered
   marker was drafted (an orphan-only tree included), `2` only when
   unresolvable files leave the draft incomplete.
-- **hook** - `0` a no-op, a clean event, or a JSON decision (a
-  PreToolUse approval prompt or a PostToolUse Bash block); `1` a
+- **hook** - `0` a no-op, a clean event, or a JSON pre decision (an
+  approval prompt or a refusal before an unrelated edit); `1` a
   non-blocking infra error (unreadable stdin, a git failure); `2` a
-  PostToolUse finding on the edited lines, a non-compiling Go
-  package, or an approvals inconsistency anywhere in the worktree,
-  which blocks the edit in-loop.
+  PostToolUse finding on edited lines, a non-compiling Go package, or
+  session approvals debt in a touched file. A post error reports a
+  mutation that already landed; it does not block or undo the write.
 - **hook-protocol** - `0` whenever a decision was reached, whatever the
   decision says (it rides the JSON on stdout, never the exit code); `1`
   plus one stderr line when none was: unreadable stdin, or a request
@@ -473,8 +473,8 @@ scopes (lambdas, arrows, IIFEs) appear as 8-hex content hashes; Java
 overloads carry a parameter-type signature; same-name siblings take
 an `@k` ordinal. Repeat the line for each identical occurrence.
 
-The check is bidirectional and always covers the whole tree: a
-marker without a covering entry and an entry without a live marker
+For `tackbox lint` and `tackbox approvals`, the bidirectional check covers the whole tree:
+a marker without a covering entry and an entry without a live marker
 (an orphan) are both findings, reported by `tackbox lint` under the
 `approvals (whole tree):` header whatever the lint scope.
 `tackbox approvals` runs the same check standalone;
@@ -488,11 +488,19 @@ Approving is adding the line. In an agent session the edit that adds
 a manifest line draws the PreToolUse ask quoting the entry (several
 lines in one edit draw one all-or-nothing ask), so the only route to
 a green check passes through a visible diff and a human decision.
-Writing a marker itself never asks - by any channel, Edit or shell -
-it merely leaves the tree inconsistent, which every later hook
-event, `dev.py check`, and CI reports until the entry lands or the
-marker is reverted. Removing a manifest line is free; a marker whose
-text, scope, or count changes needs its entry updated the same way.
+Writing a marker itself never asks - by any channel, Edit or shell.
+New session debt blocks the next edit outside the affected marker files
+and `.tackbox/approvals`; post-edit feedback reports debt only in touched
+files. Bash and eval run no approvals checks. `dev.py check` and CI still
+report all tree inconsistencies. Removing a manifest line is free; a
+marker whose text, scope, or count changes needs its entry updated.
+
+Approvals messages carry the suppressed rule's text, or say the marker
+suppresses nothing when no finding is available, such as in the standalone
+`approvals` command. Each inconsistency takes one line; no message supplies
+an approval entry to copy. Suppressed findings stay out of ordinary lint
+output, its exit status, and codequality. See D020 in
+[rules/DECISIONS.md](rules/DECISIONS.md) for the session boundary.
 
 ## Generated and vendored code
 
@@ -575,15 +583,18 @@ specified in [docs/report-contracts.md](docs/report-contracts.md).
 
 ## Agent hook
 
-The rules wire into a coding agent's edit loop through one shared core: the
-approval gates, the diff-scoped lint, and the whole-tree consistency check
-are the same whichever host drives them. In host-neutral terms:
-
-- **Post-edit** re-lints the touched files (Go: their package). A finding on
-  the lines the edit added blocks with the finding text. Every post event -
-  including an opaque channel - also runs the whole-tree approvals consistency
-  check: an unapproved marker, an orphaned entry, or an unresolvable file blocks
-  with the named fix. A verified violation is always a tool error. A post event
+The rules wire into a coding agent's edit loop through one shared core:
+approval gates, diff-scoped lint, and session approvals debt have the same
+semantics whichever host drives them. Session means the worktree difference
+from HEAD, including staged changes and untracked files; without a commit,
+the whole tree is added. Existing debt is left to `dev.py check` and CI.
+
+- **Post-edit** re-lints touched files (Go: their package). A finding on
+  added lines or session approvals debt in a touched file becomes a tool
+  error carrying the findings. The mutation has already landed; this is
+  not a block or rollback. Debt includes a new uncovered marker, a new
+  orphaned approval, and an approval whose marker was deleted.
+  A verified violation is always a tool error. A post event
   that cannot be verified reports three facts: the mutation may already have
   landed, why verification did not complete, and that the mutation must not be
   repeated before `dev.py check`. OMP appends that warning to the model-facing
@@ -596,6 +607,10 @@ are the same whichever host drives them. In host-neutral terms:
   A known target whose content is ambiguous asks when it reaches a bypass
   surface. An unclassifiable file mutation or a failed policy dependency blocks
   before it can run; it is never weakened into an approval prompt.
+  Session approvals debt also blocks an edit if any target is outside the
+  repair set: files of the debt's markers and `.tackbox/approvals`.
+  A multi-file edit with one unrelated target is refused as a whole.
+  The existing approval gates still apply to every permitted repair.
 
 Only markers in files an engine would lint participate in the check
 (D012): a marker in a Go `testdata/` path or a non-lintable fixture
@@ -658,17 +673,17 @@ the current file.
   three-fact warning, omits an `isError` override so OMP preserves the host
   state, and tells the model not to repeat the mutation before `dev.py check`.
 - an opaque write channel (`xd://` tool devices, archive members, SQLite rows),
-  every `bash` call, and every `eval` call name no file, so they run the
-  whole-tree approvals wall alone.
+  every `bash` call, and every `eval` call name no file, so they run
+  neither approvals checks nor targeted lint.
 - MCP tool names are not enumerated by this extension. Their file mutations are
-  an explicit residual outside its pre gate and post wall; review their diff and
-  run `dev.py check`.
+  an explicit residual outside its pre gate and targeted post checks;
+  review their diff and run `dev.py check`.
 - the post adapter consumes each result-detail record independently. It falls
   back to a snapshot only for that record when the record is pruned; failed
   records do not widen the scope of successful landed records. OMP 18.x does
   not identify a landed subset for a single aggregate error without per-file
-  details, so Tackbox runs its whole-tree wall, preserves the host error, and
-  cannot safely perform targeted lint for that residual.
+  details, so Tackbox preserves the host error and cannot safely perform
+  targeted lint for that residual. It does not run a whole-tree approvals check.
 
 The extension runs `uvx tackbox@<npm package version> hook-protocol`. A tagged
 wheel is built and protocol-canary tested, published to PyPI, then a successful
@@ -711,16 +726,16 @@ one JSON decision on stdout:
   landed). Pre requests omit `succeeded`; post requests require the boolean
   `succeeded`, so a failed tool is not misreported as a missing landed file.
 - `tool` is one of `edit`, `apply_patch`, `write`, `bash`, or `eval`. `bash` and
-  `eval` are target-free wall-only channels.
+  `eval` are target-free channels and run no approvals or targeted lint.
 - a **target** is one file mutation with an absolute `path`, `op`, and
   `expectedPresent`. `edit` and `write` expect the path to exist, `delete`
   expects it absent, and a move reports an absent source plus a present
   destination. `content` is a full replacement; otherwise `added` and
   `removed` are text fragments. `content` and fragments are mutually exclusive.
   `ambiguous: true` means a known target needs whole-file treatment.
-- **zero targets** is the opaque channel: the whole-tree wall runs, nothing
-  file-scoped does. `unknown` is a non-empty reason only when no concrete
-  target can be named; it blocks pre and warns post.
+- **zero targets** is the opaque channel: no approvals or targeted lint runs.
+  `unknown` is a non-empty reason only when no concrete target can be named;
+  it blocks pre and warns post.
 - the wire decisions are `allow`, `ask`, `block`, and `warn`. The semantic
   outcomes are inactive, allow, approval-required, violation, and unverified:
   unverified maps to `block` pre and `warn` post. Hosts must make a post warning

package/bin/tackbox-eslint.js

@@ -2,6 +2,7 @@
 const path = require('path')
 const fs = require('fs')
 const { ESLint } = require('eslint')
+const { setSuppressedReporter } = require('../js/rules/_shared')
 
 const REPORTERS_FLAG = '--reporters='
 
@@ -129,6 +130,12 @@ async function main() {
     process.stderr.write('tackbox-eslint: no files supplied\n')
     process.exit(2)
   }
+  if (machine) {
+    setSuppressedReporter(finding => {
+      const file = path.relative(process.cwd(), finding.file).split(path.sep).join('/')
+      process.stdout.write(JSON.stringify({ ...finding, file }) + '\n')
+    })
+  }
   validateDeclarations(decls)
   const eslint = new ESLint({
     // Inline directives (eslint-disable ... tackbox/<rule>) would be an

package/js/README.md

@@ -146,6 +146,13 @@ siblings still report. Recognition reads the enclosing element's
 preceding `SvelteHTMLComment` sibling; `/* ... */` block comments
 are never markers.
 
+The wrapper's `--machine` output retains suppressed findings with the
+same rule text plus `suppressed`, `marker_kind`, and `marker_line`.
+Human ESLint output and its exit status ignore them. Only the shared
+approvals renderer presents them (D020 in
+[../rules/DECISIONS.md](../rules/DECISIONS.md)); a marker that excuses
+no violation produces no suppressed finding.
+
 ## Markdown
 
 The CLI also lints `.md` files through `tackbox-mdlint`, a thin markdownlint

package/js/omp/index.js

@@ -9,7 +9,7 @@ const HEADLESS_NOTE =
   'tackbox cannot ask here (no interactive session), so the call is blocked' +
   ' instead of approved. Re-issue it interactively, or drop the gated line.'
 const DENIED = 'tackbox: approval denied.'
-const BLOCKED = 'tackbox blocked this change:'
+const FINDINGS = 'tackbox found issues after this change:'
 
 module.exports = function tackbox(pi) {
   pi.setLabel('tackbox')
@@ -61,7 +61,7 @@ function applyPost(decision, event) {
   const kind = decision && decision.kind
   if (kind === hook.BLOCK) {
     return {
-      content: appended(event, `${BLOCKED}\n${decision.reason}`),
+      content: appended(event, `${FINDINGS}\n${decision.reason}`),
       isError: true,
     }
   }

package/js/rules/_shared.js

@@ -392,12 +392,18 @@ function blockHasReport(context, block, errName) {
   return found
 }
 
-// markerText reports whether a comment's raw text is `<prefix>: <reason>` with
-// reason at least MIN_REASON chars (D009) - the shared marker shape.
-function markerText(raw, prefix) {
+// Multiline HTML comments locate approval identity at the keyword, not the delimiter.
+function markerLine(comment, prefix) {
+  const raw = comment.value
   const text = raw.trim()
-  if (!text.startsWith(prefix + ':')) return false
-  return text.slice(prefix.length + 1).trim().length >= MIN_REASON
+  const marker = prefix + ':'
+  if (!text.startsWith(marker) || text.slice(marker.length).trim().length < MIN_REASON) return null
+  let line = comment.loc.start.line
+  const offset = raw.indexOf(marker)
+  for (let i = 0; i < offset; i++) {
+    if (raw[i] === '\n') line++
+  }
+  return line
 }
 
 // precedingSvelteSibling returns the template node immediately before `el` among
@@ -416,30 +422,51 @@ function precedingSvelteSibling(el) {
   return null
 }
 
-// hasMarkerAbove returns true when a suppression marker `<prefix>: <reason>`
-// (reason at least MIN_REASON chars, D009) sits above node. Two forms: a `//`
-// comment block directly above node - any of its contiguous lines, so a long
-// reason can be followed by human context, a blank line breaking the block - and,
-// in a Svelte template, an HTML comment `<!-- ... -->` immediately above an
-// enclosing element, which covers the whole element (residual A8: an inline
-// handler can span lines). getAllComments omits SvelteHTMLComment nodes, so the
-// template form is read off the element's preceding sibling.
-function hasMarkerAbove(context, node, prefix) {
-  if (!node || !node.loc) return false
+// Svelte HTML comments cover the following element, not just its first line.
+function markerAbove(context, node, prefix) {
+  if (!node || !node.loc) return null
   const sourceCode = context.sourceCode || context.getSourceCode()
   const byEndLine = new Map()
   for (const c of sourceCode.getAllComments()) {
     if (c.type === 'Line') byEndLine.set(c.loc.end.line, c)
   }
   for (let line = node.loc.start.line - 1; byEndLine.has(line); line--) {
-    if (markerText(byEndLine.get(line).value, prefix)) return true
+    const comment = byEndLine.get(line)
+    const marker = markerLine(comment, prefix)
+    if (marker !== null) return marker
   }
   for (let cur = node.parent; cur; cur = cur.parent) {
     if (cur.type !== 'SvelteElement') continue
     const sib = precedingSvelteSibling(cur)
-    if (sib && sib.type === 'SvelteHTMLComment' && markerText(sib.value, prefix)) return true
+    if (sib && sib.type === 'SvelteHTMLComment') {
+      const marker = markerLine(sib, prefix)
+      if (marker !== null) return marker
+    }
+  }
+  return null
+}
+
+let suppressedReporter = null
+
+function setSuppressedReporter(reporter) {
+  suppressedReporter = reporter
+}
+
+function reportWithMarker(context, descriptor, anchor, kind, messages) {
+  const line = markerAbove(context, anchor, kind)
+  if (line === null) {
+    context.report(descriptor)
+  } else if (suppressedReporter) {
+    suppressedReporter({
+      file: context.filename || context.getFilename(),
+      line: descriptor.node.loc.start.line,
+      rule: context.id,
+      message: messages[descriptor.messageId],
+      suppressed: true,
+      marker_kind: kind,
+      marker_line: line,
+    })
   }
-  return false
 }
 
 // --- F2b: path-sensitive no-swallow analysis -----------------------------
@@ -835,7 +862,8 @@ module.exports = {
   walk,
   blockHasThrow,
   blockHasReport,
-  hasMarkerAbove,
+  reportWithMarker,
+  setSuppressedReporter,
   enclosingFn,
   fnReturnsResultLike,
   someNode,

package/js/rules/no-broad-notify.js

@@ -1,4 +1,4 @@
-const { hasMarkerAbove, walk, isTier1Notify, argFlows, isTestFile } = require('./_shared')
+const { reportWithMarker, walk, isTier1Notify, argFlows, isTestFile } = require('./_shared')
 
 // guarded: `call` sits under an additional condition strictly inside the catch
 // body - an if-branch (consequent/alternate) or a switch case. A notify
@@ -35,11 +35,12 @@ module.exports = {
         if (errName == null) return
         const body = node.body
         if (!body || body.type !== 'BlockStatement') return
-        if (hasMarkerAbove(context, node.parent, 'no-report')) return
         walk(body, call => {
           if (call.type !== 'CallExpression') return
           if (!isTier1Notify(context, call) || !argFlows(call, errName)) return
-          if (!guarded(call, body)) context.report({ node: call, messageId: 'broad' })
+          if (!guarded(call, body)) {
+            reportWithMarker(context, { node: call, messageId: 'broad' }, node.parent, 'no-report', module.exports.meta.messages)
+          }
         })
       },
     }

package/js/rules/no-parse-fallback.js

@@ -1,5 +1,5 @@
 const {
-  hasMarkerAbove,
+  reportWithMarker,
   enclosingFn,
   fnReturnsResultLike,
   errObjectFlows,
@@ -139,11 +139,10 @@ module.exports = {
         if (!tryBlockParses(node.block)) return
         const handler = node.handler
         if (!handler || !handler.body || handler.body.type !== 'BlockStatement') return
-        if (hasMarkerAbove(context, node, 'parse-skip')) return
         const errName = handler.param && handler.param.type === 'Identifier' ? handler.param.name : null
         const allowBoundary = fnReturnsResultLike(enclosingFn(node))
         if (catchPropagates(handler.body, errName, allowBoundary)) return
-        context.report({ node: handler, messageId: 'fallback' })
+        reportWithMarker(context, { node: handler, messageId: 'fallback' }, node, 'parse-skip', module.exports.meta.messages)
       },
     }
   },

package/js/rules/no-skipped-test.js

@@ -1,4 +1,4 @@
-const { hasMarkerAbove, matchesTestModifier, isStaticString, staticStringValue, TEST_ROOTS } = require('./_shared')
+const { reportWithMarker, matchesTestModifier, isStaticString, staticStringValue, TEST_ROOTS } = require('./_shared')
 
 const SKIP_PROPS = new Set(['skip', 'todo', 'skipIf', 'fixme'])
 const BARE = new Set(['xit', 'xdescribe', 'xtest'])
@@ -80,14 +80,12 @@ module.exports = {
       CallExpression(node) {
         if (matchesTestModifier(node.callee, BARE, n => SKIP_PROPS.has(n))) {
           if (hasInCallReason(node)) return
-          if (hasMarkerAbove(context, outermostCall(node), 'test-skip')) return
-          context.report({ node, messageId: 'skipped' })
+          reportWithMarker(context, { node, messageId: 'skipped' }, outermostCall(node), 'test-skip', module.exports.meta.messages)
           return
         }
         if (node.callee.type === 'Identifier' && TEST_ROOTS.has(node.callee.name)) {
           if (optionsSkipVerdict(node) !== 'flag') return
-          if (hasMarkerAbove(context, outermostCall(node), 'test-skip')) return
-          context.report({ node, messageId: 'skipped' })
+          reportWithMarker(context, { node, messageId: 'skipped' }, outermostCall(node), 'test-skip', module.exports.meta.messages)
         }
       },
     }

package/js/rules/no-swallow-allsettled.js

@@ -1,4 +1,4 @@
-const { hasMarkerAbove, enclosingFn, someNode } = require('./_shared')
+const { reportWithMarker, enclosingFn, someNode } = require('./_shared')
 
 // isAllSettledCall: syntactic `Promise.allSettled(...)`. Matched by shape, not
 // resolution - Promise is a global and allSettled is unambiguous.
@@ -43,9 +43,8 @@ module.exports = {
     return {
       CallExpression(node) {
         if (!isAllSettledCall(node)) return
-        if (hasMarkerAbove(context, node, 'no-report')) return
         if (refsReason(enclosingFn(node) || sc.ast)) return
-        context.report({ node, messageId: 'swallow' })
+        reportWithMarker(context, { node, messageId: 'swallow' }, node, 'no-report', module.exports.meta.messages)
       },
     }
   },

package/js/rules/no-swallow-catch.js

@@ -1,5 +1,5 @@
 const {
-  hasMarkerAbove,
+  reportWithMarker,
   enclosingFn,
   fnReturnsResultLike,
   makeHandledAnalysis,
@@ -20,11 +20,10 @@ module.exports = {
         const body = node.body
         if (!body || body.type !== 'BlockStatement') return
         const tryStmt = node.parent
-        if (tryStmt && hasMarkerAbove(context, tryStmt, 'no-report')) return
         const errName = node.param && node.param.type === 'Identifier' ? node.param.name : null
         const allowBoundary = fnReturnsResultLike(enclosingFn(node))
         if (makeHandledAnalysis({ context, errName, allowBoundary }).handled(body)) return
-        context.report({ node, messageId: 'swallow' })
+        reportWithMarker(context, { node, messageId: 'swallow' }, tryStmt, 'no-report', module.exports.meta.messages)
       },
     }
   },

package/js/rules/no-swallow-promise-catch.js

@@ -1,4 +1,4 @@
-const { hasMarkerAbove, makeHandledAnalysis } = require('./_shared')
+const { reportWithMarker, makeHandledAnalysis } = require('./_shared')
 
 // rejectionHandler returns the rejection-handler argument of a promise
 // method: `.catch(onErr)` -> arg 0, `.then(onOk, onErr)` -> arg 1. A single-arg
@@ -28,10 +28,9 @@ module.exports = {
         const handler = rejectionHandler(node)
         if (!handler) return
         if (handler.type !== 'ArrowFunctionExpression' && handler.type !== 'FunctionExpression') return
-        if (hasMarkerAbove(context, node, 'no-report')) return
         const errName = handler.params[0] && handler.params[0].type === 'Identifier' ? handler.params[0].name : null
         if (makeHandledAnalysis({ context, errName, allowBoundary: false, returnIdentity: true }).handled(handler.body)) return
-        context.report({ node, messageId: 'swallow' })
+        reportWithMarker(context, { node, messageId: 'swallow' }, node, 'no-report', module.exports.meta.messages)
       },
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tackbox",
-  "version": "0.1.97",
+  "version": "0.1.98",
   "description": "ESLint and Markdown lint plugins, an Oh My Pi extension, plus direct error-reporting helpers for JavaScript and TypeScript.",
   "license": "MIT",
   "main": "./js/eslint-plugin.js",