feat(skills): add chronomemory-esdb and github-actions-ci skills

tbitcs · oz-agent · tbitcs · commit edcd85a1f5c5 · 2026-05-19T17:43:51.000-04:00
chronomemory-esdb (governance domain):
  Full v0.1.1 API reference + 5 critical rules as an installable skill.
  Covers: imports, ChronoStore write/read, query.what_is_known, ContextPackCompiler,
  DepGraph, epistemic rollback, 10 query function signatures, token metrics,
  skills system, and RUST_BACKEND note. Activated by esdb/chronomemory/query tags.

github-actions-ci (devops domain):
  Layer1Labs CI pattern: permissions:{} at workflow level, per-job contents:read,
  all jobs parallel (no needs chain), Python 3.10-3.13 x ubuntu+windows matrix,
  --cov-fail-under=85 gate, named jobs, fail-fast:false. Includes canonical template
  and explicit 'What NOT to do' list. Rust project job templates included.

pyproject.toml: add E501 ignore for src/specsmith/skills/*.py (markdown body content)

Co-Authored-By: Oz &lt;oz-agent@warp.dev&gt;
diff --git a/pyproject.toml b/pyproject.toml
@@ -128,6 +128,8 @@ select = ["E", "F", "W", "I", "UP", "B", "SIM"]
 "src/specsmith/ci_manager.py" = ["E501"]
 # Context orchestrator: tier descriptions are intentionally descriptive
 "src/specsmith/context_orchestrator.py" = ["E501"]
+# Skills module: skill body strings contain markdown content with long lines
+"src/specsmith/skills/*.py" = ["E501"]
 # Migration files: rule description strings and template content
 "src/specsmith/migrations/m001_governance_yaml.py" = ["E501"]
 "src/specsmith/migrations/m004_ledger_esdb.py" = ["E501"]
diff --git a/src/specsmith/skills/devops.py b/src/specsmith/skills/devops.py
@@ -4,6 +4,165 @@
 from specsmith.skills import SkillDomain, SkillEntry
 
 SKILLS: list[SkillEntry] = [
+    SkillEntry(
+        slug="github-actions-ci",
+        name="GitHub Actions CI — Layer1Labs pattern (zero-trust, parallel, coverage-gated)",
+        description=(
+            "Standard Layer1Labs GitHub Actions CI pattern: permissions: {} at workflow level, "
+            "per-job contents: read grants, parallel jobs (no needs chain), full Python matrix "
+            "3.10–3.13, and --cov-fail-under=85 coverage gate."
+        ),
+        domain=SkillDomain.DEVOPS,
+        tags=[
+            "ci", "github-actions", "permissions", "pytest", "coverage",
+            "ruff", "mypy", "security", "python", "matrix", "zero-trust",
+        ],
+        platforms=["linux", "windows", "macos"],
+        prerequisites=["gh"],
+        body=("""\
+# GitHub Actions CI Skill (Layer1Labs pattern)
+
+Standard CI pattern used across all Layer1Labs / BitConcepts Python projects.
+Reference implementation: `chronomemory/.github/workflows/ci.yml`
+
+## Core principles
+- `permissions: {}` at workflow level — deny all by default.
+- `permissions: contents: read` on each individual job — grant minimum needed.
+- All jobs run **in parallel** — no `needs:` dependency chain unless truly required.
+- Full Python matrix: **3.10, 3.11, 3.12, 3.13** × ubuntu-latest, windows-latest.
+- Coverage gate: `--cov-fail-under=85`.
+- Named jobs (`name:` field) for readable GitHub UI.
+- `fail-fast: false` on the test matrix so all combinations are reported.
+
+## Canonical template
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+  workflow_dispatch:
+
+# Default: deny all. Each job grants only what it needs.
+permissions: {}
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install ruff
+      - name: ruff format --check
+        run: ruff format --check src/ tests/
+      - name: ruff check
+        run: ruff check src/ tests/
+
+  typecheck:
+    name: Type check (mypy)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: mypy src/<package>/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }} / ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov=<package> --cov-report=term-missing --cov-fail-under=85
+
+  security:
+    name: Security audit (pip-audit)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install pip-audit
+      - run: pip install -e .
+      - run: pip-audit
+```
+
+## What NOT to do
+- Do NOT set `permissions: contents: read` at workflow level — use `permissions: {}` + per-job grants.
+- Do NOT use `needs: [lint, typecheck]` to gate the test job — run all in parallel.
+- Do NOT omit Python 3.11 from the matrix.
+- Do NOT skip `--cov-fail-under` — the 85% gate is non-negotiable.
+- Do NOT use `cancel-in-progress: true` (concurrency block) unless there is a
+  specific reason — chronomemory pattern omits it.
+- Do NOT use `macos-latest` in the matrix unless macOS-specific behavior must be
+  tested — it is ~10× slower and uses more CI minutes.
+
+## Rust projects (additional jobs)
+```yaml
+  rust-lint:
+    name: Rust lint (clippy + fmt)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+      - run: cargo fmt --check --all
+      - run: cargo clippy --workspace -- -D warnings
+
+  rust-test:
+    name: Rust tests
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo test --workspace
+
+  security:
+    name: Security audit (cargo-audit)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+      - run: cargo install cargo-audit --locked
+      - run: cargo audit
+```
+"""),
+    ),
     SkillEntry(
         slug="docker-workflow",
         name="Docker — multi-stage builds, Compose, registries, security",
diff --git a/src/specsmith/skills/governance.py b/src/specsmith/skills/governance.py
@@ -140,6 +140,148 @@
             "If step 7 fails: `git tag -d v<version> && git reset --hard HEAD~1`.\n"
         ),
     ),
+    SkillEntry(
+        slug="chronomemory-esdb",
+        name="ChronoMemory ESDB — epistemic state database (v0.1.1)",
+        description=(
+            "Full API reference and critical rules for chronomemory v0.1.1: "
+            "ChronoStore WAL, query module, ContextPackCompiler, DepGraph, "
+            "token metrics, skills system, and Rust acceleration."
+        ),
+        domain=SkillDomain.GOVERNANCE,
+        tags=[
+            "esdb", "chronomemory", "epistemics", "wal", "persistence",
+            "context-pack", "query", "dep-graph", "rollback", "token-metrics",
+            "aee", "anti-hallucination",
+        ],
+        prerequisites=["chronomemory"],
+        body=("""\
+# ChronoMemory ESDB Skill (v0.1.1)
+
+EpiStemic State Database for Layer1Labs agentic projects.
+WAL at `<root>/.chronomemory/events.wal` — NDJSON, append-only, SHA-256 chained.
+
+## Imports
+```python
+from chronomemory import (
+    ChronoStore, ChronoRecord, WalEvent, open_store,   # Core
+    EsdbBridge,                                         # Backward-compat bridge
+    DepGraph, DependencyEdge,                           # Phase 2: dep graph
+    RollbackReport, invalidate,                         # Phase 2: rollback
+    ContextPack, ContextPackCompiler, ContextPackEntry, # Phase 2: context packs
+    RustChronoStore, RustRecord, RUST_BACKEND,          # Phase 3: Rust (optional)
+)
+from chronomemory import query    # 18 ESDB §23 query functions
+from chronomemory import metrics  # token metrics + skill system
+
+# Or via specsmith.esdb namespace (preferred within specsmith code):
+from specsmith.esdb import ChronoStore, query, metrics, ContextPackCompiler
+```
+
+## Critical rules — never break these
+1. `dependencies = []` in pyproject.toml must stay empty — chronomemory is stdlib-only.
+2. Never physically delete WAL records — always `store.delete(id)` (tombstone only).
+3. Use `query.what_is_known(store)` not `store.query(rag_filter=True)` for LLM context
+   — the former excludes infra record kinds (edge, rollback_event, token_metric, skill_run).
+4. Governance status (`defined`/`implemented`) ≠ ESDB status (`active`/`tombstone`)
+   — never conflate when migrating from `.specsmith/*.json`.
+5. WAL is append-only NDJSON — one JSON object per line, SHA-256 chained.
+
+## Core write/read
+```python
+with ChronoStore(project_root) as store:
+    store.upsert(ChronoRecord(
+        id="FACT-001", kind="fact",
+        label="CPSC projection is the sole validity authority",
+        source_type="observed", confidence=0.99,
+        evidence=["CPSC-Specification.md §9"],
+    ))
+    store.delete("OLD-001")     # tombstone only — never physically removes
+    store.chain_valid()         # verify SHA-256 WAL integrity
+
+# For LLM context — always use query.what_is_known (rule #3)
+with ChronoStore(project_root) as store:
+    beliefs = query.what_is_known(store)   # active, conf>=0.6, no infra records
+    hypotheses = query.what_requires_reverification(store)
+    done = query.has_this_work_been_done(store, "migrate flat JSON")
+```
+
+## Backward-compat bridge
+```python
+bridge = EsdbBridge(project_root)
+bridge.status().backend  # "ChronoStore WAL" or "json"
+store.migrate_from_json(Path(project_root) / ".specsmith")
+```
+
+## Dependency graph
+```python
+g = DepGraph(store=store)
+g.add_edge("HYP-001", "FACT-001", "depends_on")
+# Valid edge types: assumes contradicts depends_on derived_from
+#                  generated_from invalidates supports supersedes validated_by
+```
+
+## Epistemic rollback
+```python
+report = store.invalidate("FACT-001", "reason", dep_graph=g)
+# Cascades depends_on/derived_from → status=hypothesis, confidence halved
+```
+
+## Context pack for LLM injection
+```python
+pack = ContextPackCompiler(store).compile(
+    task_id="TASK-42", goal="fix ruff errors", token_budget=4096
+)
+context_json = pack.to_dict()  # inject into LLM context
+# Excludes: tombstone/invalidated/hypothesis, conf<0.6, infra kinds, over-budget
+```
+
+## Query API (18 functions — all degrade gracefully without dep_graph)
+```python
+query.what_is_known(store)                   # active beliefs, no infra kinds
+query.what_requires_reverification(store)    # hypotheses needing confirmation
+query.has_this_work_been_done(store, label)  # bool — check prior decisions
+query.why_do_we_believe(store, "FACT-001")   # evidence chain for a record
+query.what_skills_apply(store, "run lint")   # skills matching task label
+query.what_changed_since(store, seq)         # records written after WAL seq N
+query.what_confidence_collapsed(store, 0.6)  # hypotheses below threshold
+query.what_can_agent_do_next(store, goal)    # unblocked action records
+query.what_should_agent_not_do(store)        # stop_condition records
+query.is_this_action_duplicate(store, label) # alias for has_this_work_been_done
+```
+
+## Token metrics
+```python
+metrics.record_token_metric(
+    store, task_id="TASK-1",
+    context_tokens=512, input_tokens=256, output_tokens=128,
+    tool_calls=4, elapsed_ms=1800, success=True,
+)
+metrics.token_efficiency_report(store)  # {tokens_per_success, avg_tool_calls, ...}
+```
+
+## Skills system
+```python
+# Register a skill
+store.upsert(ChronoRecord(
+    id="SKILL-ruff", kind="skill", label="ruff linter", confidence=0.9,
+    data={"activation": ["lint", "ruff", "python"]},
+))
+metrics.find_skills(store, "run ruff lint")    # returns matching skill records
+metrics.record_skill_run(store, "SKILL-ruff",  # writes a skill_run WAL record
+    success=True, tokens_used=150, output={"errors": 0})
+```
+
+## Rust acceleration (Phase 3)
+```python
+from chronomemory import RUST_BACKEND
+# False by default — requires: pip install maturin
+#   maturin develop --manifest-path crates/chronomemory-py/Cargo.toml
+# When True, RustChronoStore and RustRecord are available.
+print("Rust backend:", RUST_BACKEND)
+```
+"""),
+    ),
     SkillEntry(
         slug="issue-triage",
         name="Issue Triage — classify and prioritise GitHub issues",
