@davesheffer/hunch 1.22.2 → 1.22.3

package/README.md

@@ -179,7 +179,7 @@ does not host that repository. Give teammates and CI normal Git access, keep cre
 the Git credential helper, and have one maintainer connect it:
 
 ```bash
-npm i -g @davesheffer/hunch@1.22.2
+npm i -g @davesheffer/hunch@1.22.3
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -189,7 +189,7 @@ git push
 Teammates then install the same version and run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.22.2
+npm i -g @davesheffer/hunch@1.22.3
 git pull
 hunch init
 hunch doctor

package/dist/core/projectDnaOutcomeExperience.d.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { type Finding } from "./types.js";
+export declare const PROJECT_DNA_USEFULNESS_OBSERVATION_SCHEMA_VERSION: "hunch.project-dna-usefulness-observation/1";
+export declare const PROJECT_DNA_USEFULNESS_SIGNALS: readonly ["used", "prevented", "near_miss", "contradicted", "stale", "unused", "unknown"];
+export declare const PROJECT_DNA_USEFULNESS_EVIDENCE_KINDS: readonly ["explicit_human_observation", "independent_review"];
+export declare const ProjectDnaUsefulnessObservationSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"hunch.project-dna-usefulness-observation/1">;
+    observationId: z.ZodString;
+    episode: z.ZodObject<{
+        provider: z.ZodString;
+        schemaVersion: z.ZodString;
+        episodeId: z.ZodString;
+        episodeHash: z.ZodString;
+        terminalAt: z.ZodString;
+        result: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+            uncertain: "uncertain";
+            abandoned: "abandoned";
+            rolled_back: "rolled_back";
+        }>;
+    }, z.core.$strict>;
+    delivery: z.ZodObject<{
+        receiptRef: z.ZodString;
+        receiptHash: z.ZodString;
+        repositoryId: z.ZodString;
+        repositoryRevision: z.ZodString;
+        profileId: z.ZodString;
+        profileContentHash: z.ZodString;
+        snapshotHash: z.ZodString;
+        retrievalHash: z.ZodString;
+    }, z.core.$strict>;
+    projection: z.ZodObject<{
+        role: z.ZodString;
+        categories: z.ZodArray<z.ZodEnum<{
+            communication: "communication";
+            engineering: "engineering";
+            review: "review";
+            culture: "culture";
+            vocabulary: "vocabulary";
+        }>>;
+        traitIds: z.ZodArray<z.ZodString>;
+        evidenceHashes: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    artifact: z.ZodObject<{
+        kind: z.ZodEnum<{
+            pull_request: "pull_request";
+            commit: "commit";
+            issue: "issue";
+            message: "message";
+        }>;
+        ref: z.ZodString;
+        contentHash: z.ZodString;
+    }, z.core.$strict>;
+    assessment: z.ZodObject<{
+        schemaVersion: z.ZodString;
+        assessmentId: z.ZodString;
+        contentHash: z.ZodString;
+        projectMatchClassification: z.ZodEnum<{
+            unassessable: "unassessable";
+            conformant: "conformant";
+            mixed: "mixed";
+            nonconformant: "nonconformant";
+        }>;
+        causalInterpretation: z.ZodLiteral<"project_match_is_non_causal">;
+    }, z.core.$strict>;
+    signal: z.ZodEnum<{
+        unknown: "unknown";
+        stale: "stale";
+        used: "used";
+        prevented: "prevented";
+        near_miss: "near_miss";
+        contradicted: "contradicted";
+        unused: "unused";
+    }>;
+    evidence: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            explicit_human_observation: "explicit_human_observation";
+            independent_review: "independent_review";
+        }>;
+        ref: z.ZodString;
+        hash: z.ZodString;
+    }, z.core.$strict>>;
+    observedAt: z.ZodString;
+    retainUntil: z.ZodString;
+    privacy: z.ZodObject<{
+        payloadMode: z.ZodLiteral<"references_hashes_only">;
+        rawArtifactIncluded: z.ZodLiteral<false>;
+        rawFeedbackIncluded: z.ZodLiteral<false>;
+        rawProfileIncluded: z.ZodLiteral<false>;
+    }, z.core.$strict>;
+    authority: z.ZodObject<{
+        behavioralEffect: z.ZodLiteral<"none">;
+        mayChangeRanking: z.ZodLiteral<false>;
+        mayPromoteKnowledge: z.ZodLiteral<false>;
+        mayGrantAuthority: z.ZodLiteral<false>;
+    }, z.core.$strict>;
+    contentHash: z.ZodString;
+}, z.core.$strict>;
+export type ProjectDnaUsefulnessObservation = z.infer<typeof ProjectDnaUsefulnessObservationSchema>;
+export type CreateProjectDnaUsefulnessObservationInput = Omit<ProjectDnaUsefulnessObservation, "schema" | "observationId" | "authority" | "contentHash">;
+export declare function createProjectDnaUsefulnessObservation(input: CreateProjectDnaUsefulnessObservationInput): ProjectDnaUsefulnessObservation;
+export declare function assertProjectDnaUsefulnessObservation(value: unknown): asserts value is ProjectDnaUsefulnessObservation;
+/** Contradiction and staleness create review work, never a profile mutation or policy. */
+export declare function projectDnaUsefulnessObservationFinding(value: unknown): Finding | null;

package/dist/core/projectDnaOutcomeExperience.js

@@ -0,0 +1,271 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { findingId } from "./ids.js";
+import { PROJECT_DNA_CATEGORIES, } from "./projectDna.js";
+import { FindingSchema, isCredentialFreeText } from "./types.js";
+export const PROJECT_DNA_USEFULNESS_OBSERVATION_SCHEMA_VERSION = "hunch.project-dna-usefulness-observation/1";
+export const PROJECT_DNA_USEFULNESS_SIGNALS = [
+    "used",
+    "prevented",
+    "near_miss",
+    "contradicted",
+    "stale",
+    "unused",
+    "unknown",
+];
+export const PROJECT_DNA_USEFULNESS_EVIDENCE_KINDS = [
+    "explicit_human_observation",
+    "independent_review",
+];
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const GIT_OBJECT = /^[a-f0-9]{40,64}$/;
+const RECEIPT_REF = /^hunch-memory:hmctx_[a-f0-9]{32}$/;
+const REPOSITORY_ID = /^pdnar_[a-f0-9]{24}$/;
+const PROFILE_ID = /^pdna_[a-f0-9]{24}$/;
+const TRAIT_ID = /^pdnat_[a-f0-9]{20}$/;
+const OBSERVATION_ID = /^pduo_[a-f0-9]{24}$/;
+const MAX_RETENTION_MS = 365 * 24 * 60 * 60 * 1_000;
+const ProjectDnaUsefulnessEvidenceSchema = z.object({
+    kind: z.enum(PROJECT_DNA_USEFULNESS_EVIDENCE_KINDS),
+    ref: z.string().min(1).max(512),
+    hash: z.string().regex(SHA256),
+}).strict();
+export const ProjectDnaUsefulnessObservationSchema = z.object({
+    schema: z.literal(PROJECT_DNA_USEFULNESS_OBSERVATION_SCHEMA_VERSION),
+    observationId: z.string().regex(OBSERVATION_ID),
+    episode: z.object({
+        provider: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
+        schemaVersion: z.string().min(3).max(128),
+        episodeId: z.string().min(3).max(256),
+        episodeHash: z.string().regex(SHA256),
+        terminalAt: z.string().min(1).max(64),
+        result: z.enum(["pass", "fail", "uncertain", "abandoned", "rolled_back"]),
+    }).strict(),
+    delivery: z.object({
+        receiptRef: z.string().regex(RECEIPT_REF),
+        receiptHash: z.string().regex(SHA256),
+        repositoryId: z.string().regex(REPOSITORY_ID),
+        repositoryRevision: z.string().regex(GIT_OBJECT),
+        profileId: z.string().regex(PROFILE_ID),
+        profileContentHash: z.string().regex(SHA256),
+        snapshotHash: z.string().regex(SHA256),
+        retrievalHash: z.string().regex(SHA256),
+    }).strict(),
+    projection: z.object({
+        role: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
+        categories: z.array(z.enum(PROJECT_DNA_CATEGORIES)).min(1).max(PROJECT_DNA_CATEGORIES.length),
+        traitIds: z.array(z.string().regex(TRAIT_ID)).min(1).max(64),
+        evidenceHashes: z.array(z.string().regex(SHA256)).min(1).max(512),
+    }).strict(),
+    artifact: z.object({
+        kind: z.enum(["commit", "pull_request", "issue", "message"]),
+        ref: z.string().min(3).max(512),
+        contentHash: z.string().regex(SHA256),
+    }).strict(),
+    assessment: z.object({
+        schemaVersion: z.string().min(3).max(128),
+        assessmentId: z.string().min(3).max(128),
+        contentHash: z.string().regex(SHA256),
+        projectMatchClassification: z.enum(["unassessable", "conformant", "mixed", "nonconformant"]),
+        causalInterpretation: z.literal("project_match_is_non_causal"),
+    }).strict(),
+    signal: z.enum(PROJECT_DNA_USEFULNESS_SIGNALS),
+    evidence: z.array(ProjectDnaUsefulnessEvidenceSchema).max(64),
+    observedAt: z.string().min(1).max(64),
+    retainUntil: z.string().min(1).max(64),
+    privacy: z.object({
+        payloadMode: z.literal("references_hashes_only"),
+        rawArtifactIncluded: z.literal(false),
+        rawFeedbackIncluded: z.literal(false),
+        rawProfileIncluded: z.literal(false),
+    }).strict(),
+    authority: z.object({
+        behavioralEffect: z.literal("none"),
+        mayChangeRanking: z.literal(false),
+        mayPromoteKnowledge: z.literal(false),
+        mayGrantAuthority: z.literal(false),
+    }).strict(),
+    contentHash: z.string().regex(SHA256),
+}).strict().superRefine((observation, ctx) => {
+    for (const [path, value] of [
+        [["episode", "terminalAt"], observation.episode.terminalAt],
+        [["observedAt"], observation.observedAt],
+        [["retainUntil"], observation.retainUntil],
+    ]) {
+        if (!Number.isFinite(Date.parse(value)) || new Date(value).toISOString() !== value) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [...path], message: "Project DNA usefulness timestamp is invalid" });
+        }
+    }
+    const observedAt = Date.parse(observation.observedAt);
+    const terminalAt = Date.parse(observation.episode.terminalAt);
+    const retainUntil = Date.parse(observation.retainUntil);
+    if (Number.isFinite(observedAt) && Number.isFinite(terminalAt) && observedAt < terminalAt) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["observedAt"], message: "Project DNA usefulness cannot precede the terminal outcome" });
+    }
+    if (Number.isFinite(observedAt) && Number.isFinite(retainUntil)
+        && (retainUntil <= observedAt || retainUntil - observedAt > MAX_RETENTION_MS)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["retainUntil"], message: "Project DNA usefulness retention is invalid" });
+    }
+    if (observation.signal !== "unknown" && observation.evidence.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["evidence"],
+            message: "classified Project DNA usefulness requires explicit human or independent review evidence",
+        });
+    }
+    const identities = new Set();
+    for (const [index, evidence] of observation.evidence.entries()) {
+        const identity = `${evidence.kind}:${evidence.ref}:${evidence.hash}`;
+        if (identities.has(identity)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["evidence", index], message: "Project DNA usefulness evidence is duplicated" });
+        }
+        identities.add(identity);
+        if (!isCredentialFreeText(evidence.ref)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["evidence", index, "ref"], message: "Project DNA usefulness evidence contains credential material" });
+        }
+    }
+    const categories = observation.projection.categories;
+    if (new Set(categories).size !== categories.length
+        || new Set(observation.projection.traitIds).size !== observation.projection.traitIds.length
+        || new Set(observation.projection.evidenceHashes).size !== observation.projection.evidenceHashes.length) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["projection"], message: "Project DNA usefulness projection contains duplicates" });
+    }
+    for (const [path, value] of [
+        [["episode", "schemaVersion"], observation.episode.schemaVersion],
+        [["episode", "episodeId"], observation.episode.episodeId],
+        [["projection", "role"], observation.projection.role],
+        [["artifact", "ref"], observation.artifact.ref],
+        [["assessment", "schemaVersion"], observation.assessment.schemaVersion],
+        [["assessment", "assessmentId"], observation.assessment.assessmentId],
+    ]) {
+        if (!isCredentialFreeText(value)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [...path], message: "Project DNA usefulness identity contains credential material" });
+        }
+    }
+    const unsigned = projectDnaUsefulnessUnsigned(observation);
+    if (observation.contentHash !== projectDnaUsefulnessHash(unsigned)
+        || observation.observationId !== projectDnaUsefulnessObservationId(observation)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Project DNA usefulness observation seal is invalid" });
+    }
+});
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+            .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function projectDnaUsefulnessHash(value) {
+    return `sha256:${createHash("sha256").update(canonicalJson(value), "utf8").digest("hex")}`;
+}
+function projectDnaUsefulnessObservationId(observation) {
+    const identityHash = projectDnaUsefulnessHash({
+        episodeId: observation.episode.episodeId,
+        receiptRef: observation.delivery.receiptRef,
+        receiptHash: observation.delivery.receiptHash,
+        profileId: observation.delivery.profileId,
+        artifactRef: observation.artifact.ref,
+        artifactContentHash: observation.artifact.contentHash,
+    });
+    return `pduo_${identityHash.slice(7, 31)}`;
+}
+function projectDnaUsefulnessUnsigned(observation) {
+    return {
+        schema: observation.schema,
+        episode: { ...observation.episode },
+        delivery: { ...observation.delivery },
+        projection: {
+            role: observation.projection.role,
+            categories: [...observation.projection.categories],
+            traitIds: [...observation.projection.traitIds],
+            evidenceHashes: [...observation.projection.evidenceHashes],
+        },
+        artifact: { ...observation.artifact },
+        assessment: { ...observation.assessment },
+        signal: observation.signal,
+        evidence: observation.evidence.map((item) => ({ ...item })),
+        observedAt: observation.observedAt,
+        retainUntil: observation.retainUntil,
+        privacy: { ...observation.privacy },
+        authority: { ...observation.authority },
+    };
+}
+export function createProjectDnaUsefulnessObservation(input) {
+    const unsigned = projectDnaUsefulnessUnsigned({
+        schema: PROJECT_DNA_USEFULNESS_OBSERVATION_SCHEMA_VERSION,
+        episode: { ...input.episode },
+        delivery: { ...input.delivery },
+        projection: {
+            role: input.projection.role,
+            categories: [...input.projection.categories],
+            traitIds: [...input.projection.traitIds],
+            evidenceHashes: [...input.projection.evidenceHashes],
+        },
+        artifact: { ...input.artifact },
+        assessment: { ...input.assessment },
+        signal: input.signal,
+        evidence: input.evidence.map((item) => ({ ...item })),
+        observedAt: input.observedAt,
+        retainUntil: input.retainUntil,
+        privacy: { ...input.privacy },
+        authority: {
+            behavioralEffect: "none",
+            mayChangeRanking: false,
+            mayPromoteKnowledge: false,
+            mayGrantAuthority: false,
+        },
+    });
+    return ProjectDnaUsefulnessObservationSchema.parse({
+        ...unsigned,
+        observationId: projectDnaUsefulnessObservationId(unsigned),
+        contentHash: projectDnaUsefulnessHash(unsigned),
+    });
+}
+export function assertProjectDnaUsefulnessObservation(value) {
+    ProjectDnaUsefulnessObservationSchema.parse(value);
+}
+/** Contradiction and staleness create review work, never a profile mutation or policy. */
+export function projectDnaUsefulnessObservationFinding(value) {
+    const observation = ProjectDnaUsefulnessObservationSchema.parse(value);
+    if (observation.signal !== "contradicted" && observation.signal !== "stale")
+        return null;
+    const title = `Project DNA outcome ${observation.signal}: ${observation.delivery.profileId}`;
+    const evidence = [
+        `project-dna-usefulness:${observation.observationId}`,
+        `project-dna-usefulness-content:${observation.contentHash}`,
+        `episode:${observation.episode.episodeId}@${observation.episode.episodeHash}`,
+        `delivery:${observation.delivery.receiptRef}@${observation.delivery.receiptHash}`,
+        `profile:${observation.delivery.profileId}@${observation.delivery.profileContentHash}`,
+        `artifact:${observation.artifact.ref}@${observation.artifact.contentHash}`,
+        `assessment:${observation.assessment.assessmentId}@${observation.assessment.contentHash}`,
+        ...observation.evidence.map((item) => `${item.kind}:${item.ref}@${item.hash}`),
+    ];
+    return FindingSchema.parse({
+        id: findingId(title),
+        title,
+        observation: observation.signal === "contradicted"
+            ? `Explicit outcome evidence may conflict with delivered Project DNA profile ${observation.delivery.profileId}; review the named traits and evidence before changing the profile.`
+            : `Explicit outcome evidence may show that delivered Project DNA profile ${observation.delivery.profileId} was stale; review currentness before changing the profile.`,
+        evidence,
+        method: null,
+        severity: observation.signal === "contradicted" ? "high" : "medium",
+        triage: "open",
+        affected_files: [],
+        affected_symbols: [...observation.projection.traitIds],
+        violates_constraint: null,
+        spawned_decision: null,
+        observed_at: observation.observedAt,
+        resolved_commit: null,
+        provenance: {
+            source: "project_dna_outcome_experience+candidate",
+            confidence: 0.75,
+            evidence,
+            last_verified: observation.observedAt,
+        },
+    });
+}
+//# sourceMappingURL=projectDnaOutcomeExperience.js.map

package/dist/projectDna.d.ts

@@ -8,3 +8,4 @@ export { PROJECT_DNA_CATEGORIES, PROJECT_DNA_MATCH_SCHEMA_VERSION, PROJECT_DNA_S
 export { PROJECT_DNA_HOST_EVIDENCE_AUTHOR_ROLES, PROJECT_DNA_HOST_EVIDENCE_DISPOSITIONS, PROJECT_DNA_HOST_EVIDENCE_KINDS, PROJECT_DNA_HOST_EVIDENCE_SCHEMA_VERSION, assertProjectDnaHostEvidence, sealProjectDnaHostEvidence, type ProjectDnaHostEvidence, type ProjectDnaHostEvidenceAuthorRole, type ProjectDnaHostEvidenceCandidate, type ProjectDnaHostEvidenceDisposition, type ProjectDnaHostEvidenceItem, type ProjectDnaHostEvidenceKind, } from "./core/projectDnaHostEvidence.js";
 export { PROJECT_DNA_DELTA_SCHEMA_VERSION, assertProjectDnaDelta, diffProjectDna, type ProjectDnaChangeKind, type ProjectDnaDelta, type ProjectDnaTraitChange, } from "./core/projectDnaDelta.js";
 export { PROJECT_DNA_SUPPLEMENT_KIND, projectDnaDeliverySupplement, type ProjectDnaDeliverySupplement, } from "./core/projectDnaDelivery.js";
+export { PROJECT_DNA_USEFULNESS_EVIDENCE_KINDS, PROJECT_DNA_USEFULNESS_OBSERVATION_SCHEMA_VERSION, PROJECT_DNA_USEFULNESS_SIGNALS, ProjectDnaUsefulnessObservationSchema, assertProjectDnaUsefulnessObservation, createProjectDnaUsefulnessObservation, projectDnaUsefulnessObservationFinding, type CreateProjectDnaUsefulnessObservationInput, type ProjectDnaUsefulnessObservation, } from "./core/projectDnaOutcomeExperience.js";

package/dist/projectDna.js

@@ -8,4 +8,5 @@ export { PROJECT_DNA_CATEGORIES, PROJECT_DNA_MATCH_SCHEMA_VERSION, PROJECT_DNA_S
 export { PROJECT_DNA_HOST_EVIDENCE_AUTHOR_ROLES, PROJECT_DNA_HOST_EVIDENCE_DISPOSITIONS, PROJECT_DNA_HOST_EVIDENCE_KINDS, PROJECT_DNA_HOST_EVIDENCE_SCHEMA_VERSION, assertProjectDnaHostEvidence, sealProjectDnaHostEvidence, } from "./core/projectDnaHostEvidence.js";
 export { PROJECT_DNA_DELTA_SCHEMA_VERSION, assertProjectDnaDelta, diffProjectDna, } from "./core/projectDnaDelta.js";
 export { PROJECT_DNA_SUPPLEMENT_KIND, projectDnaDeliverySupplement, } from "./core/projectDnaDelivery.js";
+export { PROJECT_DNA_USEFULNESS_EVIDENCE_KINDS, PROJECT_DNA_USEFULNESS_OBSERVATION_SCHEMA_VERSION, PROJECT_DNA_USEFULNESS_SIGNALS, ProjectDnaUsefulnessObservationSchema, assertProjectDnaUsefulnessObservation, createProjectDnaUsefulnessObservation, projectDnaUsefulnessObservationFinding, } from "./core/projectDnaOutcomeExperience.js";
 //# sourceMappingURL=projectDna.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.22.2",
+  "version": "1.22.3",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://hunch-pi.vercel.app",
-  "version": "1.22.2",
+  "version": "1.22.3",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.22.2",
+      "version": "1.22.3",
       "runtimeHint": "npx",
       "packageArguments": [
         {