@inneranimalmedia/agentsam-sdk 2.4.1 → 2.5.0

package/skills/agentsam-progression-guard/references/hooks-operational-io.md

@@ -0,0 +1,96 @@
+# Hooks and Operational I/O
+
+## A hook is a boundary-triggered program
+
+Examples include Git hooks, CI jobs, deploy hooks, webhooks, queue consumers,
+scheduled tasks, post-migration checks, and runtime alerts. The triggering mechanism
+changes; the engineering questions do not.
+
+A reliable hook has explicit input, authority, output, and failure behavior.
+
+## Hook contract
+
+```text
+name:
+event:
+scope:
+input refs:
+handler:
+reads:
+writes/side effects:
+credential(s) + scopes:
+timeout:
+retry/backoff:
+idempotency key:
+output/receipt:
+on failure:
+owner:
+```
+
+### Input
+
+Prefer immutable or content-addressed references where possible: Git SHA, Merkle root,
+deployment ID, schema version, artifact digest, event ID. Do not make the handler infer
+which candidate it should operate on from mutable ambient state.
+
+### Authority
+
+Give the hook only the credential scopes it needs. A test job should not hold a
+production deploy token. A postdeploy health checker should not need database-admin
+credentials just to call a public health path.
+
+### Output
+
+Emit bounded structured evidence: status, timing, affected resource IDs, hashes,
+versions, and sanitized error categories. Never emit raw secrets, access tokens, full
+request headers, or unbounded logs into a receipt.
+
+### Failure
+
+Choose deliberately:
+
+- `warn`: record but do not block;
+- `block`: candidate cannot advance;
+- `rollback`: revert/disable when rollback is proven safe;
+- `quarantine`: keep the candidate deployed but unavailable while investigation runs.
+
+Do not default every hook to "retry forever." Retries need a bounded count/window and
+idempotency semantics for side effects.
+
+## Ingress versus egress hooks
+
+**Ingress** receives something from outside: HTTP request, webhook, auth callback,
+queue event. Validate identity/signature/schema before trusted business logic.
+
+**Egress** sends something outward: API call, deploy, notification, database write.
+Validate destination identity/allowlist, credential scope, request contract, timeout,
+and retry/idempotency behavior.
+
+This makes operational I/O inspectable as edges in the same graph as code imports.
+
+## Deploy hook composition
+
+A robust deploy wrapper behaves like:
+
+```text
+predeploy
+  inspect/security/build/tests
+  capture evidence
+
+provider deploy
+  capture deployment/version ID
+
+postdeploy
+  smoke critical routes/contracts
+  inspect metrics if available
+
+promote
+  success receipt only if postdeploy is green
+
+failure
+  failure receipt
+  rollback/disable/quarantine according to project policy
+```
+
+Do not hide this behind one opaque shell string when individual steps need different
+failure semantics or receipts.

package/skills/catalog.json

@@ -0,0 +1,53 @@
+{
+  "schema_version": 1,
+  "skills": [
+    {
+      "id": "agentsam-jr-dev",
+      "aliases": [
+        "agentsam_jr_dev",
+        "jr-dev"
+      ],
+      "title": "AgentSam Jr Dev",
+      "description": "Teach, inspect, build, and revise real software using beginner-friendly language grounded in repository and runtime evidence.",
+      "entry": "agentsam-jr-dev/SKILL.md",
+      "references": [
+        "agentsam-jr-dev/references/web-application-fundamentals.md",
+        "agentsam-jr-dev/references/real-application-logic.md"
+      ],
+      "user_invocable": true
+    },
+    {
+      "id": "agentsam-app-fundamentals",
+      "aliases": [
+        "app-fundamentals",
+        "application-fundamentals",
+        "quick-bytes"
+      ],
+      "title": "AgentSam Application Fundamentals",
+      "description": "Build and review applications using explicit execution ownership, contracts, credentialed destinations, dependency graphs, AST evidence, and Merkle evidence.",
+      "entry": "agentsam-app-fundamentals/SKILL.md",
+      "references": [
+        "agentsam-app-fundamentals/references/trust-credentials-and-destinations.md",
+        "agentsam-app-fundamentals/references/graphs-contracts-ast-merkle.md"
+      ],
+      "user_invocable": true
+    },
+    {
+      "id": "agentsam-progression-guard",
+      "aliases": [
+        "progression-guard",
+        "no-regress",
+        "ship-guard",
+        "release-guard"
+      ],
+      "title": "AgentSam Progression Guard",
+      "description": "Prevent silent regression with explicit local, CI, predeploy, deploy, postdeploy, promotion, and runtime evidence gates.",
+      "entry": "agentsam-progression-guard/SKILL.md",
+      "references": [
+        "agentsam-progression-guard/references/checkpoint-chain.md",
+        "agentsam-progression-guard/references/hooks-operational-io.md"
+      ],
+      "user_invocable": true
+    }
+  ]
+}

