@davesheffer/hunch 1.8.2 → 1.8.3

package/README.md

@@ -13,6 +13,9 @@ relevant context before it makes a change.
 Memory starts **advisory**. Nothing blocks until you explicitly trust a precise rule and choose
 strict enforcement.
 
+**Memory is the input. The product boundary is the receipt:** relevant evidence before an edit,
+then a deterministic check of the change against the rules your team has explicitly trusted.
+
 ## Start in five minutes
 
 Requires Node 22.13+ and a git repository.
@@ -104,5 +107,6 @@ Local tools see the combined graph; public CI and committed documentation stay p
 - [VS Code extension](vscode-extension/README.md)
 - [Contributing](CONTRIBUTING.md)
 - [Architecture benchmark](bench/architectural-conformance.md)
+- [Competitive landscape (dated; re-verify before quoting)](docs/competitive-landscape.md)
 
 Apache-2.0

package/dist/cli/index.js

@@ -1957,6 +1957,23 @@ experimentCmd
         store.close();
     }
 });
+experimentCmd
+    .command("qualify")
+    .description("Record a passing excluded comprehension check before an EXP-03 revision-2 timed review.")
+    .argument("<file>", "reviewer qualification JSON")
+    .action((file) => {
+    const { store, root } = storeFor();
+    try {
+        const input = JSON.parse(readFileSync(resolve(file), "utf8"));
+        console.log(JSON.stringify(new ConstitutionService(store, root).qualifyExperimentReviewer(input), null, 2));
+    }
+    catch (e) {
+        fail(e.message);
+    }
+    finally {
+        store.close();
+    }
+});
 experimentCmd
     .command("next")
     .description("Start or resume the next randomized EXP-03 human review and return only its assigned treatment.")

package/dist/constitution/experiment.js

@@ -245,6 +245,46 @@ export function assignmentTreatment(bank, run, assignment) {
         throw new Error(`assignment ${assignment.id} treatment hash mismatch`);
     return treatment;
 }
