@kal-elsam/kairo-runtime 0.1.0

package/repo-template/docs/skills/ui-design.md

@@ -0,0 +1,37 @@
+# UI Design
+
+## Cuándo usar
+
+Creación o modificación de UI.
+
+## Fuente de verdad
+
+`docs/ai/ui.md`
+
+## Procedimiento
+
+1. Leer fuente de verdad.
+2. Identificar alcance.
+3. Crear/actualizar spec si el cambio no es trivial.
+4. Crear test/eval si cambia comportamiento.
+5. Implementar solo el scope necesario.
+6. Validar pipeline.
+7. Reportar riesgos y cambios.
+
+## Checklist
+
+- [ ] Contexto mínimo leído
+- [ ] Scope claro
+- [ ] Tests/evals aplican o se justifica omisión
+- [ ] Pipeline validado
+- [ ] Riesgos reportados
+
+## Output esperado
+
+```txt
+Contexto leído:
+Cambios realizados:
+Validación:
+Riesgos:
+Siguiente acción:
+```

package/repo-template/docs/specs/README.md

@@ -0,0 +1,9 @@
+# Specs
+
+Ubicación para specs vivas.
+
+Formato:
+
+```txt
+docs/specs/<feature-name>.spec.md
+```

package/repo-template/docs/specs/templates/basic-spec.md

@@ -0,0 +1,41 @@
+# Basic Spec: [Feature or Task Name]
+
+## Spec level
+
+```txt
+basic
+```
+
+## Goal
+
+[What needs to change?]
+
+## Scope
+
+[What is included?]
+
+## Non-scope
+
+[What should not change?]
+
+## Files likely affected
+
+```txt
+- [file/module]
+```
+
+## Acceptance criteria
+
+- [ ] [Expected behavior]
+- [ ] [No regression]
+
+## Validation
+
+```txt
+Command(s):
+Manual check:
+```
+
+## Notes
+
+[Any relevant context]

package/repo-template/docs/specs/templates/complex-spec.md

@@ -0,0 +1,145 @@
+# Complex Spec: [Initiative Name]
+
+## Spec level
+
+```txt
+complex
+```
+
+## Context
+
+[Background and current state.]
+
+## Problem
+
+[What problem are we solving and why now?]
+
+## Goals
+
+- [Goal]
+
+## Non-goals
+
+- [Non-goal]
+
+## Stakeholders
+
+- User/customer:
+- Engineering:
+- Product:
+- Security/privacy:
+- Operations:
+
+## System boundaries
+
+```txt
+In scope:
+Out of scope:
+Affected systems:
+```
+
+## Current architecture
+
+[Describe current design.]
+
+## Proposed architecture
+
+[Describe proposed design.]
+
+## Alternatives considered
+
+| Option | Pros | Cons | Decision |
+|---|---|---|---|
+| [A] | | | |
+
+## ADR
+
+```txt
+ADR required: yes/no
+ADR path:
+```
+
+## Data model / contracts
+
+[DB schema, API contracts, events, external integrations.]
+
+## Failure modes
+
+| Failure mode | Detection | Mitigation |
+|---|---|---|
+| [failure] | [signal] | [action] |
+
+## Security and privacy review
+
+- [ ] Auth/authz impact reviewed
+- [ ] Secrets impact reviewed
+- [ ] PII/privacy impact reviewed
+- [ ] Tool/MCP permissions reviewed
+- [ ] Dependency trust reviewed
+
+## Test strategy
+
+- Unit:
+- Integration:
+- Contract:
+- E2E:
+- Load/performance if applicable:
+
+## Eval strategy
+
+Required if AI behavior, prompts, agents, tool calls or RAG are affected.
+
+```txt
+Eval set:
+Critical cases:
+Regression cases:
+Pass threshold:
+```
+
+## Migration plan
+
+[Steps, backwards compatibility, data safety.]
+
+## Observability
+
+[Logs, metrics, traces, dashboards, alerts.]
+
+## Rollout plan
+
+[Feature flag/canary/phased release.]
+
+## Rollback plan
+
+[Exact rollback steps.]
+
+## Risk register
+
+| Risk | Severity | Mitigation | Owner |
+|---|---|---|---|
+| [risk] | [low/med/high] | [mitigation] | [owner] |
+
+## Human approvals
+
+- [ ] Architecture
+- [ ] Security
+- [ ] Data
+- [ ] Product
+- [ ] Operations
+
+## Acceptance criteria
+
+- [ ] [Criterion]
+
+## Implementation phases
+
+### Phase 1
+
+- [ ] [Task]
+
+### Phase 2
+
+- [ ] [Task]
+
+### Phase 3
+
+- [ ] [Task]

