@jjchill/probity-rules 0.1.0

package/kiro/probity-kiro-translate.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""
+Translation helper for the Probity <-> Kiro PreToolUse shim.
+
+Two subcommands, both stdin -> stdout so the shim can pipe cleanly
+(the earlier inline `python3 - <<'PY'` form clashed the heredoc with the
+piped payload on stdin, silently producing empty output = allow):
+
+  event   Read a Kiro preToolUse event JSON on stdin, write the
+          equivalent claude-code payload JSON on stdout. Emits NOTHING
+          (and exits 0) for non-mutating tools, so the shim can fast-allow.
+          A transcript path, if provided via $TRANSCRIPT_TMP, is attached
+          so Probity's history-based rules work under Kiro.
+
+  reason  Read a Probity claude-code response JSON on stdin. If it is a
+          deny, write the permissionDecisionReason on stdout; otherwise
+          write nothing. The shim turns a non-empty reason into `exit 2`.
+"""
+import json
+import os
+import sys
+
+WRITE_TOOLS = {"fs_write", "write", "fsWrite"}
+SHELL_TOOLS = {"shell", "execute_bash", "execute_cmd", "executeBash", "executeCmd"}
+
+
+def _insert_result(path, cwd, content, insert_line):
+    """Reconstruct a file's content after a Kiro `insert`, so content-based
+    Probity rules (e.g. the glossary guard) see the true result rather than
+    only the introduced text. The pending write hasn't run yet, so the file on
+    disk is the pre-write state; fall back to the introduced text alone if it
+    cannot be read."""
+    full = path if os.path.isabs(path) else os.path.join(cwd, path)
+    try:
+        with open(full, "r", encoding="utf-8") as handle:
+            existing = handle.read()
+    except OSError:
+        return content
+    if isinstance(insert_line, int) and not isinstance(insert_line, bool):
+        lines = existing.splitlines(keepends=True)
+        idx = max(0, min(insert_line, len(lines)))
+        block = content if content.endswith("\n") else content + "\n"
+        return "".join(lines[:idx]) + block + "".join(lines[idx:])
+    separator = "" if existing == "" or existing.endswith("\n") else "\n"
+    return existing + separator + content
+
+
+def cmd_event():
+    try:
+        event = json.load(sys.stdin)
+    except Exception:
+        return 0  # unparseable -> emit nothing -> shim allows
+    if not isinstance(event, dict):
+        return 0
+
+    tool = event.get("tool_name") or ""
+    ti = event.get("tool_input")
+    ti = ti if isinstance(ti, dict) else {}
+    cwd = event.get("cwd") or os.getcwd()
+
+    if tool in SHELL_TOOLS:
+        payload = {"tool_name": "Bash", "tool_input": {"command": ti.get("command", "")}}
+    elif tool in WRITE_TOOLS:
+        path = ti.get("path", "")
+        if ti.get("command") == "strReplace":
+            payload = {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": path,
+                    "old_string": ti.get("oldStr", ""),
+                    "new_string": ti.get("newStr", ""),
+                    "replace_all": bool(ti.get("replaceAll", False)),
+                },
+                "cwd": cwd,
+            }
+        elif ti.get("command") == "insert":
+            # insert ADDS to an existing file; a Write of only the introduced
+            # text would tell Probity the whole file became that text. Rebuild
+            # the true resulting content from the pre-write file on disk.
+            payload = {
+                "tool_name": "Write",
+                "tool_input": {
+                    "file_path": path,
+                    "content": _insert_result(path, cwd, ti.get("content", ""), ti.get("insertLine")),
+                },
+                "cwd": cwd,
+            }
+        else:  # create -> Write of the whole-file content
+            payload = {
+                "tool_name": "Write",
+                "tool_input": {"file_path": path, "content": ti.get("content", "")},
+                "cwd": cwd,
+            }
+    else:
+        return 0  # not a mutating tool -> allow without invoking probity
+
+    transcript = os.environ.get("TRANSCRIPT_TMP") or ""
+    if transcript:
+        payload["transcript_path"] = transcript
+
+    sys.stdout.write(json.dumps(payload))
+    return 0
+
+
+def cmd_reason():
+    raw = sys.stdin.read().strip()
+    if not raw:
+        return 0
+    try:
+        obj = json.loads(raw)
+    except Exception:
+        return 0
+    if not isinstance(obj, dict):
+        return 0
+    out = obj.get("hookSpecificOutput", {})
+    if isinstance(out, dict) and out.get("permissionDecision") == "deny":
+        sys.stdout.write(out.get("permissionDecisionReason", "blocked by Probity"))
+    return 0
+
+
+def main(argv):
+    mode = argv[1] if len(argv) > 1 else ""
+    if mode == "event":
+        return cmd_event()
+    if mode == "reason":
+        return cmd_reason()
+    sys.stderr.write("usage: probity-kiro-translate.py {event|reason}\n")
+    return 64
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/kiro/probity-kiro.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+#
+# Probity <-> Kiro PreToolUse shim.
+#
+# Probity (github.com/nizos/probity) ships vendor adapters for
+# claude-code, codex, and github-copilot -- but not Kiro. This shim lets
+# the SAME probity.config.ts enforce the mysudovpn-ios workflow under Kiro
+# by translating between Kiro's hook contract and the claude-code one:
+#
+#   1. Kiro fires `preToolUse` with an event JSON on stdin:
+#        {"hook_event_name":"preToolUse","cwd":..,"tool_name":"fs_write",
+#         "tool_input":{...}}
+#      and BLOCKS a tool when the hook exits 2 (STDERR is returned to the LLM).
+#
+#   2. Probity's claude-code vendor expects a Claude-shaped payload
+#        {"tool_name":"Write|Edit|Bash|..","tool_input":{..},"cwd":..,
+#         "transcript_path":..}
+#      and signals a block by printing a deny JSON to stdout with exit 0:
+#        {"hookSpecificOutput":{"permissionDecision":"deny",
+#         "permissionDecisionReason":"Probity: ..."}}
+#
+# The event<->payload and response<->reason translation lives in
+# probity-kiro-translate.py (kept out of this script so stdin pipes
+# cleanly). We attach a transduced transcript so history-based rules
+# (green-gate, TDD) work, then convert a deny response into `exit 2`.
+#
+# Fail-safe posture: a genuine rule violation blocks (exit 2). Shim-internal
+# errors (bad JSON, missing probity) warn on STDERR and ALLOW (exit 0) so a
+# tooling bug never wedges the session; the commit green-gate remains the
+# correctness backstop.
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PROBITY="$ROOT/node_modules/.bin/probity"
+TRANSLATE="$SCRIPT_DIR/probity-kiro-translate.py"
+TRANSDUCER="$SCRIPT_DIR/kiro-transcript-to-claude.py"
+
+EVENT="$(cat)"
+
+# Probity discovers probity.config.ts and node_modules from cwd.
+cd "$ROOT" 2>/dev/null || true
+
+if [ ! -x "$PROBITY" ]; then
+  echo "probity-kiro: probity not installed at $PROBITY (run npm install)" >&2
+  exit 0
+fi
+
+# --- Transcript: transduce Kiro's session JSONL to the Anthropic shape ----
+TRANSCRIPT_TMP=""
+if [ -n "${KIRO_SESSION_ID:-}" ]; then
+  KIRO_JSONL="$HOME/.kiro/sessions/cli/${KIRO_SESSION_ID}.jsonl"
+  if [ -f "$KIRO_JSONL" ] && command -v python3 >/dev/null 2>&1; then
+    # Trailing X's only: BSD/macOS mktemp substitutes a run of X's solely when
+    # it ends the template. A `.jsonl` suffix here would be taken literally,
+    # colliding on every second invocation. Probity reads the path, not the
+    # extension, so no suffix is needed.
+    TRANSCRIPT_TMP="$(mktemp "${TMPDIR:-/tmp}/probity-kiro-transcript.XXXXXX")"
+    if ! python3 "$TRANSDUCER" "$KIRO_JSONL" >"$TRANSCRIPT_TMP" 2>/dev/null; then
+      rm -f "$TRANSCRIPT_TMP"
+      TRANSCRIPT_TMP=""
+    fi
+  fi
+fi
+export TRANSCRIPT_TMP
+
+cleanup() { [ -n "$TRANSCRIPT_TMP" ] && rm -f "$TRANSCRIPT_TMP"; }
+trap cleanup EXIT
+
+# --- Translate the Kiro event to a claude-code payload --------------------
+# Empty stdout == non-mutating tool (or unparseable) -> allow, skip probity.
+PAYLOAD="$(printf '%s' "$EVENT" | python3 "$TRANSLATE" event)"
+if [ -z "$PAYLOAD" ]; then
+  exit 0
+fi
+
+# --- Invoke Probity and translate its response to Kiro's exit codes -------
+RESPONSE="$(printf '%s' "$PAYLOAD" | "$PROBITY" --agent claude-code 2>/dev/null)"
+REASON="$(printf '%s' "$RESPONSE" | python3 "$TRANSLATE" reason)"
+
+if [ -n "$REASON" ]; then
+  printf '%s\n' "$REASON" >&2
+  exit 2
+fi
+
+exit 0

package/kiro/skill-activation-forced-eval.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# userPromptSubmit hook that forces explicit skill evaluation.
+#
+# Kiro CLI port of .claude/hooks/skill-activation-forced-eval.sh. Kiro has
+# no Skill() tool, so "activation" means the agent READS the relevant
+# SKILL.md before implementing. This hook's stdout is injected into context
+# on every user prompt (see Kiro's Hooks docs: userPromptSubmit stdout is
+# added to the agent's context on exit 0).
+#
+# Install either project-locally (.kiro/hooks/) — referenced by
+# kiro-agent.template.json — or user-wide (~/.kiro/hooks/) for a global
+# default agent. Both work; the project-local copy keeps a checkout
+# self-contained (no per-machine global prerequisite).
+
+cat <<'EOF'
+INSTRUCTION: MANDATORY SKILL ACTIVATION SEQUENCE
+
+Step 1 - EVALUATE (do this in your response):
+For each skill listed in this session's available skills, state:
+  [skill-name] - YES/NO - [one-line reason]
+
+Step 2 - ACTIVATE (do this immediately after Step 1):
+IF any skills are YES -> Read that skill's SKILL.md (e.g.
+  .kiro/skills/<skill-name>/SKILL.md) for EACH relevant skill NOW, and follow it.
+IF no skills are YES -> State "No skills needed" and proceed.
+
+Step 3 - IMPLEMENT:
+Only after Step 2 is complete, proceed with implementation.
+
+CRITICAL: You MUST load (read) each YES skill's SKILL.md in Step 2 before
+implementing. The evaluation (Step 1) is WORTHLESS unless you ACTIVATE (Step 2)
+the skills. Skip the whole sequence only for trivial conversational replies that
+touch no skill's domain.
+
+Example of correct sequence:
+- test-driven-development: YES - changing behaviour, needs RED->GREEN->REFACTOR
+- code-review-and-quality: YES - will review the diff before done
+- perfetto-sql: NO - no trace analysis in this task
+
+[Then IMMEDIATELY read the SKILL.md for each YES skill:]
+> Read .kiro/skills/test-driven-development/SKILL.md
+> Read .kiro/skills/code-review-and-quality/SKILL.md
+
+[THEN and ONLY THEN start implementation]
+EOF

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@jjchill/probity-rules",
+  "version": "0.1.0",
+  "description": "Versioned Probity rule presets and CLI tooling for the agent-skills catalog (test-driven-development, ports-and-adapters, acceptance-testing, spec-test parity, ubiquitous-language) — see hooks/PROBITY.md.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./rules/*": "./dist/rules/*.js",
+    "./presets/*": "./dist/presets/*.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "probity-scope-report": "dist/scripts/scope-report.js",
+    "probity-spec-parity": "scripts/spec-parity.mjs"
+  },
+  "files": [
+    "dist",
+    "scripts/spec-parity.mjs",
+    "kiro/kiro-agent.template.json",
+    "kiro/kiro-transcript-to-claude.py",
+    "kiro/probity-kiro-translate.py",
+    "kiro/probity-kiro.sh",
+    "kiro/skill-activation-forced-eval.sh",
+    "kiro/README.md",
+    "probity.config.ts",
+    "probity.config.kotlin.ts",
+    "probity.config.kmp.ts",
+    "probity.config.swift.ts",
+    "GLOSSARY.template.md",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@nizos/probity": "^1.10.0"
+  },
+  "peerDependenciesMeta": {
+    "@ast-grep/napi": {
+      "optional": true
+    },
+    "@ast-grep/lang-kotlin": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "picomatch": "^4.0.4",
+    "jiti": "^2.6.1"
+  },
+  "devDependencies": {
+    "@ast-grep/lang-kotlin": "^0.0.7",
+    "@ast-grep/napi": "^0.45.1",
+    "@nizos/probity": "^1.10.0",
+    "@types/node": "^22.0.0",
+    "@types/picomatch": "^3.0.2",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test rules/*.test.mts scripts/*.test.mjs",
+    "test:kiro": "for f in kiro/*.test.py; do python3 \"$f\" || exit 1; done",
+    "eval": "tsx evals/workflow-eval.ts",
+    "prepublishOnly": "npm run clean && npm run build && npm test",
+    "pack:check": "npm pack --dry-run"
+  }
+}

package/probity.config.kmp.ts

@@ -0,0 +1,40 @@
+/**
+ * Probity config template — Kotlin Multiplatform preset.
+ *
+ * Same enforcement as probity.config.kotlin.ts, recalibrated for a
+ * KMP codebase with ports-and-adapters codified per feature module:
+ * source sets (`commonMain`/`androidMain`/`desktopMain`/`iosMain`,
+ * tests in `commonTest`/`androidHostTest`/…), core vs adapter split
+ * by package (`domain`/`port`/`usecase`/`presentation` vs
+ * `adapter`/`di`/`ui`), kotlin.test + hand-written fakes with NO
+ * mocking library, Koin at the composition root only, and
+ * acceptance tests driven through a Robot DSL at the ViewModel
+ * boundary with Markdown Given/When/Then specs in docs/specs/.
+ *
+ * Install (not yet published — see probity.config.ts for the
+ * clone-path note):
+ *
+ *   npm install -D @nizos/probity @jjchill/probity-rules
+ *
+ * Probity still runs on Node: `npm install -D @nizos/probity`
+ * (plus optionally @ast-grep/napi @ast-grep/lang-kotlin for the TDD
+ * fast-path) next to gradlew.
+ *
+ * EDIT: the rule entries live in `presets/kmp.ts` (`kmpRuleEntries`).
+ * The globs inside it (core/domain packages, source sets, adapter
+ * packages) are calibrated to the reference codebase above — audit
+ * them against your tree with `npx probity-scope-report` and adjust
+ * to your layout. The optional `parity` second argument turns on the
+ * per-scenario driver mapping; see the commented example in
+ * presets/kmp.ts.
+ */
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { defineConfig } from '@nizos/probity'
+
+import { kmpRuleEntries } from '@jjchill/probity-rules/presets/kmp'
+
+const ROOT = dirname(fileURLToPath(import.meta.url))
+
+export default defineConfig({ rules: kmpRuleEntries(ROOT) })

package/probity.config.kotlin.ts

@@ -0,0 +1,37 @@
+/**
+ * Probity config template — Kotlin/JVM/Android preset.
+ *
+ * Same enforcement as probity.config.ts (see hooks/PROBITY.md) with
+ * the deterministic layer swapped to Kotlin-shaped rules. Calibrated
+ * against a multi-module Android codebase (Gradle per project,
+ * `<module>-core` / `<module>-ui` split, Mockito-kotlin + JUnit 4,
+ * AWS/Amplify/Apollo/OkHttp/Retrofit/Room vendor stack) — adjust the
+ * options below to your layout.
+ *
+ * Install (not yet published — see probity.config.ts for the
+ * clone-path note):
+ *
+ *   npm install -D @nizos/probity @jjchill/probity-rules
+ *
+ * Note Probity itself still runs on Node: the consuming Kotlin
+ * project needs a one-dependency package.json next to gradlew.
+ *
+ * EDIT THESE OPTIONS to your layout — see presets/kotlin.ts
+ * (`KotlinPresetOptions`) for the full list and every option's
+ * current default:
+ *   - coreGlobs        — your core modules (e.g. `*-core` of a core/ui split)
+ *   - staticMockGlobs   — your test source sets
+ *   - acceptanceTestGlobs / acceptanceLanguageGlobs — your spec layer
+ *   - seamHint          — your ambient-effect port(s)
+ *   - commitCommand      — your real Gradle test task
+ */
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { defineConfig } from '@nizos/probity'
+
+import { kotlinRuleEntries } from '@jjchill/probity-rules/presets/kotlin'
+
+const ROOT = dirname(fileURLToPath(import.meta.url))
+
+export default defineConfig({ rules: kotlinRuleEntries(ROOT) })

package/probity.config.swift.ts

@@ -0,0 +1,38 @@
+/**
+ * Probity config template — Swift/iOS preset.
+ *
+ * Same enforcement stack as the Kotlin presets (see hooks/PROBITY.md),
+ * recalibrated for a native iOS app: an Xcode workspace with the
+ * acceptance suite in AcceptanceTests/ following the four-layer model
+ * (Specs + Component test glue / Scenarios / DSL / Drivers), XCUITest
+ * plus an app-hosted component-test target, MVVM view models over
+ * use-case ports, and Markdown Given/When/Then specs in docs/specs/.
+ * Calibrated against a production CocoaPods + SwiftPM app — adjust
+ * globs and package names to your layout.
+ *
+ * Install (not yet published — see probity.config.ts for the
+ * clone-path note):
+ *
+ *   npm install -D @nizos/probity @jjchill/probity-rules
+ *
+ * Probity runs on Node: `npm install -D @nizos/probity` (a
+ * one-dependency package.json with `"type": "module"` next to the
+ * xcworkspace is fine).
+ *
+ * EDIT: the rule entries live in `presets/swift.ts`
+ * (`swiftRuleEntries`). The globs inside it (AcceptanceTests/ layers,
+ * App/Sources packages) are calibrated to the reference app above —
+ * audit them against your tree with `npx probity-scope-report` before
+ * trusting the gate; the file's own comments flag which patterns need
+ * per-project calibration (test command, driver scopes).
+ */
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { defineConfig } from '@nizos/probity'
+
+import { swiftRuleEntries } from '@jjchill/probity-rules/presets/swift'
+
+const ROOT = dirname(fileURLToPath(import.meta.url))
+
+export default defineConfig({ rules: swiftRuleEntries(ROOT) })

package/probity.config.ts

@@ -0,0 +1,43 @@
+/**
+ * Probity config template for agent-skills projects — plain JS/TS
+ * preset.
+ *
+ * Copy this file to your project root as `probity.config.ts`, install
+ * the rules package and Probity itself:
+ *
+ *   npm install -D @nizos/probity @jjchill/probity-rules
+ *
+ * (not yet published — until then, install from a clone:
+ *   npm install -D @nizos/probity /path/to/agent-skills/hooks/probity
+ *  after running `npm run build` in that directory), then wire the
+ * hook (see hooks/PROBITY.md).
+ *
+ * EDIT THESE OPTIONS to your layout — the defaults below describe a
+ * common src/core + src/adapters project and WILL need adjusting:
+ *   - coreGlobs             — where your core/domain code lives
+ *   - infrastructureImports — your stack's known vendor/framework imports
+ *   - specGlobs             — where your acceptance specs live
+ *   - glossaryPath          — absolute path to a ubiquitous-language glossary
+ *   - commitCommand / commitSuccessPattern / commitFailurePattern
+ *                           — your real test command and its output shapes
+ * See presets/js.ts (`JsPresetOptions`) for the full list and every
+ * option's current default.
+ *
+ * Brownfield? The mutation-probe and characterization round-trips
+ * (`withMutationProbe`/`enforceProbeReversion`,
+ * `withCharacterizationTest`/`enforceCharacterizationResolution`,
+ * re-exported from `@jjchill/probity-rules/rules/kotlin` despite the
+ * filename — language-neutral) sanction retrofitting tests onto
+ * pre-existing behavior, which the plain TDD gate otherwise blocks (a
+ * test for existing behavior is born green). Wire them when you start
+ * backfilling coverage; see hooks/PROBITY.md.
+ */
+import { defineConfig } from '@nizos/probity'
+
+import { jsRuleEntries } from '@jjchill/probity-rules/presets/js'
+
+export default defineConfig({
+  rules: jsRuleEntries({
+    // glossaryPath: fileURLToPath(new URL('./docs/GLOSSARY.md', import.meta.url)),
+  }),
+})