package/src/capabilities/index.js

@@ -5,3 +5,10 @@ export {
   listCapabilities,
 } from './manifest.js';
 export { repositorySnapshot } from './repository-snapshot.js';
+export {
+  REPOSITORY_SNAPSHOT_VIEWS,
+  buildRepositorySnapshotFacets,
+  normalizeRepositorySnapshotFilters,
+  projectRepositorySnapshot,
+  repositoryFileMatches,
+} from './repository-snapshot-view.js';

package/src/capabilities/repository-snapshot-view.js

@@ -0,0 +1,238 @@
+import { createHash } from 'node:crypto';
+
+const VIEW_NAMES = new Set(['index', 'files', 'full']);
+const FILTER_FIELDS = Object.freeze([
+  'system', 'package', 'category', 'layer', 'kind', 'language', 'role', 'execution_domain', 'tag', 'path', 'symbol', 'import', 'match',
+]);
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 500;
+const DEFAULT_FACET_LIMIT = 48;
+const MAX_FACET_LIMIT = 200;
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(JSON.stringify(value)).digest('hex')}`;
+}
+
+function values(input) {
+  if (input == null) return [];
+  const raw = Array.isArray(input) ? input : [input];
+  return [...new Set(raw.map(clean).filter(Boolean))];
+}
+
+function boundedInt(value, fallback, max) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 1) return fallback;
+  return Math.min(max, number);
+}
+
+function globRegex(glob) {
+  const input = clean(glob).replace(/^\.\//, '');
+  let source = '^';
+  for (let i = 0; i < input.length; i += 1) {
+    const char = input[i];
+    if (char === '*') {
+      if (input[i + 1] === '*') { source += '.*'; i += 1; }
+      else source += '[^/]*';
+    } else if (char === '?') source += '[^/]';
+    else source += /[\\^$.*+?()[\]{}|]/.test(char) ? `\\${char}` : char;
+  }
+  return new RegExp(`${source}$`, 'i');
+}
+
+function pathMatches(path, selectors) {
+  if (!selectors.length) return true;
+  const candidate = clean(path).replace(/^\.\//, '');
+  return selectors.some((selector) => {
+    const normalized = selector.replace(/^\.\//, '');
+    if (normalized.includes('*') || normalized.includes('?')) return globRegex(normalized).test(candidate);
+    return candidate === normalized || candidate.startsWith(`${normalized.replace(/\/$/, '')}/`);
+  });
+}
+
+function scalarMatches(value, selectors) {
+  if (!selectors.length) return true;
+  const candidate = clean(value).toLowerCase();
+  return selectors.some((selector) => candidate === selector.toLowerCase());
+}
+
+function listMatches(list, selectors) {
+  if (!selectors.length) return true;
+  const set = new Set((Array.isArray(list) ? list : []).map((value) => clean(value).toLowerCase()));
+  return selectors.some((selector) => set.has(selector.toLowerCase()));
+}
+
+function lexicalMatches(entry, terms) {
+  if (!terms.length) return true;
+  const haystack = [
+    entry.path, entry.system, entry.package, entry.category, entry.layer, entry.kind, entry.language, entry.role, entry.execution_domain,
+    ...(entry.tags || []), ...(entry.symbols || []), ...(entry.imports || []),
+  ].map(clean).join('\n').toLowerCase();
+  return terms.every((term) => haystack.includes(term.toLowerCase()));
+}
+
+export function normalizeRepositorySnapshotFilters(input = {}) {
+  return Object.fromEntries(FILTER_FIELDS.map((field) => [field, values(input[field])]).filter(([, list]) => list.length));
+}
+
+export function repositoryFileMatches(entry, filters = {}) {
+  const f = normalizeRepositorySnapshotFilters(filters);
+  return scalarMatches(entry.system, f.system || [])
+    && scalarMatches(entry.package, f.package || [])
+    && scalarMatches(entry.category, f.category || [])
+    && scalarMatches(entry.layer, f.layer || [])
+    && scalarMatches(entry.kind, f.kind || [])
+    && scalarMatches(entry.language, f.language || [])
+    && scalarMatches(entry.role, f.role || [])
+    && scalarMatches(entry.execution_domain, f.execution_domain || [])
+    && listMatches(entry.tags, f.tag || [])
+    && pathMatches(entry.path, f.path || [])
+    && listMatches(entry.symbols, f.symbol || [])
+    && listMatches(entry.imports, f.import || [])
+    && lexicalMatches(entry, f.match || []);
+}
+
+function countFacet(entries, getter, limit) {
+  const counts = new Map();
+  for (const entry of entries) {
+    for (const raw of getter(entry)) {
+      const value = clean(raw);
+      if (!value) continue;
+      counts.set(value, (counts.get(value) || 0) + 1);
+    }
+  }
+  return [...counts.entries()]
+    .map(([value, count]) => ({ value, count }))
+    .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value))
+    .slice(0, limit);
+}
+
+export function buildRepositorySnapshotFacets(entries = [], { limit = DEFAULT_FACET_LIMIT } = {}) {
+  const bounded = boundedInt(limit, DEFAULT_FACET_LIMIT, MAX_FACET_LIMIT);
+  const scalar = (field) => (entry) => entry[field] == null ? [] : [entry[field]];
+  return {
+    systems: countFacet(entries, scalar('system'), bounded),
+    packages: countFacet(entries, scalar('package'), bounded),
+    layers: countFacet(entries, scalar('layer'), bounded),
+    roles: countFacet(entries, scalar('role'), bounded),
+    execution_domains: countFacet(entries, scalar('execution_domain'), bounded),
+    kinds: countFacet(entries, scalar('kind'), bounded),
+    languages: countFacet(entries, scalar('language'), bounded),
+    tags: countFacet(entries, (entry) => entry.tags || [], bounded),
+    categories: countFacet(entries, scalar('category'), bounded),
+  };
+}
+
+function compactEntry(entry) {
+  return {
+    path: entry.path,
+    ...(entry.package ? { package: entry.package } : {}),
+    ...(entry.package_root ? { package_root: entry.package_root } : {}),
+    ...(entry.system ? { system: entry.system } : {}),
+    ...(entry.category ? { category: entry.category } : {}),
+    ...(entry.layer ? { layer: entry.layer } : {}),
+    ...(entry.kind ? { kind: entry.kind } : {}),
+    ...(entry.language ? { language: entry.language } : {}),
+    ...(entry.role ? { role: entry.role } : {}),
+    ...(entry.execution_domain ? { execution_domain: entry.execution_domain } : {}),
+    ...(entry.tags?.length ? { tags: entry.tags } : {}),
+    ...(entry.symbols?.length ? { symbols: entry.symbols } : {}),
+    ...(entry.imports?.length ? { imports: entry.imports } : {}),
+  };
+}
+
+function compactTrustBoundary(analysis, limit = 20) {
+  const source = analysis?.trust_boundary;
+  if (!source) return undefined;
+  const findings = Array.isArray(source.findings) ? source.findings : [];
+  return {
+    trust_boundary: {
+      schema_version: source.schema_version,
+      analyzer: source.analyzer,
+      metadata_root: source.metadata_root,
+      complete: source.complete,
+      status: source.status,
+      ok: source.ok,
+      browser_roots: source.browser_roots,
+      browser_reachable_files: source.browser_reachable_files,
+      ast_files: source.ast_files,
+      finding_count: findings.length,
+      findings_returned: Math.min(findings.length, limit),
+      findings_truncated: findings.length > limit,
+      findings: findings.slice(0, limit).map((item) => ({
+        kind: item.kind,
+        severity: item.severity,
+        source: item.source,
+        ...(item.target ? { target: item.target } : {}),
+        ...(item.specifier ? { specifier: item.specifier } : {}),
+        ...(item.env ? { env: item.env } : {}),
+        ...(item.repair?.action ? { repair_action: item.repair.action } : {}),
+      })),
+    },
+  };
+}
+
+function projectionBase(snapshot) {
+  return {
+    schema_version: snapshot.schema_version,
+    capability: snapshot.capability,
+    snapshot_id: snapshot.snapshot_id,
+    created_at: snapshot.created_at,
+    content_hash: snapshot.content_hash,
+    repository: snapshot.repository,
+    tree: {
+      merkle_root: snapshot.tree?.merkle_root || null,
+      metadata_root: snapshot.tree?.metadata_root || null,
+      manifest: snapshot.tree?.manifest || null,
+      classifier: snapshot.tree?.classifier || null,
+      stats: snapshot.tree?.stats || null,
+      semantic_stats: snapshot.tree?.semantic_stats || null,
+    },
+    ...(compactTrustBoundary(snapshot.analysis) ? { analysis: compactTrustBoundary(snapshot.analysis) } : {}),
+  };
+}
+
+/**
+ * Produce a bounded, deterministic view over a canonical repository.snapshot.
+ * The canonical content_hash / Merkle identities are carried through unchanged;
+ * projection_hash identifies only this derived view and is never an authority root.
+ */
+export function projectRepositorySnapshot(snapshot, options = {}) {
+  if (!snapshot || snapshot.capability !== 'repository.snapshot' || !snapshot.tree) {
+    throw new Error('repository_snapshot_required');
+  }
+  const view = clean(options.view || 'index').toLowerCase();
+  if (!VIEW_NAMES.has(view)) throw new Error(`repository_snapshot_view_invalid:${view}`);
+  if (view === 'full') return snapshot;
+
+  const files = Array.isArray(snapshot.tree.files) ? snapshot.tree.files : [];
+  const filters = normalizeRepositorySnapshotFilters(options.filters || options);
+  const filtered = files.filter((entry) => repositoryFileMatches(entry, filters));
+  const limit = boundedInt(options.limit, DEFAULT_LIMIT, MAX_LIMIT);
+  const facetLimit = boundedInt(options.facetLimit ?? options.facet_limit, DEFAULT_FACET_LIMIT, MAX_FACET_LIMIT);
+  const base = projectionBase(snapshot);
+  const result = {
+    ...base,
+    projection: {
+      format: 'agentsam-repository-view',
+      version: 1,
+      view,
+      source_snapshot_id: snapshot.snapshot_id,
+      source_content_hash: snapshot.content_hash,
+      filters,
+      matched: filtered.length,
+      returned: view === 'files' ? Math.min(filtered.length, limit) : 0,
+      truncated: view === 'files' && filtered.length > limit,
+      limit: view === 'files' ? limit : 0,
+    },
+    facets: buildRepositorySnapshotFacets(filtered, { limit: facetLimit }),
+    ...(view === 'files' ? { files: filtered.slice(0, limit).map(compactEntry) } : {}),
+  };
+  result.projection.projection_hash = sha256({ ...result, projection: { ...result.projection, projection_hash: undefined } });
+  return result;
+}
+
+export const REPOSITORY_SNAPSHOT_VIEWS = Object.freeze([...VIEW_NAMES]);

package/src/capabilities/repository-snapshot.js

@@ -5,7 +5,10 @@ import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
 import { resolveGitContext } from '../lib/git-context.js';
+import { getRepositoryId, tryReadProjectConfig } from '../lib/project-config.js';
 import { buildMerkleTree } from '../lib/merkle/index.js';
+import { gitIgnoredPaths } from '../lib/merkle/git-ignore.js';
+import { analyzeExecutionBoundaries } from '../indexing/execution-boundary.js';
 import { showLatestDeployReceipt } from '../lib/deploy-receipt/index.js';
 import { CONFIG_PATH, canonical, readConfig, scopeKey } from '../knowledge/config.js';
 import { openSqliteStore } from '../knowledge/stores/sqlite.js';
@@ -24,16 +27,6 @@ function providerForHost(host) {
   return value ? 'git' : null;
 }
 
-async function gitIgnoredPaths(root) {
-  const result = await execute('git', ['status', '--porcelain=v1', '--ignored=matching'], {
-    cwd: root,
-    maxBuffer: 16 * 1024 * 1024,
-  });
-  return [...new Set(result.stdout.split('\n')
-    .filter((line) => line.startsWith('!! '))
-    .map((line) => line.slice(3).trim().replace(/\/$/, ''))
-    .filter((value) => value && !value.includes('\\') && !value.split('/').includes('..')))];
-}
 
 async function runRepositoryIntelligence(root, churnDays) {
   const pythonRoot = fileURLToPath(new URL('../../python', import.meta.url));
@@ -121,21 +114,29 @@ export async function repositorySnapshot({ cwd = process.cwd(), churnDays = 30 }
   const git = resolveGitContext({ cwd });
   const root = git.root;
   const ignored = await gitIgnoredPaths(root);
+  const projectConfig = tryReadProjectConfig(root);
   const [intelligence, merkle, knowledge, deployReceipt] = await Promise.all([
     runRepositoryIntelligence(root, churnDays),
-    buildMerkleTree(root, { exclude: ignored }),
+    buildMerkleTree(root, { exclude: ignored, semantic: true }),
     readKnowledgeState(root),
     showLatestDeployReceipt({ root }),
   ]);
   const provider = providerForHost(git.remoteHost);
-  const portableRepositoryId = provider && git.repoFullName ? `${provider}:${git.repoFullName}` : null;
-  const repositoryId = knowledge.repository_id || portableRepositoryId;
+  const portableRepositoryId = provider && git.repoFullName
+    ? `${provider}:${provider === 'github' ? git.repoFullName.toLowerCase() : git.repoFullName}`
+    : null;
+  const projectRepositoryId = getRepositoryId(projectConfig);
+  if (projectRepositoryId && knowledge.repository_id && projectRepositoryId !== knowledge.repository_id) {
+    throw new Error(`repository_identity_mismatch: project=${projectRepositoryId} knowledge=${knowledge.repository_id}`);
+  }
+  const repositoryId = projectRepositoryId || knowledge.repository_id || portableRepositoryId;
   const packages = readPackageInventory(root, intelligence.manifests || []);
+  const trustBoundary = analyzeExecutionBoundaries(merkle.semantic);
 
   const evidence = {
     repository: {
       repository_id: repositoryId,
-      identity_source: knowledge.repository_id ? 'knowledge-config' : portableRepositoryId ? 'git-remote' : 'unresolved',
+      identity_source: projectRepositoryId ? 'project-config' : knowledge.repository_id ? 'knowledge-config' : portableRepositoryId ? 'git-remote' : 'unresolved',
       provider,
       full_name: git.repoFullName,
       remote_url: git.remoteUrl || null,
@@ -145,10 +146,20 @@ export async function repositorySnapshot({ cwd = process.cwd(), churnDays = 30 }
     },
     tree: {
       merkle_root: merkle.rootHash,
+      metadata_root: merkle.semantic.rootHash,
+      manifest: {
+        format: merkle.format,
+        version: merkle.version,
+        hash_algorithm: merkle.algorithm,
+        policy_hash: merkle.policyHash,
+      },
+      classifier: merkle.semantic.classifier,
       stats: merkle.stats,
+      semantic_stats: merkle.semantic.stats,
       paths: merkle.entries
         .filter((entry) => entry.type === 'file' || entry.type === 'symlink')
         .map((entry) => entry.path),
+      files: merkle.semantic.entries,
     },
     intelligence: {
       summary: intelligence.summary,
@@ -159,6 +170,9 @@ export async function repositorySnapshot({ cwd = process.cwd(), churnDays = 30 }
     },
     packages,
     knowledge,
+    analysis: {
+      trust_boundary: trustBoundary,
+    },
     deploy: deployReceipt ? {
       status: deployReceipt.status,
       root_hash: deployReceipt.root_hash,