package/repo-template/docs/specs/templates/standard-spec.md

@@ -0,0 +1,58 @@
+# Standard Spec: [Feature Name]
+
+## Spec level
+
+```txt
+standard
+```
+
+## Problem
+
+[What problem are we solving?]
+
+## Goal
+
+[What should be true after this is done?]
+
+## Non-goals
+
+[What is explicitly out of scope?]
+
+## User flow / system flow
+
+[Describe the expected flow.]
+
+## Scope
+
+[What modules/components/endpoints are included?]
+
+## Technical plan
+
+1. [Step]
+2. [Step]
+3. [Step]
+
+## Acceptance criteria
+
+- [ ] [Criterion]
+- [ ] [Criterion]
+
+## Test plan
+
+- Unit:
+- Integration:
+- E2E/manual:
+
+## Risks
+
+| Risk | Mitigation |
+|---|---|
+| [risk] | [mitigation] |
+
+## Rollback
+
+[How can this be reverted safely?]
+
+## Open questions
+
+- [Question]

package/repo-template/evals/README.md

@@ -0,0 +1,11 @@
+# Evals
+
+Ubicación para evals de IA, agentes, prompts, tool calling, RAG y flujos conversacionales.
+
+```txt
+evals/
+├── golden-datasets/
+├── prompt-regression/
+├── tool-calling/
+└── conversation-flows/
+```

package/repo-template/evals/golden/sample-golden.json

@@ -0,0 +1,12 @@
+{
+  "id": "sample-golden-001",
+  "type": "golden",
+  "severity": "critical",
+  "input": "sample",
+  "expected": {
+    "valid": true
+  },
+  "must_not": [
+    "claim success without evidence"
+  ]
+}

package/repo-template/evals/loop-regression/README.md

@@ -0,0 +1,11 @@
+# Loop Regression Evals
+
+Use this folder to test whether loops converge safely.
+
+Recommended cases:
+
+- repair loop stops after max attempts
+- loop escalates when architecture is affected
+- loop does not modify DB/auth/infra without approval
+- AI behavior loop reverts when evals degrade
+- documentation loop detects stale docs

package/repo-template/evals/regression/sample-regression.json

@@ -0,0 +1,12 @@
+{
+  "id": "sample-regression-001",
+  "type": "regression",
+  "severity": "critical",
+  "input": "sample",
+  "expected": {
+    "valid": true
+  },
+  "must_not": [
+    "claim success without evidence"
+  ]
+}

package/repo-template/evals/schema/sample-schema.json

@@ -0,0 +1,12 @@
+{
+  "id": "sample-schema-001",
+  "type": "schema",
+  "severity": "critical",
+  "input": "sample",
+  "expected": {
+    "valid": true
+  },
+  "must_not": [
+    "claim success without evidence"
+  ]
+}

package/repo-template/evals/tool-calls/sample-tool-calls.json

@@ -0,0 +1,12 @@
+{
+  "id": "sample-tool-calls-001",
+  "type": "tool-calls",
+  "severity": "critical",
+  "input": "sample",
+  "expected": {
+    "valid": true
+  },
+  "must_not": [
+    "claim success without evidence"
+  ]
+}

package/repo-template/opencode.json.sample

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "plan": {
+      "mode": "primary",
+      "permission": {
+        "edit": "deny",
+        "bash": "deny"
+      },
+      "steps": 8
+    },
+    "build": {
+      "mode": "primary",
+      "permission": {
+        "edit": "ask",
+        "bash": {
+          "*": "ask",
+          "git status *": "allow",
+          "git diff *": "allow",
+          "npm test*": "allow",
+          "pnpm test*": "allow",
+          "npm run test*": "allow",
+          "pnpm run test*": "allow"
+        }
+      },
+      "steps": 12
+    }
+  }
+}

package/repo-template/scripts/harness/backup.mjs