+/** Human-facing help is deliberately outside the hash-bound treatment. It may
+ * explain the review task, but must never interpret the assigned evidence. */
+export function experimentReviewGuide(arm) {
+    const notEnough = {
+        value: "uncompilable",
+        label: "Not enough information",
+        use_when: "The requirement does not clearly say which code relationship must always hold.",
+    };
+    if (arm === "A") {
+        return {
+            title: "Write one code rule from the requirement",
+            question: "Can one exact code rule be written from the requirement without guessing?",
+            action: "If yes, write one sentence naming the code elements, required or forbidden relationship, direct or transitive meaning, and file scope. If no, choose Not enough information.",
+            answer_template: "<subject> must <directly or transitively> <required or forbidden relationship> <target>; scope: <file or component>",
+            warning: "Use only the stated requirement. Current code may confirm names, but cannot add intent.",
+            choices: [
+                { value: "accepted_precise", label: "Rule written", use_when: "Your sentence expresses one exact rule fully supported by the requirement." },
+                notEnough,
+            ],
+        };
+    }
+    const choices = [
+        { value: "accepted_precise", label: "Yes — exact match", use_when: "The proposed rule says exactly what the requirement says." },
+        { value: "accepted_edited", label: "Needs editing", use_when: "The requirement supports one rule, but the proposal needs a specific correction." },
+        { value: "rejected", label: "Unsupported", use_when: "The proposal adds or changes meaning that the requirement does not support." },
+        notEnough,
+    ];
+    return {
+        title: arm === "C" ? "Check the proposed rule and its proof card" : "Check the proposed rule",
+        question: "Does the proposed rule say exactly what the requirement says?",
+        action: arm === "C"
+            ? "Compare the requirement with the proposed rule, then use the proof card only to check that the named code targets are bound correctly."
+            : "Compare the requirement with the proposed rule. Check the relationship, direction, direct or transitive meaning, and scope.",
+        answer_template: "Choose one plain-language option; include corrected rule text only for Needs editing.",
+        warning: arm === "C"
+            ? "The proof card can verify code bindings, but it cannot add intent missing from the requirement."
+            : "Do not infer intent from the current implementation or from nearby code.",
+        choices,
+    };
+}
 export function experimentRunContentHash(run) {
     const { id: _id, content_hash: _hash, ...body } = run;
     return canonicalHash(body);
@@ -537,6 +577,38 @@ export function compileExperimentReviewStart(run, assignment, reviewer, opts = {
     const contentHash = canonicalHash(body);
     return ExperimentReviewStartSchema.parse({ id: `expreview_${shortHash(contentHash)}`, content_hash: contentHash, ...body });
 }
+export const ExperimentReviewerQualificationSchema = z.object({
+    id: z.string().regex(/^expreviewqual_[a-f0-9]{10}$/),
+    content_hash: z.string().regex(HASH),
+    preregistration_id: z.string().regex(/^expreg_[a-f0-9]{10}$/),
+    preregistration_hash: z.string().regex(HASH),
+    reviewer: z.string().regex(/^human:[^\s]+$/i),
+    protocol: z.literal("exp03-plain-language-comprehension-v2"),
+    cases_hash: z.string().regex(HASH),
+    passed: z.literal(true),
+    reason: z.string().trim().min(1).max(4000),
+    data_class: z.literal("private"),
+    authority: z.literal("none"),
+    recorded_at: z.string().datetime({ offset: true }),
+}).strict();
+export function experimentReviewerQualificationContentHash(record) {
+    const { id: _id, content_hash: _hash, ...body } = record;
+    return canonicalHash(body);
+}
+export function compileExperimentReviewerQualification(input, preregistration, opts = {}) {
+    if (preregistration.experiment !== "EXP-03" || preregistration.revision < 2)
+        throw new Error("plain-language reviewer qualification requires EXP-03 revision 2 or later");
+    if (input.preregistration_id !== preregistration.id || input.preregistration_hash !== preregistration.content_hash)
+        throw new Error("reviewer qualification must bind the exact current preregistration");
+    const body = {
+        ...input,
+        data_class: "private",
+        authority: "none",
+        recorded_at: opts.now ?? new Date().toISOString(),
+    };
+    const contentHash = canonicalHash(body);
+    return ExperimentReviewerQualificationSchema.parse({ id: `expreviewqual_${shortHash(contentHash)}`, content_hash: contentHash, ...body });
+}
 export const ExperimentFollowupSchema = z.object({
     id: z.string().regex(/^expfollow_[a-f0-9]{10}$/),
     content_hash: z.string().regex(HASH),
@@ -943,6 +1015,24 @@ export class ExperimentRepository {
         this.put("experiment-review-starts", parsed.id, parsed);
         return parsed;
     }
+    listReviewerQualifications() {
+        return this.load("experiment-review-qualifications", "expreviewqual_", (raw) => {
+            const parsed = ExperimentReviewerQualificationSchema.parse(raw);
+            if (experimentReviewerQualificationContentHash(parsed) !== parsed.content_hash || parsed.id !== `expreviewqual_${shortHash(parsed.content_hash)}`)
+                throw new Error(`experiment reviewer qualification ${parsed.id} content hash mismatch`);
+            return parsed;
+        }).sort((a, b) => a.id.localeCompare(b.id));
+    }
+    putReviewerQualification(record) {
+        const parsed = ExperimentReviewerQualificationSchema.parse(record);
+        if (experimentReviewerQualificationContentHash(parsed) !== parsed.content_hash || parsed.id !== `expreviewqual_${shortHash(parsed.content_hash)}`)
+            throw new Error(`experiment reviewer qualification ${parsed.id} content hash mismatch`);
+        const incumbent = this.listReviewerQualifications().find((item) => item.preregistration_id === parsed.preregistration_id && item.reviewer === parsed.reviewer);
+        if (incumbent)
+            return incumbent;
+        this.put("experiment-review-qualifications", parsed.id, parsed);
+        return parsed;
+    }
     listFollowups() {
         const records = this.load("experiment-followups", "expfollow_", (raw) => {
             const parsed = ExperimentFollowupSchema.parse(raw);

package/dist/constitution/service.js

@@ -31,7 +31,7 @@ import { evaluateExecutableBehaviorPolicy } from "./behaviorEvaluator.js";
 import { executeG2OperationalDrill } from "./g2Drills.js";
 import { G3_REQUIRED_EXPERIMENTS, G3EvidenceRepository, compileExperimentPreregistration, compileG3Plan, compileProofReviewMeasurement, scoreG3Readiness, } from "./g3.js";
 import { executeG3AdapterConformance, g3ConformanceSourceHash } from "./g3Conformance.js";
-import { ExperimentRepository, assignmentTreatment, buildExperimentReport, compileExperimentCaseBank, compileExperimentFollowup, compileExperimentOutcome, compileExperimentReviewStart, compileExperimentRun, compileExperimentStop, compileExp03ReviewResponse, currentExperimentOutcomes, normalizedEditDistance, } from "./experiment.js";
+import { ExperimentRepository, assignmentTreatment, buildExperimentReport, compileExperimentCaseBank, compileExperimentFollowup, compileExperimentOutcome, compileExperimentReviewStart, compileExperimentReviewerQualification, compileExperimentRun, compileExperimentStop, compileExp03ReviewResponse, currentExperimentOutcomes, experimentReviewGuide, normalizedEditDistance, } from "./experiment.js";
 import { executeExp01Assignment } from "./experimentRunner.js";
 function relationSummary(policy) {
     return {
@@ -492,11 +492,22 @@ export class ConstitutionService {
         const bank = this.experimentRepository.listCaseBanks().find((item) => item.id === run.case_bank_id);
         if (!bank)
             throw new Error(`run ${run.id} is missing exact case bank ${run.case_bank_id}`);
+        const preregistration = this.g3Repository.listExperiments().find((item) => item.id === run.preregistration_id && item.content_hash === run.preregistration_hash);
+        const usesPlainLanguageReview = bank.cases.some((item) => "required_relationship" in item);
+        if (usesPlainLanguageReview && !preregistration)
+            throw new Error(`run ${run.id} is missing exact preregistration ${run.preregistration_id}`);
+        if (preregistration && preregistration.revision >= 2) {
+            const qualification = this.experimentRepository.listReviewerQualifications().find((item) => item.preregistration_id === preregistration.id && item.preregistration_hash === preregistration.content_hash && item.reviewer === reviewer);
+            if (!qualification)
+                throw new Error(`${reviewer} must pass the excluded plain-language comprehension check before a revision-${preregistration.revision} timed review`);
+            const targetReviewers = new Set(bank.cases.map((item) => item.strata.target_reviewer).filter(Boolean));
+            if (targetReviewers.has(reviewer) || targetReviewers.has(reviewer.replace(/^human:/i, "")))
+                throw new Error(`${reviewer} cannot perform timed reviews because the same actor labeled revision-${preregistration.revision} targets`);
+        }
         // Single-operator mitigation (expreg_9c9617cd13, revision >= 3): at least 48 hours
         // must separate the case-bank lock from the FIRST review start — enforced, not
         // merely auditable, so a violation is impossible rather than post-hoc visible.
-        const prereg = this.g3Repository.listExperiments().find((item) => item.id === run.preregistration_id);
-        if (prereg && prereg.revision >= 3) {
+        if (preregistration && preregistration.revision >= 3) {
             const elapsed = Date.parse(opts.now ?? new Date().toISOString()) - Date.parse(bank.locked_at);
             const hasStart = this.experimentRepository.listReviewStarts().some((item) => item.run_id === run.id);
             if (!hasStart && elapsed < 48 * 3_600_000) {
@@ -518,7 +529,13 @@ export class ConstitutionService {
         if (!assignment)
             throw new Error(`no unreviewed EXP-03 assignment is available for ${reviewer}`);
         const start = existing ?? this.experimentRepository.putReviewStart(compileExperimentReviewStart(run, assignment, reviewer, opts));
-        return { start, assignment, treatment: assignmentTreatment(bank, run, assignment) };
+        return { start, assignment, treatment: assignmentTreatment(bank, run, assignment), review_guide: experimentReviewGuide(assignment.arm) };
+    }
+    qualifyExperimentReviewer(input, opts = {}) {
+        const preregistration = this.g3Repository.currentExperiments().find((item) => item.experiment === "EXP-03");
+        if (!preregistration)
+            throw new Error("no current EXP-03 preregistration");
+        return this.experimentRepository.putReviewerQualification(compileExperimentReviewerQualification(input, preregistration, opts));
     }
     /** Resolve an EXP-03 run/assignment/case triple (the shared lookup for both
      *  review-submission dialects). */

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.8.2",
+  "version": "1.8.3",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
-  "description": "Architectural Conformance for AI-generated code: a git-native graph that deterministically blocks AI changes which break your architecture — the semantic invariants (layering, must-reach, dependency direction) pattern-SAST can't express — grounded in the decisions and bugs behind each rule, across any MCP assistant (Claude Code, Cursor, Copilot, Windsurf, Antigravity, Codex).",
+  "description": "Engineering memory and a deterministic Change Gate for AI-assisted codebases: decisions, rejected approaches, constraints, and bug lineage become portable context and opt-in enforcement for every MCP assistant.",
   "homepage": "https://hunch-pi.vercel.app",
   "repository": {
     "type": "git",
@@ -19,6 +19,7 @@
   "files": [
     "dist/**/*.js",
     "bench/constitution-exp03-v1.json",
+    "tooling/competitive-watch.mjs",
     "LICENSE",
     "NOTICE"
   ],
@@ -33,7 +34,12 @@
     "windsurf",
     "antigravity",
     "mcp",
+    "coding-agents",
+    "agent-memory",
     "engineering-memory",
+    "architectural-conformance",
+    "change-gate",
+    "code-governance",
     "knowledge-graph",
     "code-intelligence",
     "ai",
@@ -52,6 +58,7 @@
     "rehearse:constitution": "npm run build && node tooling/constitution-clean-rehearsal.mjs",
     "gate:release": "node tooling/release-gate.mjs",
     "site:proof": "npm run build && node tooling/generate-public-proof.mjs",
+    "research:competitors": "node tooling/competitive-watch.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {

package/tooling/competitive-watch.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+const repos = [
+  "davesheffer/hunch",
+  "gitmem-dev/gitmem",
+  "ismaelkedir/knowit",
+  "weigibbor/mnemo",
+  "oldskultxo/aictx",
+  "riponcm/projectmem",
+  "Cranot/roam-code",
+  "blackwell-systems/knowing",
+];
+
+const distinctivePhrases = [
+  "Causal Merge Verdict",
+  "corrections become enforced",
+  "content-matched constraints",
+  "deterministic Change Gate for AI-assisted codebases",
+];
+
+const token = process.env.GITHUB_TOKEN?.trim();
+const headers = {
+  Accept: "application/vnd.github+json",
+  "User-Agent": "hunch-competitive-watch",
+  "X-GitHub-Api-Version": "2022-11-28",
+  ...(token ? { Authorization: `Bearer ${token}` } : {}),
+};
+
+async function github(path) {
+  const response = await fetch(`https://api.github.com${path}`, { headers });
+  if (!response.ok) {
+    const detail = (await response.text()).slice(0, 300).replaceAll("\n", " ");
+    throw new Error(`GitHub ${response.status} for ${path}: ${detail}`);
+  }
+  return response.json();
+}
+
+async function repoSnapshot(repo) {
+  const data = await github(`/repos/${repo}`);
+  return {
+    repo,
+    created: data.created_at,
+    pushed: data.pushed_at,
+    stars: data.stargazers_count,
+    forks: data.forks_count,
+    issues: data.open_issues_count,
+    url: data.html_url,
+  };
+}
+
+async function phraseSnapshot(phrase) {
+  const query = encodeURIComponent(`\"${phrase}\"`);
+  const data = await github(`/search/code?q=${query}&per_page=100`);
+  const external = data.items
+    .filter((item) => !item.repository.full_name.startsWith("davesheffer/"))
+    .map((item) => ({
+      repo: item.repository.full_name,
+      path: item.path,
+      url: item.html_url,
+    }));
+  return { phrase, total: data.total_count, external };
+}
+
+function render(snapshot, phrases) {
+  const lines = [
+    `# Competitive watch — ${new Date().toISOString()}`,
+    "",
+    "## Public repository signals",
+    "",
+    "| Repository | Created | Last push | Stars | Forks | Open issues |",
+    "| --- | --- | --- | ---: | ---: | ---: |",
+  ];
+
+  for (const item of snapshot) {
+    lines.push(
+      `| [${item.repo}](${item.url}) | ${item.created.slice(0, 10)} | ${item.pushed.slice(0, 10)} | ${item.stars} | ${item.forks} | ${item.issues} |`,
+    );
+  }
+
+  lines.push("", "## Distinctive phrase search", "");
+  if (!token) {
+    lines.push("Skipped: set `GITHUB_TOKEN` to enable authenticated GitHub code search.");
+  } else {
+    for (const result of phrases) {
+      lines.push(`- **${result.phrase}** — ${result.external.length} external indexed match(es)`);
+      for (const match of result.external) {
+        lines.push(`  - [${match.repo} · ${match.path}](${match.url})`);
+      }
+    }
+  }
+
+  lines.push(
+    "",
+    "> Signals are leads, not copying findings. Re-check chronology and substantial similarity before drawing a conclusion.",
+  );
+  return `${lines.join("\n")}\n`;
+}
+
+try {
+  const snapshot = await Promise.all(repos.map(repoSnapshot));
+  const phrases = token
+    ? await Promise.all(distinctivePhrases.map(phraseSnapshot))
+    : [];
+  process.stdout.write(render(snapshot, phrases));
+} catch (error) {
+  process.stderr.write(`competitive-watch: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}