@@ -0,0 +1,7 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const snapshotDir = path.join('.harness', 'snapshots', new Date().toISOString().replace(/[:.]/g, '-'));
+fs.mkdirSync(snapshotDir, { recursive: true });
+const targets = ['AGENTS.md','docs','.cursor','.codex','.claude','.opencode','.github','.gentle-ai','.pi'].filter((t) => fs.existsSync(t));
+for (const target of targets) fs.cpSync(target, path.join(snapshotDir, target), { recursive: true });
+console.log(`Harness snapshot created: ${snapshotDir}`);

package/repo-template/scripts/harness/doctor.mjs

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+const required = [
+  'AGENTS.md',
+  'docs/ai/governance.md',
+  'docs/ai/adapter-parity.md',
+  'docs/ai/enforcement.md',
+  'docs/ai/quality-gates.md',
+  'docs/ai/trust-policy.md',
+  'docs/ai/eval-strategy.md',
+  'docs/skills',
+  'docs/specs',
+  'evals'
+];
+const missing = required.filter((path) => !fs.existsSync(path));
+if (missing.length) {
+  console.error('Harness doctor failed. Missing:');
+  for (const item of missing) console.error(`- ${item}`);
+  process.exit(1);
+}
+console.log('Harness doctor passed.');

package/repo-template/scripts/harness/run-evals.mjs

@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const roots = ['evals/golden','evals/tool-calls','evals/schema','evals/regression','evals/loop-regression'];
+let total = 0;
+let failed = 0;
+for (const root of roots) {
+  if (!fs.existsSync(root)) continue;
+  for (const file of fs.readdirSync(root).filter((f) => f.endsWith('.json'))) {
+    total++;
+    const full = path.join(root, file);
+    try {
+      const data = JSON.parse(fs.readFileSync(full, 'utf8'));
+      if (!data.id || !data.type || !data.severity) {
+        console.error(`Invalid eval schema: ${full}`);
+        failed++;
+      }
+    } catch {
+      console.error(`Failed to parse eval file: ${full}`);
+      failed++;
+    }
+  }
+}
+if (failed > 0) {
+  console.error(`Eval validation failed: ${failed}/${total}`);
+  process.exit(1);
+}
+console.log(`Eval validation passed: ${total} eval files checked.`);

package/repo-template/setup-agent-links.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+set -e
+
+echo "Creating agent compatibility links..."
+
+mkdir -p .claude
+if [ ! -e CLAUDE.md ]; then
+  ln -s AGENTS.md CLAUDE.md
+  echo "✓ CLAUDE.md -> AGENTS.md"
+fi
+
+if [ ! -e .claude/CLAUDE.md ]; then
+  ln -s ../AGENTS.md .claude/CLAUDE.md
+  echo "✓ .claude/CLAUDE.md -> ../AGENTS.md"
+fi
+
+if [ ! -e .windsurfrules ]; then
+  ln -s AGENTS.md .windsurfrules
+  echo "✓ .windsurfrules -> AGENTS.md"
+fi
+
+mkdir -p .agent
+if [ ! -e .agent/AGENTS.md ]; then
+  ln -s ../AGENTS.md .agent/AGENTS.md
+  echo "✓ .agent/AGENTS.md -> ../AGENTS.md"
+fi
+
+mkdir -p .github
+if [ ! -e .github/copilot-instructions.md ]; then
+  cat > .github/copilot-instructions.md <<'EOF'
+Este archivo es un puntero de compatibilidad.
+Fuente universal: `../AGENTS.md`.
+Fuente técnica: `../docs/ai/`.
+Skills operativos: `../docs/skills/`.
+EOF
+  echo "✓ .github/copilot-instructions.md"
+fi
+
+echo "Done. AGENTS.md is the universal source of truth."
+
+# Gemini
+if [ ! -e GEMINI.md ]; then
+  ln -s AGENTS.md GEMINI.md
+  echo "✓ GEMINI.md -> AGENTS.md"
+fi
+
+# Codex folder
+mkdir -p .codex
+
+# Gentle AI folder
+mkdir -p .gentle-ai
+
+# Universal parity note
+echo "Adapter parity: AGENTS.md is governance-primary. Adapters are translation layers."

package/scripts/check-published-release.mjs

@@ -0,0 +1,127 @@
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+function defaultRunGit(command) {
+  return execSync(command, { encoding: "utf8" });
+}
+
+async function defaultFetchJson(url) {
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: HTTP ${response.status}`);
+  }
+
+  return response.json();
+}
+
+export function parsePublishedReleaseArgs(argv) {
+  const args = [...argv];
+  let version = null;
+  let packageName = "@kal-elsam/kairo-runtime";
+
+  for (let index = 2; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--version") {
+      version = args[++index];
+      continue;
+    }
+
+    if (arg.startsWith("--version=")) {
+      version = arg.slice("--version=".length);
+      continue;
+    }
+
+    if (arg === "--package") {
+      packageName = args[++index];
+      continue;
+    }
+
+    if (arg.startsWith("--package=")) {
+      packageName = arg.slice("--package=".length);
+      continue;
+    }
+
+    throw new Error(`Unknown option "${arg}".`);
+  }
+
+  if (!version) {
+    throw new Error("Missing required --version <x.y.z>.");
+  }
+
+  return { version, packageName };
+}
+
+export async function verifyPublishedRelease({
+  version,
+  packageName = "@kal-elsam/kairo-runtime",
+  runGit = defaultRunGit,
+  fetchJson = defaultFetchJson
+}) {
+  const tag = `v${version}`;
+  const encodedPackage = encodeURIComponent(packageName);
+  const meta = await fetchJson(`https://registry.npmjs.org/${encodedPackage}/${version}`);
+
+  if (meta.version !== version) {
+    throw new Error(`npm version mismatch: expected ${version}, got ${meta.version ?? "none"}`);
+  }
+
+  if (!meta.gitHead) {
+    throw new Error(`npm package ${packageName}@${version} has no gitHead`);
+  }
+
+  const gitHead = meta.gitHead.trim();
+  const tagSha = runGit(`git rev-parse ${tag}^{commit}`).trim();
+
+  if (tagSha !== gitHead) {
+    throw new Error(`Local tag ${tag} (${tagSha}) does not match npm gitHead (${gitHead})`);
+  }
+
+  const mainSha = runGit("git rev-parse origin/main").trim();
+
+  if (mainSha !== gitHead) {
+    try {
+      runGit(`git merge-base --is-ancestor ${gitHead} origin/main`);
+    } catch {
+      throw new Error(
+        `origin/main (${mainSha}) does not contain npm gitHead (${gitHead})`
+      );
+    }
+  }
+
+  const remoteTagLine = runGit(`git ls-remote --tags origin refs/tags/${tag}`).trim();
+
+  if (!remoteTagLine.startsWith(gitHead)) {
+    throw new Error(`Remote tag ${tag} on origin does not point to npm gitHead (${gitHead})`);
+  }
+
+  return {
+    version,
+    packageName,
+    gitHead,
+    tag,
+    mainSha,
+    tagSha,
+    mainAhead: mainSha !== gitHead
+  };
+}
+
+function isMainModule() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  return fileURLToPath(import.meta.url) === entry;
+}
+
+if (isMainModule()) {
+  const { version, packageName } = parsePublishedReleaseArgs(process.argv);
+  const result = await verifyPublishedRelease({ version, packageName });
+
+  console.log("Published release provenance OK");
+  console.log(`Package: ${result.packageName}@${result.version}`);
+  console.log(`npm gitHead: ${result.gitHead}`);
+  console.log(`Tag: ${result.tag}`);
+  console.log(
+    `origin/main: ${result.mainSha}${result.mainAhead ? " (contains release)" : ""}`
+  );
+}

package/scripts/check-release-commit.mjs

@@ -0,0 +1,32 @@
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import {
+  parseAttributionGuardArgs,
+  runAttributionGuard
+} from "./lib/attribution-guard.mjs";
+
+export {
+  assertCleanReleaseMessage,
+  assertCleanReleaseMessages,
+  parseAttributionGuardArgs,
+  readCommitMessages,
+  runAttributionGuard
+} from "./lib/attribution-guard.mjs";
+
+function defaultRunGit(command) {
+  return execSync(command, { encoding: "utf8" });
+}
+
+function isMainModule() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  return fileURLToPath(import.meta.url) === entry;
+}
+
+if (isMainModule()) {
+  const { range } = parseAttributionGuardArgs(process.argv);
+  const result = runAttributionGuard({ range, runGit: defaultRunGit });
+  const scope = range ?? "HEAD";
+
+  console.log(`Release attribution guard OK (${result.checked} commit(s), range: ${scope})`);
+}