diff --git a/.DONE b/.DONE deleted file mode 100644 index e69de29..0000000 diff --git a/.KEI_FORK_META.toml b/.KEI_FORK_META.toml deleted file mode 100644 index 5075975..0000000 --- a/.KEI_FORK_META.toml +++ /dev/null @@ -1,4 +0,0 @@ -agent_id = "ci-cost-fix-w15" -started_ts = 1776937553 -base_branch = "main" -ledger_id = "ci-cost-fix-w15" diff --git a/.gitignore b/.gitignore index 80606dc..4e18ba6 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,11 @@ _primitives/_rust/target/ # Agent worktrees — ephemeral orchestrator scratch dirs, never commit. .claude/worktrees/ **/.claude/worktrees/ +.claude/forks/ + +# kei-fork internal markers (should never leak into main) +.DONE +.KEI_FORK_META.toml # Secrets .env diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/.claude-plugin/marketplace.json b/_archive/forks/2026-04-23/ci-cost-fix-w15/.claude-plugin/marketplace.json new file mode 100644 index 0000000..e057937 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/.claude-plugin/marketplace.json @@ -0,0 +1,21 @@ +{ + "name": "keisei-marketplace", + "owner": { + "name": "KeiSei84", + "url": "https://github.com/KeiSei84" + }, + "metadata": { + "description": "KeiSei Constructor-Pattern kits and primitives for Claude Code", + "version": "0.16.0" + }, + "plugins": [ + { + "name": "keisei", + "source": { + "source": "github", + "repo": "KeiSei84/KeiSeiKit" + }, + "description": "Full KeiSeiKit — 12-agent fleet, 39 skills, 9 hooks, 23 Rust primitives, sleep-sync cloud consolidation, MCP server layer" + } + ] +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/.claude-plugin/mcp-template.json b/_archive/forks/2026-04-23/ci-cost-fix-w15/.claude-plugin/mcp-template.json new file mode 100644 index 0000000..047d0f9 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/.claude-plugin/mcp-template.json @@ -0,0 +1,9 @@ +{ + "_comment": "Template for .mcp.json. Copy to repo root as .mcp.json to register the KeiSei MCP server. Requires @keisei/mcp-server published to npm (status: not yet published — see PLUGIN.md).", + "mcpServers": { + "keisei": { + "command": "npx", + "args": ["-y", "@keisei/mcp-server", "--stdio"] + } + } +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/.claude-plugin/plugin.json b/_archive/forks/2026-04-23/ci-cost-fix-w15/.claude-plugin/plugin.json new file mode 100644 index 0000000..320b07a --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/.claude-plugin/plugin.json @@ -0,0 +1,22 @@ +{ + "name": "keisei", + "version": "0.16.0", + "description": "Constructor-Pattern agent kit for Claude Code: composable behavioral blocks, 23 Rust primitives, 39 portable skills, 9 pre-wired hooks, typed artifact handoff, sleep-sync cloud consolidation, MCP server layer.", + "author": { + "name": "KeiSei", + "url": "https://github.com/KeiSei84" + }, + "homepage": "https://github.com/KeiSei84/KeiSeiKit", + "repository": "https://github.com/KeiSei84/KeiSeiKit", + "license": "MIT", + "keywords": [ + "constructor-pattern", + "agents", + "skills", + "hooks", + "mcp", + "rust", + "claude-code", + "sleep-sync" + ] +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/.dockerignore b/_archive/forks/2026-04-23/ci-cost-fix-w15/.dockerignore new file mode 100644 index 0000000..1b60657 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/.dockerignore @@ -0,0 +1,46 @@ +# .dockerignore — trim the Docker build context. +# Without this, `docker build` tries to copy the full working tree into the +# daemon, including target/ (2.6 GB after v0.21 aws-sdk-s3), agent worktrees +# (6+ GB), and node_modules. That caused an I/O error on 2026-04-22 when the +# battle-test image tried to pack everything. +# +# Keep this list aligned with tests/battle/Dockerfile.install-test — anything +# the Dockerfile actually needs (scripts/, install/, hooks/, skills/, etc.) +# must NOT be listed here. + +# Rust build artefacts +**/target/ +**/*.rlib +**/*.rmeta + +# TypeScript / node +**/node_modules/ +**/dist/ +**/.turbo/ + +# Agent worktrees (several GB — never relevant inside a container build) +.claude/worktrees/ + +# Git internal (we don't need history inside the image) +.git/ + +# IDE + OS +.DS_Store +.idea/ +.vscode/ +*.swp + +# Editor backups +*~ +*.bak +*.bak-* + +# Secrets (defence in depth — RULE 0.8 + project .gitignore) +**/.env +**/secrets/*.env +*.pem +*.key + +# Logs +*.log +/tmp/ diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/.github/dependabot.yml b/_archive/forks/2026-04-23/ci-cost-fix-w15/.github/dependabot.yml new file mode 100644 index 0000000..8c88efe --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/.github/dependabot.yml @@ -0,0 +1,26 @@ +version: 2 +updates: + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly + open-pull-requests-limit: 5 + labels: + - dependencies + - github-actions + - package-ecosystem: npm + directory: /_ts_packages + schedule: + interval: weekly + open-pull-requests-limit: 5 + labels: + - dependencies + - npm + - package-ecosystem: cargo + directory: /_primitives/_rust + schedule: + interval: weekly + open-pull-requests-limit: 5 + labels: + - dependencies + - rust diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/.github/workflows/ci.yml b/_archive/forks/2026-04-23/ci-cost-fix-w15/.github/workflows/ci.yml new file mode 100644 index 0000000..ac74ba5 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/.github/workflows/ci.yml @@ -0,0 +1,119 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + paths-ignore: + - 'docs/**' + - '**/*.md' + - 'CHANGELOG.md' + +# v0.21.0 cost optimisation (W15): cancel superseded runs on the same ref. +# A rapid push train (common during batch work) used to launch one full +# 12-job matrix per commit, even though only the last matters. This +# top-level concurrency group cancels the older run as soon as a newer +# one is queued. Effect: 60-80% saving on "rapid pushes" work days. +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + +# v0.19.1 supply-chain hardening (H5): every third-party action is pinned +# by full commit SHA. A floating tag like @v4 can be re-pointed by a +# compromised maintainer (CVE-2025-30066 class). The `# vN.m.k` comment +# next to each SHA is a human-readable hint only — the SHA is the load- +# bearing identifier. When Dependabot proposes a bump, review the new SHA +# against the release tag before merging. + +jobs: + rust-assembler: + runs-on: ${{ matrix.os }} + strategy: + # v0.21.0: macOS only on push-to-main (10x billing multiplier). PRs get ubuntu-only. + matrix: + os: ${{ (github.event_name == 'push' && github.ref == 'refs/heads/main') && fromJSON('["ubuntu-latest","macos-latest"]') || fromJSON('["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + - uses: dtolnay/rust-toolchain@stable # exception to SHA-pin rule: this action uses named-branch convention (stable/nightly/beta/1.NN.0) — pinning a SHA locks to a specific Rust version (validator V-2026-04-22 confirmed 3c5f7ea was rust 1.94.1 branch tip, not generic "install stable"). dtolnay is a trusted maintainer (author of serde/anyhow/cxx). Supply-chain risk of @stable re-point is LOW and accepted here. + - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1 + with: + workspaces: _assembler + - run: cd _assembler && cargo test --release + + rust-primitives: + runs-on: ${{ matrix.os }} + strategy: + # v0.21.0: macOS only on push-to-main. --release dropped — debug mode + # runs 2-3× faster and still catches architectural breakage. Release- + # build regressions (debug_assertions!) caught by rust-assembler above. + matrix: + os: ${{ (github.event_name == 'push' && github.ref == 'refs/heads/main') && fromJSON('["ubuntu-latest","macos-latest"]') || fromJSON('["ubuntu-latest"]') }} + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + - uses: dtolnay/rust-toolchain@stable # exception to SHA-pin rule: this action uses named-branch convention (stable/nightly/beta/1.NN.0) — pinning a SHA locks to a specific Rust version (validator V-2026-04-22 confirmed 3c5f7ea was rust 1.94.1 branch tip, not generic "install stable"). dtolnay is a trusted maintainer (author of serde/anyhow/cxx). Supply-chain risk of @stable re-point is LOW and accepted here. + - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1 + with: + workspaces: _primitives/_rust + - run: cd _primitives/_rust && cargo test --workspace + + ts-packages: + # v0.21.0: ubuntu-only. Node is x-plat; no macOS-specific behaviour to + # test. Matrix: 2 jobs (ubuntu × 2 nodes) instead of 4. Saves 2 macOS jobs. + runs-on: ubuntu-latest + strategy: + matrix: + node: ['20', '22'] + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 + with: + node-version: ${{ matrix.node }} + - run: cd _ts_packages && npm ci + - run: cd _ts_packages && npm run build --workspaces + - run: cd _ts_packages && npm test --workspaces --if-present + + install-dry-run: + # v0.21.0: ubuntu-only. All 3 profiles on main push; PRs get minimal-only + # (full profile pulls everything, rarely signals PR-specific regressions). + runs-on: ubuntu-latest + strategy: + matrix: + profile: ${{ (github.event_name == 'push' && github.ref == 'refs/heads/main') && fromJSON('["minimal","dev","full"]') || fromJSON('["minimal"]') }} + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + - uses: dtolnay/rust-toolchain@stable # exception to SHA-pin rule: this action uses named-branch convention (stable/nightly/beta/1.NN.0) — pinning a SHA locks to a specific Rust version (validator V-2026-04-22 confirmed 3c5f7ea was rust 1.94.1 branch tip, not generic "install stable"). dtolnay is a trusted maintainer (author of serde/anyhow/cxx). Supply-chain risk of @stable re-point is LOW and accepted here. + - name: Install hard deps + run: sudo apt-get update && sudo apt-get install -y jq pandoc + - run: bash -n install.sh + - run: ./install.sh --no-execute --profile=${{ matrix.profile }} + + shell-lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + - run: sudo apt-get update && sudo apt-get install -y shellcheck + - name: shellcheck (advisory) + # v0.15.1: kept advisory because local shellcheck sweep not yet clean + # (quoted-var nits in hooks). Flip to fatal once the sweep is committed; + # planned for v0.16. + # v0.20.1: explicit `|| true` in addition to continue-on-error — the + # latter doesn't always suppress the step-level exit-1 in the GH + # Actions annotation stream. + run: | + find hooks _primitives -name '*.sh' -exec shellcheck -S warning {} + || \ + echo "shellcheck emitted warnings (advisory-only, not blocking)" + continue-on-error: true + + workflow-lint: + # v0.20.1: guards against the dtolnay-SHA-class incident (2026-04-22). + # actionlint catches workflow syntax; validate-workflow-shas.sh catches + # fabricated / force-pushed SHA pins. Runs fast (<30s). + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + - name: Install actionlint + run: bash scripts/install-actionlint.sh + - name: Lint workflows (actionlint) + run: PATH="${HOME}/.local/bin:${PATH}" bash scripts/lint-workflows.sh + - name: Validate pinned SHAs + run: bash scripts/validate-workflow-shas.sh diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/.github/workflows/release.yml b/_archive/forks/2026-04-23/ci-cost-fix-w15/.github/workflows/release.yml new file mode 100644 index 0000000..4a95db9 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/.github/workflows/release.yml @@ -0,0 +1,344 @@ +name: Release + +on: + push: + tags: + - 'v*' + +permissions: + contents: write + +jobs: + build-release: + name: Build ${{ matrix.target }} + runs-on: ${{ matrix.os }} + continue-on-error: ${{ matrix.experimental }} + strategy: + fail-fast: false + matrix: + # v0.22.3 fix: aarch64-linux moved from ubuntu-latest + cross-linker + # install (apt gcc-aarch64-linux-gnu consistently failed in CI) to + # ubuntu-24.04-arm NATIVE ARM runner. No cross-compile, rustc builds + # the target host-native. `experimental: false` — native path is + # reliable. + include: + - os: ubuntu-latest + target: x86_64-unknown-linux-gnu + experimental: false + - os: ubuntu-24.04-arm + target: aarch64-unknown-linux-gnu + experimental: false + - os: macos-latest + target: x86_64-apple-darwin + experimental: false + - os: macos-latest + target: aarch64-apple-darwin + experimental: false + steps: + # v0.19.1 supply-chain hardening (H5): all actions pinned by full + # commit SHA; a floating tag like @v4 can be re-pointed by a + # compromised maintainer (CVE-2025-30066 class). Version comment next + # to each SHA is for human readability only — the SHA is load-bearing. + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + with: + fetch-depth: 0 + + - name: Install Rust toolchain + uses: dtolnay/rust-toolchain@stable # exception to SHA-pin: named-branch convention (validator V-2026-04-22) + with: + targets: ${{ matrix.target }} + + - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1 + with: + workspaces: _primitives/_rust + + # v0.22.3: cross-linker step removed — aarch64-linux now builds + # natively on ubuntu-24.04-arm. No cross-compile, no gcc-aarch64-linux-gnu. + + - name: Build workspace (release) + working-directory: _primitives/_rust + run: cargo build --workspace --release --target ${{ matrix.target }} + + - name: Package binaries + id: package + working-directory: _primitives/_rust/target/${{ matrix.target }}/release + shell: bash + run: | + set -euo pipefail + # Collect every Cargo-built executable (Linux + macOS: no ext, mode +x). + # Portable across GNU + BSD find: iterate, test executability in shell. + BINS=() + for f in *; do + [ -f "$f" ] || continue + case "$f" in + *.d|*.rlib|*.rmeta|*.so|*.dylib|*.dSYM) continue ;; + esac + if [ -x "$f" ]; then + BINS+=("$f") + fi + done + if [ "${#BINS[@]}" -eq 0 ]; then + echo "::error::no release binaries produced for ${{ matrix.target }}" + exit 1 + fi + echo "Binaries found: ${BINS[*]}" + ARCHIVE="keisei-${{ matrix.target }}.tar.gz" + tar czf "$GITHUB_WORKSPACE/$ARCHIVE" "${BINS[@]}" + cd "$GITHUB_WORKSPACE" + if command -v sha256sum >/dev/null 2>&1; then + sha256sum "$ARCHIVE" > "$ARCHIVE.sha256" + else + shasum -a 256 "$ARCHIVE" > "$ARCHIVE.sha256" + fi + echo "archive=$ARCHIVE" >> "$GITHUB_OUTPUT" + + - name: Upload artifact + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: binaries-${{ matrix.target }} + path: | + keisei-${{ matrix.target }}.tar.gz + keisei-${{ matrix.target }}.tar.gz.sha256 + if-no-files-found: error + + # v0.18 Phase 1 (exobrain): compile @keisei/mcp-server to a single static + # binary for 5 platforms via `bun build --compile`. Runs in parallel with + # build-release; the release job below `needs:` both. Linux arm64 is kept + # `continue-on-error` because the ubuntu arm runner pool is newer and + # occasionally flaky — a missing linux-arm64 asset must NOT block release. + build-mcp-binary: + # v0.22.2 fix: `macos-13` Intel runners were deprecated by GitHub and the + # pool is dry — `darwin-x64` jobs sit in queued for hours and block the + # final `release` job (needs: build-mcp-binary). bun supports + # cross-compile to every target from any host, so we consolidate every + # bun build onto ubuntu-latest. Faster, no macOS quota cost, no runner + # starvation. Binaries are still native per-target (bun produces the + # correct Mach-O / ELF / PE format via --target). + name: Build mcp-server ${{ matrix.target.platform }}-${{ matrix.target.arch }} + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + target: + - { platform: linux, arch: x64, bun_target: bun-linux-x64, ext: '' } + - { platform: linux, arch: arm64, bun_target: bun-linux-arm64, ext: '' } + - { platform: darwin, arch: x64, bun_target: bun-darwin-x64, ext: '' } + - { platform: darwin, arch: arm64, bun_target: bun-darwin-arm64, ext: '' } + - { platform: windows, arch: x64, bun_target: bun-windows-x64, ext: '.exe' } + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + + - name: Install bun + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 + with: + bun-version: latest + + # v0.19.1 supply-chain hardening (H4): lockfile is REQUIRED — the + # `|| bun install` fallback was removed so a missing bun.lock fails + # the build instead of resolving deps fresh against the live npm + # registry (tainted-binary window). bun.lock lives at workspace + # root (_ts_packages/bun.lock) — bun is a monorepo tool and tracks + # all packages/* from one lockfile. See BUILD.md §Lockfile. + - name: Install mcp-server deps + shell: bash + working-directory: _ts_packages + run: bun install --frozen-lockfile + + - name: Compile single-binary + shell: bash + env: + BIN_NAME: kei-mcp-server-${{ matrix.target.platform }}-${{ matrix.target.arch }}${{ matrix.target.ext }} + run: | + set -euo pipefail + mkdir -p dist + bun build \ + --compile \ + --target=${{ matrix.target.bun_target }} \ + _ts_packages/packages/mcp-server/src/index.ts \ + --outfile "dist/${BIN_NAME}" + ls -la "dist/${BIN_NAME}" + + - name: Compute sha256 + shell: bash + env: + BIN_NAME: kei-mcp-server-${{ matrix.target.platform }}-${{ matrix.target.arch }}${{ matrix.target.ext }} + run: | + set -euo pipefail + cd dist + if command -v sha256sum >/dev/null 2>&1; then + sha256sum "${BIN_NAME}" > "${BIN_NAME}.sha256" + else + shasum -a 256 "${BIN_NAME}" > "${BIN_NAME}.sha256" + fi + cat "${BIN_NAME}.sha256" + + - name: Upload artifact + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: kei-mcp-server-${{ matrix.target.platform }}-${{ matrix.target.arch }} + path: | + dist/kei-mcp-server-${{ matrix.target.platform }}-${{ matrix.target.arch }}${{ matrix.target.ext }} + dist/kei-mcp-server-${{ matrix.target.platform }}-${{ matrix.target.arch }}${{ matrix.target.ext }}.sha256 + if-no-files-found: error + + release: + name: Publish GitHub Release + needs: [build-release, build-mcp-binary] + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + with: + fetch-depth: 0 + + - name: Install Rust toolchain + uses: dtolnay/rust-toolchain@stable # exception to SHA-pin: named-branch convention (validator V-2026-04-22) + + - uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1 + with: + workspaces: _primitives/_rust + + - name: Build kei-changelog + working-directory: _primitives/_rust + run: cargo build --release -p kei-changelog + + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + path: dist/ + + - name: Flatten artifacts + run: | + set -euo pipefail + mkdir -p release-assets + # Rust tarballs + sha256 sums from build-release matrix. + # MCP-server bare binaries (+ .exe on windows) + sha256 sums from + # build-mcp-binary matrix. Bare binaries need a stable name to stay + # USB-drive-droppable, so no archive — we ship them raw alongside + # the tarballs. + find dist -type f \( \ + -name '*.tar.gz' \ + -o -name '*.sha256' \ + -o -name 'kei-mcp-server-*' \ + \) -exec mv {} release-assets/ \; + ls -la release-assets + + - name: Generate release notes (kei-changelog) + id: notes + run: | + set -euo pipefail + TAG="${GITHUB_REF_NAME}" + PREV="$(git tag --sort=-creatordate | grep -v "^${TAG}$" | head -n1 || true)" + echo "Current tag: ${TAG}" + echo "Previous tag: ${PREV:-}" + if [ -n "${PREV}" ]; then + NOTES="$(./_primitives/_rust/target/release/kei-changelog \ + --from "${PREV}" --to "${TAG}" --version "${TAG}")" + else + NOTES="$(./_primitives/_rust/target/release/kei-changelog \ + --to "${TAG}" --version "${TAG}")" + fi + if [ -z "${NOTES}" ]; then + NOTES="Release ${TAG}. No conventional-commit entries found in range." + fi + { + echo 'notes<> "$GITHUB_OUTPUT" + + # v0.22.3 fix: softprops/action-gh-release v2.6.2 exited with failure + # on v0.22.2 due to a metadata-update race (asset uploaded to blob + # store but Releases metadata API returned 404 on the subsequent + # PATCH — eventual-consistency window). All 15 assets WERE uploaded, + # but the action exited 1 and left the Release in Draft state. + # + # Replaced with `gh release create` (bundled on all GitHub runners). + # CLI is idempotent: if the release already exists it updates it; if + # assets already exist `--clobber` replaces them. No metadata-PATCH + # race. Retry loop on transient upload failures. + - name: Publish GitHub Release + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + TAG: ${{ github.ref_name }} + NOTES: ${{ steps.notes.outputs.notes }} + shell: bash + run: | + set -euo pipefail + # Create the release if missing; `|| true` absorbs "already exists" + # on workflow re-run. + gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1 || \ + gh release create "$TAG" \ + --repo "$GITHUB_REPOSITORY" \ + --title "$TAG" \ + --notes "$NOTES" + # Upload all assets with --clobber so re-runs replace cleanly. + # Retry each asset up to 3 times on transient network errors. + shopt -s nullglob + for f in release-assets/*.tar.gz release-assets/*.sha256 release-assets/kei-mcp-server-*; do + [ -f "$f" ] || continue + for try in 1 2 3; do + if gh release upload "$TAG" --repo "$GITHUB_REPOSITORY" --clobber "$f"; then + break + elif [ "$try" -eq 3 ]; then + echo "::error::failed to upload $f after 3 tries" >&2 + exit 1 + else + echo "upload of $f failed (attempt $try/3), retrying in 5s..." >&2 + sleep 5 + fi + done + done + echo "✓ Release $TAG published with all assets" + + npm-publish: + name: Publish npm packages (optional) + needs: release + runs-on: ubuntu-latest + # Graceful skip: if NPM_TOKEN secret is not configured, the first step + # reports "skipped" and exits 0 — Rust-binary release above still succeeds. + steps: + - name: Check NPM_TOKEN presence + id: have_token + env: + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} + run: | + if [ -n "${NPM_TOKEN:-}" ]; then + echo "present=1" >> "$GITHUB_OUTPUT" + else + echo "present=0" >> "$GITHUB_OUTPUT" + echo "::notice::NPM_TOKEN not set — skipping npm publish gracefully" + fi + + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 + if: steps.have_token.outputs.present == '1' + + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 + if: steps.have_token.outputs.present == '1' + with: + node-version: '20' + registry-url: 'https://registry.npmjs.org' + + - name: Install deps + if: steps.have_token.outputs.present == '1' + working-directory: _ts_packages + run: npm ci + + - name: Build workspaces + if: steps.have_token.outputs.present == '1' + working-directory: _ts_packages + run: npm run build --workspaces --if-present + + - name: Publish each package + if: steps.have_token.outputs.present == '1' + working-directory: _ts_packages + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + run: | + set -euo pipefail + for pkg in packages/*/; do + if [ -f "$pkg/package.json" ]; then + echo "::group::publish $pkg" + ( cd "$pkg" && npm publish --access public ) \ + || echo "::warning::publish failed for $pkg (continuing)" + echo "::endgroup::" + fi + done diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/.gitignore b/_archive/forks/2026-04-23/ci-cost-fix-w15/.gitignore new file mode 100644 index 0000000..80606dc --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/.gitignore @@ -0,0 +1,53 @@ +_primitives/_rust/target/ +**/target/ +.DS_Store + +# Agent worktrees — ephemeral orchestrator scratch dirs, never commit. +.claude/worktrees/ +**/.claude/worktrees/ + +# Secrets +.env +.env.* +!.env.example +!.env.template +secrets/ +**/secrets/ +.claude/secrets/ + +# Keys and certs +*.pem +*.key +*.pfx +*.p12 +*.jks +id_rsa +id_rsa.* +id_ed25519 +id_ed25519.* +*.gpg + +# Credentials / config with values +credentials.json +.netrc +.authinfo +.aws/credentials +.ssh/ + +# Locks (per-project policy — leave as existing if already tracked) +# Do not add: Cargo.lock (tracked per RULE 0.1 for reproducibility) + +# OS + editor junk +Thumbs.db +*.swp +*.swo +.idea/ +.vscode/ +*.iml + +# Build +node_modules/ +dist/ +build/ +__pycache__/ +*.pyc diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/CHANGELOG.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/CHANGELOG.md new file mode 100644 index 0000000..8ef5243 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/CHANGELOG.md @@ -0,0 +1,233 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +Entries are generated from the git history via +`_primitives/_rust/kei-changelog` (a conventional-commits walker). +Regenerate a single version block with, e.g.: + +```bash +_primitives/_rust/target/release/kei-changelog \ + --from v0.14.2 --to v0.15.0 --version v0.15.0 --update CHANGELOG.md +``` + +## [Unreleased] + +> Work in flight on `feat/v0.16-changelog-gen` and follow-up branches. +> Only placeholders — no corresponding commits exist yet. Any line that +> ships must be replaced with the real commit summary before release. + +### Changed +- **primitives (v0.22 — `keisei` schema v4, BREAKING marker shape):** + - Marker schema bumped from v3 to v4. The top-level `brain_path` / `brain_name` / `attached_at` fields are gone; every `[[attachments]]` entry now owns its own `brain_path`, `brain_name`, and `attached_at`. Consequence: one marker can track multiple brains wired to different clients at the same time (e.g. brain-A on Claude Code at user scope + brain-B on Cursor at project scope). `config::AttachRecord::new(attachments)` is the fresh constructor; raw struct literals no longer compile. + - `ClientAdapter::post_attach_hint` signature widened from `fn (&self) -> &'static str` to `fn (&self, brain: &Brain, scope: Scope) -> String` so adapters can interpolate the brain's name and the resolved scope into the reload instruction. Implementations of the trait outside this crate need to update. + - Adapter enumeration centralised in `adapters/_registry.rs::all_adapters`. `adapter::all()` now delegates; the "add a 5th adapter" touchpoint drops from three files to one. Public API of `adapter::all()` unchanged. +- **primitives (v0.22 — `config.rs` decomposition):** + - Schema-migration logic extracted from `config.rs` into `config_migrate.rs` (pure functions on `WireRecord` → `AttachRecord`). Time helpers extracted into `time.rs` with a 5-test anchor suite covering epoch-0, leap day 2020-02-29, century non-leap 2100-03-01, an arbitrary recent timestamp, and `civil_from_days` direct invariants. `config.rs` drops from 224 LOC to 197 LOC, below the 200-LOC Constructor Pattern ceiling. + +### Added +- **primitives/keisei (v0.22 Track A — schema v4 multi-brain marker):** `AttachRecord` inverted so every `Attachment` carries its own `brain_path` + `brain_name` + `scope` + `attached_at`. Enables brain-A attached to Claude Code (user scope) + brain-B attached to Cursor (project scope) simultaneously in ONE marker. v1/v2/v3 readers transparent via `#[serde(untagged)]` — auto-migrate silently on first v0.22 `config::read()` with one-line stderr notice. +- **primitives (v0.22 — `Scope::Auto` CLI default):** + - `keisei attach ` without `--scope` now defaults to `auto`. Each adapter exposes `auto_scope()`; Claude Code returns `Scope::Project` when CWD has `.claude/` (dir or `settings.json`), Cursor when CWD has `.cursor/`. Continue + Zed stay on user-scope default. Team workflow `cd team-repo; keisei attach brain` now picks project-scope without an extra flag. + - `Scope::Auto` is a CLI-level intent only — `attach.rs` resolves it to a concrete `User` / `Project` before writing the marker. The persisted marker never contains `auto`. +- **primitives (v0.22 — `keisei mount` per-adapter scope resolution):** + - `mount` now resolves scope per-adapter via `auto_scope()` instead of forcing `Scope::User` across the fan-out. A single `keisei mount brain` inside `team-repo/` can wire Cursor at project scope and Claude Code at user scope (or both at project, depending on CWD). +- **primitives (v0.22 — templated `post_attach_hint`):** `fn post_attach_hint(&self, brain: &Brain, scope: Scope) -> String` interpolates the brain name + resolved scope into the per-adapter reload instruction. No more Claude-Code-specific string in the orchestrator. +- **primitives (v0.22 — adapter registry):** new `adapters/_registry.rs` (32 LOC) is the single canonical adapter list. `adapter::all()` delegates. Adding a 5th adapter is one line, one place. +- **primitives (v0.22 — `config.rs` decomposition):** `config.rs` 224 → 197 LOC. Extracted `time.rs` (90 LOC — `now_utc_string` + `format_epoch_utc` + `civil_from_days` + 5 unit tests covering epoch-0, leap-day 2020-02-29, century-non-leap 2100-03-01, arbitrary 2026-04-22, RFC3339 shape) and `config_migrate.rs` (114 LOC — `WireRecord` v1→v4 migration). +- **docs (v0.22 — README `## Reference` section):** major new section appended before `## Runtime hook controls`. Documents the actual CLI surface of every shipped component: 25 Rust primitives (clap subcommands + flags + state paths + exit codes extracted from `_primitives/_rust/*/src/main.rs`), 13 shell primitives (header docstrings + flags), all 10 hooks (event + severity + bypass table), 39 skills grouped into 6 collapsible categories, and a deep-dive on the `keisei` exobrain CLI (real flag matrix, exit codes, env vars, marker SSoT, v0.19 security hardening). Every claim is source-verified — flags not present in code are marked absent, not fabricated. Adds ~670 LOC to README.md; collapsible `
` used for the 39-skill table to keep scroll length reasonable. +- **primitives/keisei (v0.22 Track C — filesystem-type advisory):** new `fs_type.rs` cube (`<110 LOC`) classifies the brain root via `statfs(2)` on macOS + Linux and returns `FsWarning::{None,ExFat,Fat32,Unknown}`. Windows support deferred (returns `Unknown` until `GetVolumeInformationW` lands). `Brain::load` now prints a stderr advisory when exFAT / FAT32 is detected — SQLite WAL shared-mmap is unreliable there and `keisei mount` (multi-client) WILL corrupt `kei-memory` / `kei-artifact` / `kei-social-store` DBs. Warning is non-blocking — single-client `keisei attach` on exFAT stays supported. New runtime dep `libc = "0.2"` (unix-only). Two new integration tests (`brain_load_on_typical_filesystem_no_warn`, `fs_type_detection_returns_none_on_standard_fs`). +- **tests/battle (v0.22 Track C — distro matrix):** two new Dockerfiles alongside the existing `ubuntu:24.04` image. `Dockerfile.install-test-alpine` (Alpine 3.19 — musl libc, exposes musl-static-link quirks in `rusqlite` / `git2` / `aws-sdk-s3`). `Dockerfile.install-test-debian` (Debian 12 bookworm — glibc, different apt structure from Ubuntu). `README.md` documents the 3-image matrix and documents known musl-static-link failures as matrix signal rather than regression. +- **docs (v0.22 Track C — USB guide platform split):** `USB-BRAIN-GUIDE.md` restructured into a TOC + platform-agnostic preamble (prerequisites, exFAT/FAT32 warning, invariants, troubleshooting). Three new platform-specific walkthroughs: `USB-BRAIN-GUIDE-macos.md` (Gatekeeper `xattr`, `/Volumes/`, `diskutil`), `USB-BRAIN-GUIDE-linux.md` (`/media/$USER/`, `umount`, ext4, optional systemd-udev auto-attach), `USB-BRAIN-GUIDE-windows.md` (PowerShell, drive letter, NTFS, `Dismount-Volume`, FS-advisory returns `Unknown` caveat). + +### Removed +- **primitives (v0.22 — dead `Error` variants):** + - `Error::NotAttached` — never surfaced; `detach` prints "nothing to detach" and returns `Ok(())`. + - `Error::AdapterFailed { client, reason }` — never constructed; `mount` / `detach` orchestration carried `(client, reason)` tuples instead. Downstream matches on these variants won't compile against v0.22. + +### Added (pre-v0.22) +- **primitives (v0.21 — keisei SSoT relocation + `Scope` enum):** + - Marker file relocated from `~/.claude/keisei-attached.toml` to `~/.keisei/attached.toml`. `~/.claude/` is Claude-Code-specific territory and should not host cross-adapter keisei state. `config::read()` performs a one-shot migration the first time it runs under v0.21: if the legacy file exists and the new location is empty, the marker moves over (new file written, legacy file deleted) and a stderr notice is emitted. + - `Scope` enum (`user` / `project`) on the `ClientAdapter` trait. Adapters declare `supported_scopes()`; `config_path(scope)`, `attach(brain, scope)`, `detach(brain_name, scope)` are scope-aware. Claude Code and Cursor support both scopes; Continue and Zed are user-only. `keisei attach` gains `--scope=` (default `user`); `keisei mount` stays host-wide (`Scope::User` fan-out by design). + - Marker schema v3: each `[[attachments]]` entry carries `scope = "user" | "project"`. Pre-v0.21 markers without the field default to `Scope::User` silently. New error variant `Error::ScopeUnsupported { client, scope, supported }` fires when a caller asks for a scope the adapter doesn't advertise. +- **primitives (v0.21 — `kei-store` real S3 backend):** + - `S3CloudStore` — functional S3 / R2 / MinIO / Wasabi backend via `aws-sdk-s3` v1. GetObject / PutObject / ListObjectsV2 (paginated) / DeleteObject wired behind the existing `MemoryStore` trait (sync-over-async via a single-thread tokio runtime). Enables `keisei attach s3://my-bucket/brain/` as a real cloud-mount path, not just a local stub. + - Opt-in feature flag `s3` on the `kei-store` crate — off by default so users who don't need cloud pay zero binary weight. Enabling adds tokio + hyper + rustls + aws-sdk-s3 (~5 MB release binary growth [estimate, E5 — not yet measured; would require `cargo build --release` before/after feature flag]). + - AWS default credential chain honoured (env vars → `~/.aws/credentials` → IMDS). No new credential format; RULE 0.8 secrets-single-source unchanged. + - Endpoint override for non-AWS S3-compat providers via `KEI_STORE_S3_ENDPOINT` env var (runtime) or `s3.endpoint` in `store-config.toml` (persistent). Path-style addressing auto-enabled when a custom endpoint is set (MinIO / some R2 configs). + - "Branch" semantics: S3 has no native branching, so a branch is modelled as a key prefix (`/`). `branch()` sets the active prefix in-memory; default `main`. + - Factory auto-routes: `backend = "s3"` + feature `s3` + `s3.bucket` set → real cloud; otherwise falls back to the v0.14 local-manifest stub (still behind `KEI_STORE_ALLOW_S3_STUB=1`). + - Path-traversal guard parity with `FilesystemStore`: absolute and `..`-component paths rejected before keys are spliced. +- **tests/battle:** Docker-based clean-Ubuntu install test — `tests/battle/Dockerfile.install-test` + `verify.sh` + `battle-entry.sh` + README. Builds a fresh `ubuntu:24.04` image, runs `install.sh --profile=` under `--yes`, then asserts post-install counts (blocks ≥ 79, skills ≥ 39, top hooks ≥ 10, `_lib` hooks ≥ 2), runs `hooks/_lib/test-gate.sh`, and validates `settings.json`. First real-world "does it work on a fresh machine?" signal — CI previously only ran `--no-execute` dry-runs. v0.21 ship-blocker for any profile that regresses. +- **primitives (v0.20 — brain schema v2 + per-client hint):** + - Brain schema v2 with per-platform `mcp_server` dispatch — a single brain directory can now host binaries for darwin-arm64/darwin-x64/linux-x64/linux-arm64/windows-x64 and `keisei attach` picks the right one automatically. Schema v1 (single string) still accepted for backward-compat. + - `ClientAdapter::post_attach_hint()` — per-client reload instruction, no more hardcoded Claude-Code string in the orchestrator. +- **primitives:** `keisei` CLI MVP — `attach ` + `status` subcommands for mounting a portable exobrain directory into Claude Code. First step of the v0.18 exobrain architecture (multi-client adapter surface prepared; only `claude-code` adapter ships in MVP). +- **primitives (v0.19 — multi-client exobrain):** + - `keisei mount ` — attach a brain to EVERY detected AI client in one shot (Claude Code + Cursor + Continue + Zed). + - `keisei detach` — remove the brain from every client recorded in the marker, preserving user's other MCP/context-server entries. + - `keisei list-adapters` — tabular dump of every registered adapter and whether it's detected on this host. + - 3 new `ClientAdapter` implementations: `cursor` (`.cursor/mcp.json` project-local or `~/.cursor/mcp.json` global), `continue` (`~/.continue/config.{yaml,json}` — YAML preferred, JSON fallback), `zed` (`~/Library/Application Support/Zed/settings.json` on macOS or `~/.config/zed/settings.json` on Linux, under `context_servers`). + - `keisei-attached.toml` schema **v2** — carries a list of `[[attachments]]` (client_type + config_path) instead of a single `client_type`. v1 markers read transparently (auto-migrated in memory). + - New error variants: `AdapterFailed { client, reason }` and `ConfigParseError { path, reason }`. +- Placeholder: CHANGELOG.md generation wired through `kei-changelog` (this file). +- Placeholder: `.github/workflows/release.yml` — tag-driven multi-platform release. +- Placeholder: pre-built-binary install path in `install.sh` (`KEI_SKIP_RUST_BUILD=1`). +- added: `kei-mcp-server` single-binary compile for 5 platforms (linux/darwin/windows × x64/arm64 where available) via `bun build --compile` — v0.18 Phase 1 of the exobrain distribution architecture. Ships as bare binaries + `.sha256` sums on every GitHub release; `install.sh` detects a dropped binary at `_primitives/_rust/target/release/kei-mcp-server--` and skips bun/npm build. Opt-out via `KEI_SKIP_MCP_BUILD=1`. See `_ts_packages/packages/mcp-server/BUILD.md`. + +### Changed +- **primitives (v0.22 Track B — `kei-store` AsyncBackend trait + shared tokio runtime):** + - New `async_backend` module (gated behind `s3` feature) — introduces an `AsyncBackend` sub-trait (4 async methods: `get`/`put`/`list`/`list_recursive` + `label`) and a generic `AsyncBackendStore` wrapper that implements `MemoryStore` on top of any backend. Adding a new cloud backend (GCS, Azure Blob, Bunny Storage, …) is now 6 methods, not a re-invention of the sync-over-async bridge. + - Shared process-global multi-thread tokio runtime via `OnceLock` — 2 worker threads, `enable_io + enable_time`. Replaces the previous per-instance `current_thread` runtime inside `S3CloudStore`, which caused a `block_on` panic when two `S3CloudStore` instances in one process interacted across threads (N=2-Store footgun). + - `S3CloudStore` is now `pub type S3CloudStore = AsyncBackendStore`. Public API (`S3CloudStore::new(cfg)`, `.branch()`, `.current_branch()`, `.key()`, `.backend_name()`) preserved. New `S3AsyncBackend` struct in `s3_cloud/backend.rs` holds the `aws-sdk-s3::Client` and the bucket name; the sync wrapper handles branch-prefix + path-validation + commit-manifest. + - `validate_rel`, `short_hash`, `is_manifest_key` helpers moved from `s3_cloud/keys.rs` into `async_backend` (single source of truth for every future cloud backend). `s3_cloud/keys.rs` kept as a thin re-export shim so external callers and its unit tests keep working unchanged. + - New deps under `s3` feature: `async-trait 0.1` + `tokio` feature `rt-multi-thread`. No change to the default-feature dep graph. + - +7 tests (5 async_backend units + `two_store_instances` + `runtime_is_multi_thread`). Existing 46 tests (31 unit + 9 integration + 6 smoke) unchanged and green. +- Placeholder: plugin / block format refresh targeted for v0.16.0. + +### Security +- **primitives/keisei (v0.19.2 audit polish — M1):** `keisei-attached.toml` marker is now `chmod 0o600` on unix (Windows unchanged — no equivalent bit). The marker carries the resolved `brain_path` and every attached client's config path; restricting it to owner-only closes the residual "other local user can enumerate attached brains" surface. +- **primitives/keisei (v0.19.2 audit polish — L9):** every manifest-sourced string printed by `status` and `attach` (brain name, brain path, client/config paths) is now scrubbed through `display::sanitize_display`, which replaces every ASCII control byte (`< 0x20` or `== 0x7F`) with `?`. Closes the escape-sequence injection surface from a malicious `brain.name` like `"evil\x1b[2Jpayload"` that would otherwise clear the user's terminal or rewrite already-printed lines. +- **primitives/keisei (v0.19.2 audit polish — L12):** `manifest.toml` is now capped at 64 KiB (`Error::ManifestTooLarge { size, max }`). The check runs off `fs::metadata` before `read_to_string` so an attacker-supplied 1 GB file can't exhaust memory inside the toml parser. Legit manifests are ~1 KB; the cap is three orders of magnitude of headroom. + +### Fixed +- Placeholder: hook-bypass edge case follow-up to v0.15.1. +- **primitives/kei-store (v0.21.1 audit wave, HIGH-1):** `S3CloudStore::commit()` now calls a new `list_recursive(prefix)` helper (ListObjectsV2 without `delimiter`) so every nested key under the branch — e.g. `write("traces/x.jsonl", ...)` — contributes to the manifest hash. The previous implementation called `list("")` which under the hood used `delimiter="/"` and hid all sub-directory writes from the commit, silently breaking hash-stability. `commit()` ALSO strips any existing `manifest-*.json` entries from the input so the hash is stable across repeated commits on unchanged data. +- **primitives/kei-store (v0.21.1 audit wave, HIGH-2):** `S3Cfg::access_key_env` + `S3Cfg::secret_key_env` are now wired through to the aws-sdk-s3 builder. When both are set, we resolve the named env vars into an explicit `Credentials` provider and overlay it on the SDK config. Partial configuration (only one of the two set) now returns an error rather than silently ignoring it. Previously both fields were dead — configured users were getting the ambient AWS default chain instead of the named pair. +- **primitives/kei-store (v0.21.1 audit wave, HIGH-5):** all tests that mutate process env on `KEI_STORE_*` vars now take a shared `test_env::ENV_LOCK` mutex (exposed under `cfg(any(test, feature = "s3"))`). Prevents cargo-test parallelism from racing multiple tests on the same env state. `github.rs` dedups onto the shared lock; `s3_cloud/tests.rs` + `tests/s3_smoke.rs` now use it. +- **primitives/keisei (v0.21.1 audit wave, HIGH-3):** `detach.rs` + `mount.rs` now scrub every manifest-sourced string (brain name, brain path, config path, client type, error reason) through `display::sanitize_display` before `println!` / `eprintln!`. `status.rs` + `attach.rs` were already compliant; this closes the L9 regression gap for the other two print sites. Two new integration tests (`detach_sanitizes_control_chars_in_marker_fields`, `mount_sanitizes_control_chars_in_error_reason`) assert source-level guard presence. +- **primitives/keisei (v0.21.1 audit wave, HIGH-4):** extracted `adapters/jsonmcp.rs` (~107 LOC) as the shared JSON merge/remove/persist helper used by the `claude-code`, `cursor`, and `zed` adapters. All three adapters drop from ~170 LOC to ~105 LOC each and share a uniform error-surfacing contract (`Error::ConfigParseError { path }` rather than raw serde_json on parse failure). `continue_adapter.rs` is YAML-based and is unaffected. +- **security (v0.21.1 audit wave, H1):** `scripts/install-actionlint.sh` now verifies SHA-256 of the downloaded tarball before extraction. Per (OS, ARCH) hashes are pinned at the top of the script and documented as the output of `checksums.txt` on the upstream release page. If a hash is marked `SKIP` (documented as `[UNVERIFIED]` pending live fetch), the installer prints a WARNING. Missing `shasum` / `sha256sum` is a hard exit 2 — refuses to install an unverified binary. Env override `ACTIONLINT_SHA256_OVERRIDE=` lets CI inject the hash at runtime. +- **security (v0.21.1 audit wave, H2):** `kei-store::s3_cloud::client::validate_endpoint` rejects loopback / link-local / metadata hosts (`127.0.0.0/8`, `::1`, `169.254.0.0/16`, `fe80::/10`, `metadata.google.internal`, etc.) and plain-HTTP URLs by default. Closes the SSRF / IMDS-leak surface where an attacker-controlled `KEI_STORE_S3_ENDPOINT` pointed at `http://169.254.169.254` would cause the AWS default credential chain to sign requests against the instance metadata endpoint and leak IMDS creds. Env overrides: `KEI_STORE_S3_ALLOW_INTERNAL=1` (local MinIO / tests), `KEI_STORE_S3_ALLOW_INSECURE=1` (plain-HTTP). When a custom endpoint is set, explicit `access_key_env` + `secret_key_env` are REQUIRED — the default credential chain is no longer consulted for non-AWS endpoints. +- **docs (v0.21.1 audit wave, D1):** `docs/USB-BRAIN-GUIDE.md` now warns that **exFAT / FAT32 are NOT safe for multi-client attach** — SQLite WAL shared-memory mmap doesn't work reliably on those filesystems. Recommends APFS / ext4 / NTFS for `keisei mount`. Troubleshooting entry "SQLite corruption on mount-attach" added with recovery steps. +- **docs (v0.21.1 audit wave, D2):** the "~5 MB release binary growth" claim for the `s3` feature is now labelled `[estimate, E5 — not yet measured]` in both CHANGELOG.md and the `s3_cloud` module doc-comment. Prevents over-claim until a real `cargo build --release` before/after comparison is landed. +- **scripts (v0.21.1 audit wave, D3):** `scripts/validate-workflow-shas.sh` now exits 2 when UNVERIFIED pins exist AND no `GITHUB_TOKEN` was provided (rate-limit path). Previously silently returned 0 which masked incomplete verification in CI. +- **primitives/keisei (v0.19 audit hardening):** close 3 Security HIGH + 3 Critic HIGH + 2 Critic MEDIUM findings. Path-escape guard on `mcp_server` + `memory/artifacts/manifests` (absolute / `..` / canonical-mismatch → `PathEscape`); brain-name regex `^[a-z][a-z0-9_-]{0,63}$` (`InvalidName`); symlink-rooted brain inputs rejected (`BrainIsSymlink` — closes USB → `$HOME` pivot); MCP-entry collision check across all 4 adapters (`NameConflict` instead of silent clobber); dropped unused `rusqlite` dep (no C toolchain tail); `BrainPaths.{memory,artifacts,manifests}` relaxed to `Option`; `$KEISEI_HOME`/`$HOME` resolver deduped into `paths.rs` SSoT; `fsx::write_atomic` rewritten on `tempfile::NamedTempFile` for Windows + cross-fs correctness; 5 adversarial integration tests added (16 total pass). +- **primitives/keisei (v0.19.2 polish):** dropped unused `ClientAdapter` imports from `mount.rs` + `detach.rs`; `Error::NotAttached` and `AttachRecord::has_client` now carry explicit `#[allow(dead_code)]` markers documenting that they're reserved for future callers / test-only respectively. `cargo check -p keisei` is warning-clean; integration suite is 19/19 pass (3 new: `marker_file_has_0600_perms_on_unix`, `status_sanitizes_control_chars_in_brain_name`, `manifest_too_large_rejected`). `brain.rs` module-level doc-comment now lists the v0.19 invariants (path confinement / symlink reject / name regex / manifest size cap) and flags schema v2 as v0.20. + +### Security +- Pinned all GitHub Actions (`ci.yml`, `release.yml`) by full commit SHA to defend against CVE-2025-30066-class supply-chain attacks via mutable tag re-pointing. +- Removed `|| bun install` fallback from `release.yml` build-mcp-binary job — lockfile is now strictly REQUIRED (H4 audit finding). +- Added `.github/dependabot.yml` for weekly SHA update PRs on github-actions, npm, and cargo ecosystems. +- **v0.20.1 — workflow validation defense-in-depth:** motivated by the 2026-04-22 incident where `dtolnay/rust-toolchain@3c5f7ea...` SHA-pinned a specific Rust version (1.94.1 branch tip) instead of "install current stable", breaking CI for 4 jobs. Added three gates against the incident class: `scripts/install-actionlint.sh` (pinned v1.7.12 installer, macOS-arm64 + linux-x64), `scripts/lint-workflows.sh` (actionlint runner, advisory if binary missing), `scripts/validate-workflow-shas.sh` (git-ls-remote every `uses: @` pin; exits 1 on `SHA MISSING`, soft-continues on network errors with `[UNVERIFIED]`), `scripts/pre-commit-workflow-lint.sh` (symlink-to-install pre-commit hook, fires only when workflow files are staged), and new `workflow-lint` CI job running the two validators on every push + PR. + +## [0.15.0] — 2026-04-22 + +### Added +- **primitives:** `kei-artifact` typed handoff pipeline (BMAD-style doc passthrough) (`3f303b7`) +- **blocks:** 5 cognitive mode blocks + 2 manifest wirings (`fdfc690`) + +## [0.14.2] — 2026-04-22 + +### Added +- **hooks:** runtime controls via `KEI_DISABLED_HOOKS` + `KEI_HOOK_PROFILE` (v0.14.2) (`1a448e8`) + +### Removed +- genesis-scan from public kit (internal tool, Bundle-only) (`268226b`) + +## [0.14.1] — 2026-04-22 + +### Added +- **ci:** GitHub Actions workflows + `.claude/worktrees` gitignore (`407e8b7`) + +### Changed +- **readme + install:** reconcile all count drift (F4 RELEASE BLOCKER) (`0199fd4`) +- **rust:** misc schema/main refactor in 8 crates (assorted CP splits) (`61448b9`) +- **mock-render:** split `main.rs` 227 LOC into 4 cubes (F5a Constructor Pattern) (`ad5977d`) + +### Fixed +- **kei-auth:** remove `--key` CLI flag (F12 HIGH — `/proc/cmdline` leak) (`b449587`) +- **kei-refactor-engine:** retract 'git apply-ready' claim (F1 RELEASE BLOCKER) (`f50ef43`) +- **kei-store:** path-traversal guard (F2 RELEASE BLOCKER) + S3 stub gate (F7) + GitHub RULE 0.1 guard (F8) (`ad9c53f`) + +## [0.14.0] — 2026-04-22 + +### Added +- **primitives:** 10 Rust crates extracted from LBM (Genesis-scrubbed) (`a5e6649`) +- **ts-packages:** 6 TS packages — MCP server + 5 external-API adapters (`7b647d5`) + +### Changed +- **rust-core:** Constructor-Pattern splits in `kei-router` + `kei-auth` (`afed921`) + +## [0.13.0] — 2026-04-22 + +### Added +- **integration:** deep-sleep wired into MANIFEST + sleep-setup Phase 3b + README (`bcd80f6`) +- **primitives:** 4 Rust crates for deep-sleep — `conflict-scan`, `refactor-engine`, `graph-check`, `store` (`0f75493`) +- **skills:** `/onboard` auto-project-analyze with 3-mode apply (full-auto / step-by-step / full-manual) (`1396139`) + +### Changed +- **readme:** "Why Rust, not Python" paragraph in author note (`92c918a`) +- **readme:** clarify "my sample, not claim of originality" in author note (`47d2448`) +- **readme:** add "double sorry" disclaimer in author note (`3d5d768`) +- **readme:** move "From the author" to opening, expand with transformer-error context (`fd67315`) +- **readme:** add "From the author" note (`b103c3d`) + +## [0.12.0] — 2026-04-22 + +### Added +- **integration:** Phase A incubation wired into trigger + install + README (`d72de64`) +- **skills:** `/sleep-on-it` 6-phase wizard + `kei-sleep-queue` CRUD + incubation prompt (`30df6cb`) + +## [0.11.0] — 2026-04-22 + +### Added +- **integration:** `--with-sleep-sync` flag + README Cloud REM sync section (`1dd05c6`) +- **skills:** `/sleep-setup` 5-phase wizard (click + 1 free-text URL) (`b658f81`) +- **hooks:** `session-end-dump` calls `kei-sleep-sync` after ingest (`1ab39d5`) +- **primitives:** `kei-sleep-setup` wizard + `kei-sleep-sync` helper + trigger template (`4fdaab6`) + +## [0.10.0] — 2026-04-22 + +### Added +- **integration:** register `genesis-scan` in MANIFEST core+full + README + `install.sh` sizing (`93ba0a0`) +- **hooks:** `git-pre-commit-genesis` — template for repo symlink into `.git/hooks/pre-commit` (`670af3f`) +- **primitives:** `genesis-scan` Rust — patent-IP leak detector (CI / pre-commit) (`5db8548`) +- **integration:** wire `kei-memory` into MANIFEST + settings-snippet + README for v0.10 (`0b5da5a`) +- **skills:** `/self-audit` 5-phase triage pipeline (`334a867`) +- **hooks:** 3 self-audit triggers — stop / milestone / error-spike (`a5c3896`) +- **primitives:** `kei-memory` Rust crate — offline session analyzer (Genesis-clean) (`448fc07`) + +## [0.9.1] — 2026-04-21 + +### Added +- **install:** interactive menu (whiptail / dialog / plain) + confirm screen + `--yes` / `--no-execute` (`4809269`) + +## [0.9.0] — 2026-04-21 + +### Added +- **install:** modular profiles + `--add` / `--remove` / `--list` incremental install (`b1b8de0`) +- **primitives:** `MANIFEST.toml` — SSoT for 21 primitives + 6 profiles (`764a999`) + +### Changed +- **readme:** install profiles table + migration note for v0.9.0 (`47931a3`) + +> BREAKING: default install profile is now `minimal` (was `full`). +> Re-run with `--profile=full` to preserve prior behaviour. + +## [0.8.0] — 2026-04-21 + +### Added +- **install:** copy `_primitives/` + build Rust workspace; register `agent-fork-logger` + `site-wysiwyd` hooks (`b0d9389`) +- **hooks:** `site-wysiwyd-check` PostToolUse(Edit | Write) drift advisory (`c2041b4`) +- **skills:** `/site-create` pipeline (phases 0–4 — phases 5–6 deferred) (`839ae57`) + +### Changed +- **compose-solution:** prior-art grep paths + phase-5 cross-refs for 10 pipelines + 21 primitives (`f664cbc`) +- **readme:** v0.8.0 — 73 blocks / 34 skills / 21 primitives / 6 hooks / 11 bridges + pipelines section (`ed7d566`) + +[Unreleased]: https://github.com/KeiSei84/KeiSeiKit/compare/v0.15.0...HEAD +[0.15.0]: https://github.com/KeiSei84/KeiSeiKit/compare/v0.14.2...v0.15.0 +[0.14.2]: https://github.com/KeiSei84/KeiSeiKit/compare/v0.14.1...v0.14.2 +[0.14.1]: https://github.com/KeiSei84/KeiSeiKit/compare/v0.14.0...v0.14.1 +[0.14.0]: https://github.com/KeiSei84/KeiSeiKit/compare/v0.13.0...v0.14.0 +[0.13.0]: https://github.com/KeiSei84/KeiSeiKit/compare/v0.12.0...v0.13.0 +[0.12.0]: https://github.com/KeiSei84/KeiSeiKit/compare/v0.11.0...v0.12.0 +[0.11.0]: https://github.com/KeiSei84/KeiSeiKit/compare/v0.10.0...v0.11.0 +[0.10.0]: https://github.com/KeiSei84/KeiSeiKit/compare/v0.9.1...v0.10.0 +[0.9.1]: https://github.com/KeiSei84/KeiSeiKit/compare/v0.9.0...v0.9.1 +[0.9.0]: https://github.com/KeiSei84/KeiSeiKit/compare/v0.8.0...v0.9.0 +[0.8.0]: https://github.com/KeiSei84/KeiSeiKit/releases/tag/v0.8.0 diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/LICENSE b/_archive/forks/2026-04-23/ci-cost-fix-w15/LICENSE new file mode 100644 index 0000000..2434186 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Claude Code KeiSeiKit contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/PLUGIN.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/PLUGIN.md new file mode 100644 index 0000000..35569a8 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/PLUGIN.md @@ -0,0 +1,78 @@ +# KeiSeiKit — Anthropic Claude Code plugin format + +This document describes the plugin-format install path (v0.16+) and how it relates to the classic `./install.sh` path. Both paths are supported; use whichever fits. + +## TL;DR + +```bash +# One-time +/plugin marketplace add KeiSei84/KeiSeiKit +# Install +/plugin install keisei@keisei-marketplace +``` + +The plugin auto-registers: agents, skills, hooks, and the MCP server. No manual `~/.claude/settings.json` edits. No `install.sh` needed for the core (non-primitive) experience. + +## Layout + +The repo follows the [Anthropic Claude Code plugin spec](https://code.claude.com/docs/en/plugins): + +``` +.claude-plugin/ + plugin.json # plugin manifest (name, version, author, license, keywords) + marketplace.json # marketplace manifest — lets this repo serve as a marketplace source + mcp-template.json # template for .mcp.json (copy to repo root; see "MCP prerequisite" below) +agents/ # auto-discovered by Claude Code at plugin-install time +skills//SKILL.md # auto-discovered +hooks/hooks.json # PreToolUse / PostToolUse / Stop hooks with ${CLAUDE_PLUGIN_ROOT} paths +.mcp.json # MCP server registration (see prerequisite note) +``` + +Paths inside `hooks/hooks.json` use `${CLAUDE_PLUGIN_ROOT}` (expanded by Claude Code at runtime to the plugin install directory) rather than absolute `$HOME/.claude/hooks/...` paths. This lets the same hooks ship unchanged whether the plugin is installed from GitHub, npm, or a local path. + +## Plugin install vs classic install — what differs + +| Feature | Plugin install | Classic `./install.sh` | +|---|---|---| +| Agents registered | yes, automatic | yes, copied to `~/.claude/agents/` | +| Skills registered | yes, automatic | yes, copied to `~/.claude/skills/` | +| Hooks wired | yes, via `hooks/hooks.json` | requires `--activate-hooks` (jq-merge of `settings-snippet.json`) | +| MCP server | yes, via `.mcp.json` (once `@keisei/mcp-server` is published) | same | +| 36 Rust primitives | **no** — plugin ships manifest sources only; no cargo build | yes, `--profile=` builds the selected set | +| 13 shell primitives | **no** | yes, copied to `~/.claude/agents/_primitives/` | +| Disk footprint | ~2 MB (plugin cache) | ~2 MB minimal up to ~200 MB full | +| Update path | `/plugin update keisei` | `git pull && ./install.sh` | +| Update visibility | Claude Code shows version change | silent | + +**Bottom line:** plugin install is the right default for the agent-kit experience (agents + skills + hooks). For the Rust primitives (`tomd`, `kei-ledger`, `provision-hetzner`, `kei-migrate`, etc.), fall back to the classic installer or run it alongside the plugin — the two don't collide because the plugin namespaces into its own install dir and the classic installer writes to `~/.claude/`. + +## Prerequisites + +**For plugin install:** +- Claude Code 2.1+ (check with `claude --version`) +- Network access to `github.com/KeiSei84/KeiSeiKit` on `/plugin marketplace add` + +**For the MCP server subset:** +- `@keisei/mcp-server` published to npm — **STATUS: not yet published as of v0.16.0.** The `.mcp.json` entry is structurally correct and will activate automatically once the package is published. Until then, the `keisei` MCP server simply won't appear in your tool list — the agents, skills, and hooks all work without it. +- Node.js 18+ (for `npx` to fetch the server on demand) + +**For the Rust primitives (classic install only):** +- Rust stable, `jq`, plus the soft-deps listed in the main README per-profile table. + +## Known limitations + +1. **Rust primitives not auto-installed.** The plugin format doesn't currently express "also run `cargo build` at install time". We ship the manifest sources in-repo so that users who want the primitives can run `./install.sh --profile=full` alongside the plugin. A future version may add pre-built release binaries for common platforms (macOS arm64/x86_64, Linux x86_64) into `bin/` so the plugin can ship primitives without a cargo step. +2. **`@keisei/mcp-server` not yet on npm.** The `.mcp.json` entry is the canonical intent, but the package needs publishing first. See `_ts_packages/packages/mcp-server/README.md` for the publish pipeline. +3. **Hooks use `${CLAUDE_PLUGIN_ROOT}`.** This is the official Claude Code plugin variable. Older Claude Code versions (<2.1) that predate plugin support will not expand this variable — stick with classic install on those versions. +4. **No version-pinning yet.** `/plugin install keisei@keisei-marketplace` installs the default branch HEAD. For reproducible team installs, add the `--ref=` flag once it lands in Claude Code (currently in the spec per the extension schema `ref` field). + +## Feedback & bugs + +Open an issue at [github.com/KeiSei84/KeiSeiKit/issues](https://github.com/KeiSei84/KeiSeiKit/issues). A well-formed problem description is already half the solution. + +## References + +- [Anthropic Claude Code plugins docs](https://code.claude.com/docs/en/plugins) +- `README.md` — main install guide (plugin section is the new default) +- `settings-snippet.json` — retained for classic install; the plugin path does not use it +- `install.sh --help` — classic installer options, now with a plugin-first banner diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/README.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/README.md new file mode 100644 index 0000000..a792733 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/README.md @@ -0,0 +1,116 @@ +# KeiSeiKit + +> A living neural structure you install next to your AI assistant. +> A mini-universe where any user, from any domain, can discover a new primitive or grow a new class of agent. + +KeiSeiKit is not a toolkit. It is a substrate for cognitive growth — an opinionated neural structure of Kei that a developer installs, shapes, and extends. It sleeps when you sleep, remembers what you decided yesterday, heals mistakes it notices in itself, and runs from a directory you can put on a USB stick and carry between machines. + +## Install in one line + +```bash +/plugin marketplace add KeiSei84/KeiSeiKit +/plugin install keisei@keisei-marketplace +``` + +Twelve agents appear in Claude Code, forty-three skills become callable as `/self-audit`, `/sleep-on-it`, `/compose-solution`, `/new-project`, `/spawn-agent` — and the nightly consolidation cycle is wired. Other install paths: [docs/INSTALL.md](./docs/INSTALL.md). + +## The five biological principles + +KeiSeiKit is organised around five properties a living neural system has, and most software doesn't. Each principle maps to concrete code shipped in this repo. + +- **DNA and taxonomy.** Every agent invocation gets a 80-character deterministic identifier composed from role, capability bitmap, scope hash, task-body hash, and per-spawn nonce. Every primitive and agent is tagged along seven orthogonal facets — kingdom, mechanism, domain, layer, stage, stability, language — so the graph is queryable along any axis. See `_primitives/_rust/kei-agent-runtime/src/dna.rs` and [docs/TAXONOMY.md](./docs/TAXONOMY.md). + +- **Creator lineage.** Every row in the agent ledger carries `creator_id` and `fork_parent_id`. Who spawned what, from which parent, under which DNA — traceable. No orphan artefacts, no "where did this come from". See `_primitives/_rust/kei-ledger/src/schema.rs` migration v4. + +- **Sleep. Three phases, every night.** Phase A is incubation: during the day you drop tasks into `/sleep-on-it`; at 03:00 a remote Claude agent works on them. Phase B is REM: the same agent reads the day's JSONL traces, extracts cross-session patterns, and writes a report. Phase C is NREM (every seven days by default): a conflict-scan plus refactor-engine propose a clean-up branch. Nothing auto-injects into the next session — you `git pull`, read, decide. See [docs/SLEEP-LAYER.md](./docs/SLEEP-LAYER.md). + +- **Self-healing.** Three passive hooks (`session-end-dump`, `milestone-commit-hook`, `error-spike-detector`) feed a session retrospective. When the same mistake reappears twice, `/escalate-recurrence` offers to codify it as rule plus wiki entry plus hook — at the severity you pick. Silent-first: the first ten sessions log without prompting, so the baseline is real. + +- **Growth by composition.** `/new-project` scaffolds a project across four phases with branch + ledger + artefact bundle per fork. `/spawn-agent` emits a new agent manifest. `/compose-solution` decomposes a free-text problem, greps existing atoms for prior art, and proposes the smallest artefact — agent, skill, hook, rule, block, or pipeline — that closes the gap. Every session leaves the substrate slightly larger than it found it. + +The deeper theory — why these five and not others, and the analogy with hippocampal / cortical dynamics — is in [docs/PHILOSOPHY.md](./docs/PHILOSOPHY.md). + +## Four layers + +``` +4. Portability USB stick / iCloud / S3 — keisei mount, any machine +3. Sleep Phase A (incubation) → Phase B (REM) → Phase C (NREM) +2. Cognition DNA + ledger + taxonomy + memory + self-audit +1. Substrate atoms, agents, skills, hooks, blocks, bridges +``` + +Layer 1 is the body — the reusable parts. Layer 2 is identity and memory. Layer 3 is overnight learning. Layer 4 is the ability to pick up and move. + +## What ships (verified counts) + +- **36 Rust primitives** — pure Rust workspace crates, release-stripped, each ≤2 MB, no Python runtime. Covers the ledger, memory, router, migrate, agent runtime, forge, spawn/replay, sleep infrastructure, and the `keisei` CLI. +- **12 agents** (`kei-*` namespaced) — code-implementer, infra-implementer, ml-implementer, critic, validator, security-auditor, architect, researcher, ml-researcher, cost-guardian, modal-runner, fal-ai-runner. All carry a `substrate_role` facet. +- **43 skills** — one-command pipelines including `/new-project`, `/spawn-agent`, `/self-audit`, `/sleep-on-it`, `/sleep-setup`, `/compose-solution`, `/schema-design`, `/api-design`, `/auth-setup`, `/observability-setup`, `/ci-scaffold`, `/pr-review`, `/debug-deep`. +- **12 hooks** — pre-commit safety net, always on: assembler, validator, no-hand-edit-agents, tomd-preread, agent-fork-logger, orchestrator-dirty-check, site-wysiwyd-check, session-end-dump, milestone-commit-hook, error-spike-detector, and two capability gates. +- **82 behavioural blocks** — tested patterns composable into your own agents via `blocks = [...]` in a manifest. +- **11 capabilities / 5 roles** — the capability-graph that agents resolve at spawn time. +- **11 cross-tool bridges** — one source of truth emits `.cursorrules`, Cursor MDC, `AGENTS.md`, Copilot, Windsurf, Junie, Continue, Gemini, Aider, Replit. Switch AI tools without rewriting your setup. +- **500+ tests** across the Rust workspace, green on `cargo test --workspace` on every supported OS. + +Every number is regenerated from source by `scripts/regen-counts.sh` — no manual drift. + +## Domain-agnostic by construction + +KeiSeiKit has no hardcoded domain. The same substrate ships unchanged for biology, finance, law, medicine, music, research, game dev, ops. What's domain-aware lives in the *blocks* — reusable markdown cubes you compose into an agent manifest — and the assembler rebuilds the affected agents when a block changes. If you work in a domain the kit doesn't yet cover, the path to first-class support is a manifest plus a handful of blocks, not a fork. + +## How to start + +**Install:** the two-line plugin command above. Other paths — full profile, dev profile, MCP-only, manual, Nix, Docker — are in [docs/INSTALL.md](./docs/INSTALL.md). + +**Discover a new primitive:** +``` +/compose-solution "I want a hook that blocks rm -rf ~/ in any Bash call" +``` +The skill greps existing atoms, proposes the smallest intervention, drafts a block if nothing matches, and hands off to `/escalate-recurrence` to persist it. + +**Grow a new agent:** +``` +/spawn-agent +``` +Four phases: role, task, scope, emit. The wizard writes the manifest, composes its DNA, forks a ledger row, and the assembler generates the agent markdown Claude Code will pick up. + +**Start a new project:** +``` +/new-project +``` +Four phases: intake, fork skeleton, parallel execution (orchestrator owns git per RULE 0.13), merge ceremony with per-branch AskUserQuestion. + +## Portability + +Every primitive is a pure Rust binary ≤2 MB. Every hook is POSIX shell. Every skill is markdown. Every manifest is TOML. The `keisei` CLI mounts a brain-directory into Claude Code + Cursor + Continue + Zed simultaneously; the directory can live on a USB stick, iCloud, S3, or any filesystem. Move it to another machine and the same agents, the same memory, the same artefact bundles are there. [docs/USB-BRAIN-GUIDE.md](./docs/USB-BRAIN-GUIDE.md). + +## Under the hood + +Constructor Pattern: one file, one concern. TOML manifests are the source of truth. A Rust assembler compiles them to the Markdown Claude Code expects. When a block changes, a PostToolUse hook rebuilds every affected agent. Rust is the backbone because the type system catches the class of mistakes LLMs most often introduce — `None` vs `[]`, missing `.await`, unhandled `Result` — at compile time, so they cannot ship. Python is reserved for the places where Python is genuinely better. + +Build pipeline, cross-tool bridge mechanics, meta-composer internals, sleep-layer details → [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md). + +## Docs + +| | | +|---|---| +| [PHILOSOPHY.md](./docs/PHILOSOPHY.md) | The biological principles, in depth | +| [INSTALL.md](./docs/INSTALL.md) | All install paths, profiles, `keisei` CLI, hook controls | +| [ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Build pipeline, bridges, meta-composer | +| [REFERENCE.md](./docs/REFERENCE.md) | Every primitive, hook, skill with flags and exit codes | +| [SLEEP-LAYER.md](./docs/SLEEP-LAYER.md) | Phase A / B / C nightly cycle + self-audit | +| [TAXONOMY.md](./docs/TAXONOMY.md) | The seven-facet vocabulary | +| [SUBSTRATE-SCHEMA.md](./docs/SUBSTRATE-SCHEMA.md) | Atom contract | +| [SECURITY.md](./docs/SECURITY.md) | Threat model + mitigations | +| [USB-BRAIN-GUIDE.md](./docs/USB-BRAIN-GUIDE.md) | Portable brain — macOS / Linux / Windows | +| [WHY.md](./docs/WHY.md) | The full story of why this exists | +| [CHANGELOG.md](./CHANGELOG.md) | What changed, version by version | +| [PLUGIN.md](./PLUGIN.md) | Anthropic plugin-format details | + +## Authorship + +Built by Denis Parfionovich () at KeiLab, while running 4–8 parallel Claude Code terminals every day. What you are looking at is the scaffolding that makes that possible — shared now so you don't have to build your own. Forks and pull requests welcome. + +## License + +MIT. See [LICENSE](./LICENSE). diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/.gitignore b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/.gitignore new file mode 100644 index 0000000..4fffb2f --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/.gitignore @@ -0,0 +1,2 @@ +/target +/Cargo.lock diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/Cargo.toml b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/Cargo.toml new file mode 100644 index 0000000..5324c47 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/Cargo.toml @@ -0,0 +1,22 @@ +[package] +name = "agent-assembler" +version = "0.1.0" +edition = "2024" +description = "Constructor-Pattern assembler for Claude agent .md files" + +[[bin]] +name = "assemble" +path = "src/main.rs" + +[dependencies] +serde = { version = "1", features = ["derive"] } +toml = "0.8" + +[dev-dependencies] +insta = "1" +tempfile = "3" + +[profile.release] +opt-level = "z" +lto = true +strip = true diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/assembler.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/assembler.rs new file mode 100644 index 0000000..806f73a --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/assembler.rs @@ -0,0 +1,133 @@ +//! Agent assembler — composes markdown from manifest + blocks. +//! Output is deterministic: same manifest + blocks → byte-identical .md. + +use crate::manifest::Manifest; +use crate::substrate; +use std::fs; +use std::path::Path; + +pub fn assemble(m: &Manifest, blocks_dir: &Path) -> Result { + // Substrate role expansion uses the kit root (parent of _blocks/). + let root = blocks_dir + .parent() + .ok_or_else(|| "blocks_dir has no parent (can't locate _roles/ and _capabilities/)".to_string())?; + + let mut out = String::new(); + + write_frontmatter(m, &mut out); + write_role(m, &mut out); + write_substrate(m, root, &mut out)?; + write_blocks(m, blocks_dir, &mut out)?; + write_domain_scope(m, &mut out); + write_handoffs(m, &mut out); + write_output_format(m, &mut out); + write_forbidden(m, &mut out); + write_references(m, &mut out); + + Ok(out) +} + +fn write_substrate(m: &Manifest, root: &Path, out: &mut String) -> Result<(), String> { + let Some(role) = &m.substrate_role else { + return Ok(()); + }; + let section = substrate::build_substrate_section(root, role)?; + out.push_str(§ion); + Ok(()) +} + +fn write_frontmatter(m: &Manifest, out: &mut String) { + let desc = m.description.replace('\n', " "); + out.push_str("---\n"); + out.push_str(&format!("name: {}\n", m.name)); + out.push_str(&format!("description: {}\n", desc.trim())); + out.push_str(&format!("tools: {}\n", m.tools.join(", "))); + out.push_str(&format!("model: {}\n", m.model)); + out.push_str("---\n\n"); + out.push_str(&format!( + "\n\n", + m.name + )); +} + +fn write_role(m: &Manifest, out: &mut String) { + out.push_str("# ROLE\n\n"); + out.push_str(m.role.trim()); + out.push_str("\n\n"); +} + +fn write_blocks(m: &Manifest, blocks_dir: &Path, out: &mut String) -> Result<(), String> { + for block in &m.blocks { + let path = blocks_dir.join(format!("{block}.md")); + let text = fs::read_to_string(&path) + .map_err(|e| format!("read {}: {e}", path.display()))?; + out.push_str(text.trim()); + out.push_str("\n\n"); + } + Ok(()) +} + +fn write_domain_scope(m: &Manifest, out: &mut String) { + out.push_str("# DOMAIN SCOPE\n\n**In:**\n"); + for item in &m.domain_in { + out.push_str(&format!("- {item}\n")); + } + out.push_str("\n**Out (hand off):**\n"); + for h in &m.handoff { + out.push_str(&format!("- `{}` — {}\n", h.target, h.trigger)); + } + out.push('\n'); +} + +fn write_handoffs(m: &Manifest, out: &mut String) { + out.push_str("# HANDOFFS\n\n"); + for h in &m.handoff { + out.push_str(&format!("- **{}** — {}\n", h.target, h.trigger)); + } + out.push('\n'); +} + +fn write_output_format(m: &Manifest, out: &mut String) { + out.push_str("# OUTPUT FORMAT\n\n```\n"); + out.push_str(&format!("=== {} REPORT ===\n", m.name.to_uppercase())); + out.push_str("Goal: \n"); + out.push_str("Scope: \n"); + out.push_str("Plan: \n"); + out.push_str("Executed: \n"); + out.push_str("Verify: \n"); + out.push_str("Evidence grades: \n"); + out.push_str("Handoffs made: \n"); + for extra in &m.output_extra_fields { + out.push_str(extra); + out.push('\n'); + } + out.push_str("Blockers / next: \n"); + out.push_str("```\n\n"); +} + +fn write_forbidden(m: &Manifest, out: &mut String) { + out.push_str("# FORBIDDEN\n\n"); + for item in &m.forbidden_domain { + out.push_str(&format!("- {item}\n")); + } + out.push('\n'); +} + +fn write_references(m: &Manifest, out: &mut String) { + out.push_str("# REFERENCES\n\n"); + out.push_str("- `~/.claude/CLAUDE.md` — baseline umbrella\n"); + out.push_str("- `~/.claude/memory/MEMORY.md` — memory index (adjust if your Claude Code user-slug path differs)\n"); + if let Some(mp) = &m.memory_project { + out.push_str(&format!( + "- `~/.claude/memory/{mp}` — project memory (adjust path if needed)\n" + )); + } + if let Some(pc) = &m.project_claudemd { + out.push_str(&format!("- `{pc}` — project CLAUDE.md\n")); + } + if let Some(refs) = &m.references { + for r in &refs.extra { + out.push_str(&format!("- `{r}`\n")); + } + } +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/main.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/main.rs new file mode 100644 index 0000000..6173465 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/main.rs @@ -0,0 +1,116 @@ +//! CLI entry: build [--validate] [--in-place] [ ...] +//! +//! Default: read all _manifests/*.toml, write to _generated/*.md. +//! --in-place: write to agents/.md (replaces generated file). +//! --validate: parse + validate only, no output. +//! Positional args: specific manifest files to process. + +mod assembler; +mod manifest; +mod placeholders; +mod schemas_export; +mod substrate; +mod validator; + +use manifest::Manifest; +use std::path::{Path, PathBuf}; +use std::process::ExitCode; +use std::{env, fs}; + +fn main() -> ExitCode { + let root = root_dir(); + let blocks = root.join("_blocks"); + let manifests = root.join("_manifests"); + let generated = root.join("_generated"); + + let args: Vec = env::args().skip(1).collect(); + let validate_only = args.iter().any(|a| a == "--validate"); + let in_place = args.iter().any(|a| a == "--in-place"); + let targets: Vec<&String> = args.iter().filter(|a| !a.starts_with("--")).collect(); + + let paths: Vec = if targets.is_empty() { + collect_manifests(&manifests) + } else { + targets.iter().map(|t| PathBuf::from(t)).collect() + }; + + if paths.is_empty() { + eprintln!("no manifests found in {}", manifests.display()); + return ExitCode::from(1); + } + + let mut errors = 0u32; + for path in &paths { + match process(path, &blocks, &generated, &root, validate_only, in_place) { + Ok(out_path) => { + let name = path.file_name().unwrap_or_default().to_string_lossy(); + match out_path { + Some(p) => println!("OK {name} → {}", relative_to(&p, root.parent().unwrap_or(root.as_path()))), + None => println!("OK {name}"), + } + } + Err(e) => { + eprintln!("FAIL {}: {e}", path.display()); + errors += 1; + } + } + } + + if errors > 0 { ExitCode::from(1) } else { ExitCode::SUCCESS } +} + +fn process( + path: &Path, + blocks: &Path, + generated: &Path, + root: &Path, + validate_only: bool, + in_place: bool, +) -> Result, String> { + let text = fs::read_to_string(path).map_err(|e| format!("read: {e}"))?; + let m: Manifest = toml::from_str(&text).map_err(|e| format!("parse: {e}"))?; + validator::validate(&m, blocks)?; + + if validate_only { + return Ok(None); + } + + let content = assembler::assemble(&m, blocks)?; + let out_path = if in_place { + root.join(format!("{}.md", m.name)) + } else { + fs::create_dir_all(generated).map_err(|e| format!("mkdir generated: {e}"))?; + generated.join(format!("{}.md", m.name)) + }; + fs::write(&out_path, content).map_err(|e| format!("write {}: {e}", out_path.display()))?; + Ok(Some(out_path)) +} + +fn root_dir() -> PathBuf { + // Priority: AGENT_ROOT env > HOME/.claude/agents default. + // (exe-relative would break when the binary is symlinked or copied.) + if let Ok(v) = env::var("AGENT_ROOT") { + return PathBuf::from(v); + } + PathBuf::from(env::var("HOME").unwrap_or_default()).join(".claude/agents") +} + +fn collect_manifests(dir: &Path) -> Vec { + let mut out = Vec::new(); + if let Ok(rd) = fs::read_dir(dir) { + for entry in rd.flatten() { + let p = entry.path(); + if p.extension().and_then(|e| e.to_str()) == Some("toml") { + out.push(p); + } + } + } + out.sort(); + out +} + +fn relative_to(path: &Path, base: &Path) -> String { + path.strip_prefix(base) + .map(|p| p.display().to_string()) + .unwrap_or_else(|_| path.display().to_string()) +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/manifest.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/manifest.rs new file mode 100644 index 0000000..75821ec --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/manifest.rs @@ -0,0 +1,50 @@ +//! Manifest struct — deserialized from _manifests/*.toml. +//! One manifest = one agent. Source of truth; the .md file is generated. + +use serde::Deserialize; + +#[derive(Deserialize)] +pub struct Manifest { + pub name: String, + pub description: String, + pub tools: Vec, + pub model: String, + pub role: String, + pub blocks: Vec, + /// v0.16 (phase 5): agent substrate role. When present, assembler loads + /// `_roles/.toml` and emits each capability's `text.md` + /// fragment between the ROLE section and the existing blocks. Optional + /// for backward compatibility with pre-substrate manifests. + #[serde(default)] + pub substrate_role: Option, + pub domain_in: Vec, + pub forbidden_domain: Vec, + pub handoff: Vec, + #[serde(default)] + pub output_extra_fields: Vec, + pub memory_project: Option, + pub project_claudemd: Option, + pub references: Option, + /// v0.15: optional typed-artifact schema this agent emits on completion. + /// Must be one of the names in `artifact_schemas::KNOWN`. + #[serde(default)] + pub produces_artifact: Option, +} + +#[derive(Deserialize)] +pub struct Handoff { + pub target: String, + pub trigger: String, + /// v0.15: optional schema name the target consumes from this handoff. + #[serde(default)] + pub expects_artifact: Option, + /// v0.15: optional schema name this agent produces for the target. + #[serde(default)] + pub produces_artifact: Option, +} + +#[derive(Deserialize)] +pub struct References { + #[serde(default)] + pub extra: Vec, +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/placeholders.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/placeholders.rs new file mode 100644 index 0000000..8fab5bd --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/placeholders.rs @@ -0,0 +1,128 @@ +//! Placeholder check — reject unsubstituted `{{PLACEHOLDER}}` tokens. +//! +//! Constructor Pattern: one cube = one validation concern. +//! Extracted from `validator.rs` to keep that file under 200 LOC. + +use crate::manifest::Manifest; + +/// Reject manifests that still carry `{{PLACEHOLDER}}` tokens — the wizard +/// should have substituted them. Matches `{{...}}` conservatively (not +/// single braces). +pub fn check(m: &Manifest) -> Result<(), String> { + let check = |field: &str, value: &str| -> Result<(), String> { + if contains_placeholder(value) { + Err(format!( + "Unsubstituted template placeholder in field '{field}': {value}. Did the wizard skip a substitution?" + )) + } else { + Ok(()) + } + }; + + check("name", &m.name)?; + check("description", &m.description)?; + check("model", &m.model)?; + check("role", &m.role)?; + for (i, t) in m.tools.iter().enumerate() { + check(&format!("tools[{i}]"), t)?; + } + for (i, b) in m.blocks.iter().enumerate() { + check(&format!("blocks[{i}]"), b)?; + } + for (i, d) in m.domain_in.iter().enumerate() { + check(&format!("domain_in[{i}]"), d)?; + } + for (i, d) in m.forbidden_domain.iter().enumerate() { + check(&format!("forbidden_domain[{i}]"), d)?; + } + for (i, h) in m.handoff.iter().enumerate() { + check(&format!("handoff[{i}].target"), &h.target)?; + check(&format!("handoff[{i}].trigger"), &h.trigger)?; + } + for (i, o) in m.output_extra_fields.iter().enumerate() { + check(&format!("output_extra_fields[{i}]"), o)?; + } + if let Some(v) = &m.substrate_role { + check("substrate_role", v)?; + } + if let Some(v) = &m.memory_project { + check("memory_project", v)?; + } + if let Some(v) = &m.project_claudemd { + check("project_claudemd", v)?; + } + if let Some(r) = &m.references { + for (i, e) in r.extra.iter().enumerate() { + check(&format!("references.extra[{i}]"), e)?; + } + } + Ok(()) +} + +fn contains_placeholder(s: &str) -> bool { + if let Some(start) = s.find("{{") { + if s[start + 2..].contains("}}") { + return true; + } + } + false +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::manifest::{Handoff, Manifest}; + + fn base() -> Manifest { + Manifest { + name: "test".into(), + description: "d".into(), + tools: vec!["Read".into()], + model: "opus".into(), + role: "r".into(), + blocks: vec!["baseline".into(), "evidence-grading".into(), "memory-protocol".into()], + domain_in: vec!["x".into()], + forbidden_domain: vec!["y".into()], + handoff: vec![Handoff { + target: "a".into(), + trigger: "b".into(), + expects_artifact: None, + produces_artifact: None, + }], + output_extra_fields: vec![], + memory_project: None, + project_claudemd: None, + references: None, + produces_artifact: None, + substrate_role: None, + } + } + + #[test] + fn rejects_placeholder_in_memory_project() { + let mut m = base(); + m.memory_project = Some("{{MEMORY_PROJECT}}".into()); + let err = check(&m).unwrap_err(); + assert!(err.contains("memory_project"), "err = {err}"); + assert!(err.contains("{{MEMORY_PROJECT}}"), "err = {err}"); + } + + #[test] + fn accepts_single_braces() { + let mut m = base(); + m.description = "hello {world}".into(); + assert!(check(&m).is_ok()); + } + + #[test] + fn accepts_empty_manifest() { + assert!(check(&base()).is_ok()); + } + + #[test] + fn rejects_placeholder_in_role() { + let mut m = base(); + m.role = "do {{THING}}".into(); + assert!(check(&m).is_err()); + } +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/schemas_export.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/schemas_export.rs new file mode 100644 index 0000000..025c726 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/schemas_export.rs @@ -0,0 +1,136 @@ +//! Dynamic artifact-schema whitelist loader. +//! +//! v0.16: the assembler previously hardcoded the 5 builtin schema names. +//! That blocked any user who registered a custom schema via +//! `kei-artifact register-schema` — the assembler would reject manifests +//! referencing it. This cube loads the current registry from the export +//! file written by `kei-artifact export-schemas`. +//! +//! Priority (first hit wins): +//! 1. `$AGENT_ROOT/artifacts/schemas.json` (derived from `blocks_dir.parent()`) +//! 2. `~/.claude/agents/artifacts/schemas.json` +//! 3. Built-in fallback (5 names) +//! +//! Export file format: `{"schemas": ["spec", "plan", ...]}`. Builtins are +//! always unioned in, so a hand-crafted export cannot drop a core schema. +//! +//! Constructor Pattern: no dependency on serde_json — minimal hand-parser +//! keeps the assembler lean and free of transitive deps. + +use std::collections::BTreeSet; +use std::path::{Path, PathBuf}; + +/// Canonical artifact schema names shipped by `kei-artifact`. +/// +/// MIRROR OF `kei-artifact/src/schemas.rs::BUILTIN` (by design — assembler +/// crate must not link to the runtime primitive). Drift is detected by the +/// `builtin_schemas_do_not_drift` test in `validator.rs`. +pub const BUILTIN: &[&str] = &["spec", "plan", "patch", "review", "research"]; + +/// Union of builtins + any names found in an on-disk export, as a sorted set. +pub fn load(blocks_dir: &Path) -> BTreeSet { + load_with_home(blocks_dir, std::env::var("HOME").ok().as_deref()) +} + +/// Test-friendly variant that accepts an explicit HOME override. +pub fn load_with_home(blocks_dir: &Path, home: Option<&str>) -> BTreeSet { + let mut out: BTreeSet = BUILTIN.iter().map(|s| (*s).to_string()).collect(); + for path in candidate_paths(blocks_dir, home) { + if let Some(names) = read_export(&path) { + out.extend(names); + break; + } + } + out +} + +fn candidate_paths(blocks_dir: &Path, home: Option<&str>) -> Vec { + let mut v = Vec::new(); + if let Some(root) = blocks_dir.parent() { + v.push(root.join("artifacts/schemas.json")); + } + if let Some(h) = home { + v.push(PathBuf::from(h).join(".claude/agents/artifacts/schemas.json")); + } + v +} + +fn read_export(path: &Path) -> Option> { + let text = std::fs::read_to_string(path).ok()?; + parse_export(&text) +} + +/// Minimal parser for `{"schemas": ["a", "b"]}`. Tolerant of whitespace. +pub fn parse_export(text: &str) -> Option> { + let body = text.trim(); + let key = "\"schemas\""; + let i = body.find(key)?; + let rest = &body[i + key.len()..].trim_start_matches(|c: char| c == ':' || c.is_whitespace()); + let open = rest.find('[')?; + let close = rest[open..].find(']')?; + let inner = &rest[open + 1..open + close]; + let mut names = Vec::new(); + for tok in inner.split(',') { + let t = tok.trim().trim_matches('"').trim(); + if !t.is_empty() { + names.push(t.to_string()); + } + } + Some(names) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn parse_happy_path() { + let body = r#"{"schemas": ["spec", "plan", "custom-one"]}"#; + assert_eq!(parse_export(body).unwrap(), vec!["spec", "plan", "custom-one"]); + } + + #[test] + fn parse_whitespace_and_newlines() { + let body = "{\n \"schemas\" : [\n \"a\",\n \"b\"\n ]\n}\n"; + assert_eq!(parse_export(body).unwrap(), vec!["a", "b"]); + } + + #[test] + fn parse_rejects_malformed() { + assert!(parse_export("{}").is_none()); + assert!(parse_export(r#"{"schemas":"spec"}"#).is_none()); + } + + #[test] + fn load_falls_back_to_builtin_when_no_export() { + let tmp = tempfile::tempdir().unwrap(); + let blocks_dir = tmp.path().join("_blocks"); + std::fs::create_dir_all(&blocks_dir).unwrap(); + // Isolated HOME (under tmp) — no real export file at that path. + let home = tmp.path().to_string_lossy().to_string(); + let known = load_with_home(&blocks_dir, Some(&home)); + for s in BUILTIN { + assert!(known.contains(*s)); + } + assert_eq!(known.len(), BUILTIN.len()); + } + + #[test] + fn load_unions_with_custom_export() { + let tmp = tempfile::tempdir().unwrap(); + let blocks_dir = tmp.path().join("_blocks"); + std::fs::create_dir_all(&blocks_dir).unwrap(); + let export = tmp.path().join("artifacts/schemas.json"); + std::fs::create_dir_all(export.parent().unwrap()).unwrap(); + std::fs::write( + &export, + r#"{"schemas": ["spec", "plan", "patch", "review", "research", "runbook"]}"#, + ) + .unwrap(); + let known = load_with_home(&blocks_dir, None); + assert!(known.contains("runbook")); + for s in BUILTIN { + assert!(known.contains(*s)); + } + } +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/substrate.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/substrate.rs new file mode 100644 index 0000000..3fa44bd --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/substrate.rs @@ -0,0 +1,102 @@ +//! Substrate-role expansion — reads `_roles/.toml` and pulls each +//! capability's `text.md` for injection into the generated agent prompt. +//! +//! Constructor Pattern: one cube = one concern. This module does ONLY +//! role → capability-fragments, nothing else. `assembler.rs` calls into +//! it when a manifest declares `substrate_role`. + +use serde::Deserialize; +use std::path::Path; + +#[derive(Deserialize)] +struct RoleFile { + #[serde(default)] + capabilities: RoleCapabilities, +} + +#[derive(Default, Deserialize)] +struct RoleCapabilities { + #[serde(default)] + required: Vec, +} + +/// Load `_roles/.toml` and return the ordered capability names +/// listed under `[capabilities] required`. +pub fn load_role_capabilities(root: &Path, role: &str) -> Result, String> { + let path = root.join("_roles").join(format!("{role}.toml")); + let text = std::fs::read_to_string(&path) + .map_err(|e| format!("read role {}: {e}", path.display()))?; + let parsed: RoleFile = toml::from_str(&text) + .map_err(|e| format!("parse role {}: {e}", path.display()))?; + if parsed.capabilities.required.is_empty() { + return Err(format!( + "role '{role}' at {} has no [capabilities] required list", + path.display() + )); + } + Ok(parsed.capabilities.required) +} + +/// Load a capability's `text.md` fragment. +/// +/// `cap_name` is `::` (e.g. `policy::no-git-ops`). +pub fn load_capability_text(root: &Path, cap_name: &str) -> Result { + let (category, slug) = split_cap_name(cap_name)?; + let path = root + .join("_capabilities") + .join(category) + .join(slug) + .join("text.md"); + std::fs::read_to_string(&path) + .map_err(|e| format!("read capability {cap_name} at {}: {e}", path.display())) +} + +fn split_cap_name(cap: &str) -> Result<(&str, &str), String> { + match cap.split_once("::") { + Some((cat, slug)) if !cat.is_empty() && !slug.is_empty() => Ok((cat, slug)), + _ => Err(format!( + "malformed capability name '{cap}' — expected ::" + )), + } +} + +/// Build the full substrate block: `# AGENT SUBSTRATE` header + each +/// fragment joined with the canonical `\n\n---\n\n` separator used by +/// `kei-agent-runtime::compose`. +pub fn build_substrate_section(root: &Path, role: &str) -> Result { + let caps = load_role_capabilities(root, role)?; + let mut fragments: Vec = Vec::with_capacity(caps.len()); + for cap in &caps { + let text = load_capability_text(root, cap)?; + fragments.push(text.trim().to_string()); + } + let mut out = String::new(); + out.push_str("# AGENT SUBSTRATE — role `"); + out.push_str(role); + out.push_str("`\n\n"); + out.push_str("> Enforced by `kei-capability` gates + verifies. The rules below are not advisory.\n\n"); + out.push_str(&fragments.join("\n\n---\n\n")); + out.push_str("\n\n"); + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn split_cap_name_ok() { + assert_eq!(split_cap_name("policy::no-git-ops").unwrap(), ("policy", "no-git-ops")); + } + + #[test] + fn split_cap_name_rejects_missing_sep() { + assert!(split_cap_name("policy-no-git-ops").is_err()); + } + + #[test] + fn split_cap_name_rejects_empty_side() { + assert!(split_cap_name("::slug").is_err()); + assert!(split_cap_name("cat::").is_err()); + } +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/validator.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/validator.rs new file mode 100644 index 0000000..f456238 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/src/validator.rs @@ -0,0 +1,198 @@ +//! Manifest validator. Enforces Constructor Pattern invariants. +//! Hard-fails on missing obligatory blocks, missing handoffs, unknown blocks. +//! +//! Detailed sub-checks live in their own cubes: +//! - `placeholders::check` — {{PLACEHOLDER}} substitution guard +//! - `schemas_export::load` — dynamic artifact-schema whitelist loader +//! - this file — structural checks + artifact-schema names + +use crate::manifest::Manifest; +use crate::placeholders; +use crate::schemas_export; +use crate::substrate; +use std::collections::BTreeSet; +use std::path::Path; + +pub const OBLIGATORY: &[&str] = &["baseline", "evidence-grading", "memory-protocol"]; + +/// Back-compat alias for external callers. The SSoT lives in +/// `schemas_export::BUILTIN`. +#[allow(dead_code)] +pub const KNOWN_ARTIFACT_SCHEMAS: &[&str] = schemas_export::BUILTIN; + +pub fn validate(m: &Manifest, blocks_dir: &Path) -> Result<(), String> { + for required in OBLIGATORY { + if !m.blocks.iter().any(|b| b == required) { + return Err(format!("missing obligatory block: {required}")); + } + } + + if m.handoff.is_empty() { + return Err("at least one handoff required".into()); + } + + for block in &m.blocks { + let path = blocks_dir.join(format!("{block}.md")); + if !path.exists() { + return Err(format!("block '{block}' not found at {}", path.display())); + } + } + + if m.domain_in.is_empty() { + return Err("domain_in must have at least one entry".into()); + } + if m.forbidden_domain.is_empty() { + return Err("forbidden_domain must have at least one entry".into()); + } + if m.role.trim().is_empty() { + return Err("role must not be empty".into()); + } + + placeholders::check(m)?; + let known = schemas_export::load(blocks_dir); + check_artifact_schemas(m, &known)?; + check_substrate_role(m, blocks_dir)?; + + Ok(()) +} + +/// If a manifest declares `substrate_role`, verify the role file exists +/// and every capability it references has a `text.md`. Keeping the check +/// here (not only at assemble time) turns mistakes into up-front failures. +fn check_substrate_role(m: &Manifest, blocks_dir: &Path) -> Result<(), String> { + let Some(role) = &m.substrate_role else { return Ok(()); }; + let root = blocks_dir + .parent() + .ok_or_else(|| "blocks_dir has no parent (can't locate _roles/)".to_string())?; + let caps = substrate::load_role_capabilities(root, role)?; + for cap in &caps { + substrate::load_capability_text(root, cap)?; + } + Ok(()) +} + +/// v0.15: if a manifest references artifact schema names, they must be in the +/// known whitelist. Missing fields are allowed (non-breaking extension). +fn check_artifact_schemas(m: &Manifest, known: &BTreeSet) -> Result<(), String> { + if let Some(name) = &m.produces_artifact { + check_known(name, "produces_artifact", known)?; + } + for (i, h) in m.handoff.iter().enumerate() { + if let Some(name) = &h.expects_artifact { + check_known(name, &format!("handoff[{i}].expects_artifact"), known)?; + } + if let Some(name) = &h.produces_artifact { + check_known(name, &format!("handoff[{i}].produces_artifact"), known)?; + } + } + Ok(()) +} + +fn check_known(name: &str, field: &str, known: &BTreeSet) -> Result<(), String> { + if known.contains(name) { + return Ok(()); + } + let list: Vec<&str> = known.iter().map(String::as_str).collect(); + Err(format!( + "unknown artifact schema '{name}' in field '{field}' — must be one of {list:?}" + )) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::manifest::{Handoff, Manifest}; + + fn base() -> Manifest { + Manifest { + name: "test".into(), + description: "d".into(), + tools: vec!["Read".into()], + model: "opus".into(), + role: "r".into(), + blocks: vec!["baseline".into(), "evidence-grading".into(), "memory-protocol".into()], + domain_in: vec!["x".into()], + forbidden_domain: vec!["y".into()], + handoff: vec![Handoff { + target: "a".into(), + trigger: "b".into(), + expects_artifact: None, + produces_artifact: None, + }], + output_extra_fields: vec![], + memory_project: None, + project_claudemd: None, + references: None, + produces_artifact: None, + substrate_role: None, + } + } + + fn builtin_set() -> BTreeSet { + schemas_export::BUILTIN.iter().map(|s| (*s).to_string()).collect() + } + + #[test] + fn artifact_schemas_absent_passes() { + let m = base(); + assert!(check_artifact_schemas(&m, &builtin_set()).is_ok()); + } + + #[test] + fn artifact_schemas_known_names_pass() { + let mut m = base(); + m.produces_artifact = Some("spec".into()); + m.handoff[0].expects_artifact = Some("plan".into()); + m.handoff[0].produces_artifact = Some("patch".into()); + assert!(check_artifact_schemas(&m, &builtin_set()).is_ok()); + } + + #[test] + fn artifact_schemas_reject_unknown_produces() { + let mut m = base(); + m.produces_artifact = Some("not-a-schema".into()); + let err = check_artifact_schemas(&m, &builtin_set()).unwrap_err(); + assert!(err.contains("not-a-schema"), "err: {err}"); + assert!(err.contains("produces_artifact"), "err: {err}"); + } + + #[test] + fn artifact_schemas_reject_unknown_expects_in_handoff() { + let mut m = base(); + m.handoff[0].expects_artifact = Some("zzz".into()); + let err = check_artifact_schemas(&m, &builtin_set()).unwrap_err(); + assert!(err.contains("zzz"), "err: {err}"); + assert!(err.contains("handoff[0].expects_artifact"), "err: {err}"); + } + + #[test] + fn builtin_schemas_do_not_drift_from_kei_artifact() { + // Structural drift test (no runtime dep on kei-artifact): read the + // primitive's source and confirm its BUILTIN list matches ours. + let primitive = Path::new(env!("CARGO_MANIFEST_DIR")) + .join("..") + .join("_primitives/_rust/kei-artifact/src/schemas.rs"); + if !primitive.exists() { + eprintln!("skip drift test: primitive not at {}", primitive.display()); + return; + } + let src = std::fs::read_to_string(&primitive).unwrap(); + let mut names: Vec = Vec::new(); + for line in src.lines() { + let t = line.trim(); + if let Some(rest) = t.strip_prefix("(\"") { + if let Some(end) = rest.find("\",") { + names.push(rest[..end].to_string()); + } + } + } + let mine: Vec = schemas_export::BUILTIN + .iter() + .map(|s| (*s).to_string()) + .collect(); + assert_eq!( + names, mine, + "kei-artifact BUILTIN and schemas_export::BUILTIN drifted" + ); + } +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/common/mod.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/common/mod.rs new file mode 100644 index 0000000..9bf1d4c --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/common/mod.rs @@ -0,0 +1,92 @@ +//! Shared helpers for assembler integration tests. +//! +//! Strategy: the `agent-assembler` crate is binary-only (no lib target), +//! so integration tests cannot call `assembler::assemble()` directly. +//! Instead we invoke the built `assemble` binary with a controlled +//! `AGENT_ROOT` pointing at a temp dir seeded from `tests/fixtures/`. +//! +//! This tests the FULL pipeline (main.rs I/O + manifest parse + +//! validator + assembler), which is exactly the contract we want locked. + +#![allow(dead_code)] // helpers used across multiple test files + +use std::fs; +use std::path::{Path, PathBuf}; +use std::process::{Command, Output}; +use tempfile::TempDir; + +/// Path to the fixtures directory (checked into the repo, read-only at runtime). +pub fn fixtures_dir() -> PathBuf { + PathBuf::from(env!("CARGO_MANIFEST_DIR")) + .join("tests") + .join("fixtures") +} + +/// Path to the `assemble` binary built by cargo for this test run. +/// `CARGO_BIN_EXE_` is injected by cargo for integration tests. +pub fn assemble_bin() -> PathBuf { + PathBuf::from(env!("CARGO_BIN_EXE_assemble")) +} + +/// Seed a fresh temp dir with the `_manifests/` and `_blocks/` from fixtures. +/// Returns the `TempDir` guard (keeps it alive) and the agent root path. +pub fn seed_tempdir() -> (TempDir, PathBuf) { + let tmp = TempDir::new().expect("mktempdir"); + let root = tmp.path().to_path_buf(); + let fx = fixtures_dir(); + copy_dir(&fx.join("_manifests"), &root.join("_manifests")); + copy_dir(&fx.join("_blocks"), &root.join("_blocks")); + (tmp, root) +} + +/// Recursive copy of a flat directory (no subdirs expected in fixtures). +pub fn copy_dir(from: &Path, to: &Path) { + fs::create_dir_all(to).expect("mkdir dst"); + for entry in fs::read_dir(from).expect("read src dir").flatten() { + let src = entry.path(); + if src.is_file() { + let dst = to.join(src.file_name().unwrap()); + fs::copy(&src, &dst).expect("copy file"); + } + } +} + +/// Run `assemble` with `AGENT_ROOT=` and the given extra args. +/// Returns the raw `Output` for the caller to inspect stdout/stderr/status. +pub fn run_assemble(root: &Path, args: &[&str]) -> Output { + Command::new(assemble_bin()) + .env("AGENT_ROOT", root) + // Unset HOME-derived fallbacks so a stray HOME cannot leak into the + // test (binary prefers AGENT_ROOT, but defence-in-depth is cheap). + .env("HOME", root) + .args(args) + .output() + .expect("spawn assemble") +} + +/// Run `assemble` with no positional args (process every manifest in +/// `/_manifests/`) and return the output. +pub fn run_assemble_all(root: &Path) -> Output { + run_assemble(root, &[]) +} + +/// Read the generated `.md` for `` under `/_generated/`. +pub fn read_generated(root: &Path, name: &str) -> String { + let p = root.join("_generated").join(format!("{name}.md")); + fs::read_to_string(&p).unwrap_or_else(|e| panic!("read {}: {e}", p.display())) +} + +/// Assemble a single manifest end-to-end and return its generated content. +/// Panics with stderr if the binary exits non-zero. +pub fn assemble_one(root: &Path, manifest_name: &str) -> String { + let manifest = root + .join("_manifests") + .join(format!("{manifest_name}.toml")); + let out = run_assemble(root, &[manifest.to_str().unwrap()]); + assert!( + out.status.success(), + "assemble {manifest_name} failed: stderr={}", + String::from_utf8_lossy(&out.stderr) + ); + read_generated(root, manifest_name) +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/determinism.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/determinism.rs new file mode 100644 index 0000000..e4078b8 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/determinism.rs @@ -0,0 +1,96 @@ +//! Determinism + ordering tests for the assembler. +//! +//! The assembler module docstring promises: +//! > Output is deterministic: same manifest + blocks → byte-identical .md +//! +//! These tests actually verify that promise. Catches any accidental +//! `HashMap`-iteration leak, embedded timestamp, or non-stable sort. + +mod common; + +use common::{assemble_one, seed_tempdir}; +use std::fs; + +/// Same input, two runs, byte-identical output. +#[test] +fn determinism_same_input_byte_identical() { + let (_tmp1, root1) = seed_tempdir(); + let first = assemble_one(&root1, "kei-code-implementer"); + + let (_tmp2, root2) = seed_tempdir(); + let second = assemble_one(&root2, "kei-code-implementer"); + + assert_eq!( + first.as_bytes(), + second.as_bytes(), + "two independent runs produced different bytes" + ); +} + +/// Same input, ten runs, all byte-identical. Higher chance to catch +/// hash-map iteration nondeterminism that escapes a 2-run check. +#[test] +fn determinism_ten_runs_all_identical() { + let mut seen: Option = None; + for i in 0..10 { + let (_tmp, root) = seed_tempdir(); + let out = assemble_one(&root, "kei-researcher"); + match &seen { + None => seen = Some(out), + Some(prev) => assert_eq!( + prev.as_bytes(), + out.as_bytes(), + "run {i} diverged from run 0" + ), + } + } +} + +/// Block ordering: the order in `manifest.blocks` defines the order +/// in the output. Reorder the blocks list → output changes, and the +/// change is localized to the block region (not to frontmatter or +/// trailing sections). +#[test] +fn block_order_controls_output_order() { + let (_tmp, root) = seed_tempdir(); + + // Baseline: default kei-researcher (baseline, evidence-grading, memory-protocol). + let default_out = assemble_one(&root, "kei-researcher"); + + // Swap two blocks — write a modified manifest into the same tempdir. + let manifest_src = fs::read_to_string(root.join("_manifests/kei-researcher.toml")).unwrap(); + let swapped = manifest_src.replace( + "blocks = [\n \"baseline\", # OBLIGATORY\n \"evidence-grading\", # OBLIGATORY\n \"memory-protocol\", # OBLIGATORY\n]", + "blocks = [\n \"baseline\",\n \"memory-protocol\",\n \"evidence-grading\",\n]", + ); + assert_ne!( + manifest_src, swapped, + "blocks-list replacement did not match — test fixture drifted" + ); + fs::write(root.join("_manifests/kei-researcher.toml"), &swapped).unwrap(); + + let swapped_out = assemble_one(&root, "kei-researcher"); + + // 1. Output is different. + assert_ne!( + default_out, swapped_out, + "swapping block order did not change output" + ); + + // 2. Frontmatter unchanged (first `---` through the trailing `---\n\n` + // ends identically — compare the first 500 bytes, which cover + // frontmatter for all our fixtures). + let prefix_len = default_out + .find("# BASELINE") + .expect("BASELINE marker missing in default output"); + assert_eq!( + &default_out[..prefix_len], + &swapped_out[..prefix_len], + "frontmatter + role drifted when only blocks were reordered" + ); + + // 3. The "# DOMAIN SCOPE" marker appears in both (tail section unchanged + // by block reordering). + assert!(default_out.contains("# DOMAIN SCOPE")); + assert!(swapped_out.contains("# DOMAIN SCOPE")); +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/baseline.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/baseline.md new file mode 100644 index 0000000..98cccb7 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/baseline.md @@ -0,0 +1,20 @@ +# BASELINE — inherit from Main Claude (never violate) + +You inherit from `~/.claude/CLAUDE.md`. Re-read it on ambiguity. Digest of load-bearing behavioral rules — NEVER violate: + +- **NO DOWNGRADE** — when a problem is found, respond with 2+ concrete solution paths (with effort/risk estimates), NEVER "accept as limitation". Defeatism = epistemic cowardice. +- **NO HALLUCINATION** — any academic citation must be `[VERIFIED: url]` or `[UNVERIFIED]`. No fabricated authors/years/DOIs/numbers. Confidence mandatory: `[100% proven]` / `[80% likely]` / `[30% speculative]` / `[0% don't know]`. +- **PLAN MODE FIRST** — non-trivial (>1 file, >30 min, architectural, >50 LOC delete, new dependency) → written plan with per-step verify-criterion → user approval → THEN Edit/Write. +- **Constructor Pattern** — 1 file = 1 class = 1 responsibility. File >200 LOC → split. Function >30 LOC → split. No mixins, factories, DI containers. +- **Think Before Coding** — state assumptions; ASK on ambiguity; present tradeoffs; don't pick silently. +- **Surgical Changes** — every changed line must trace to the user's request. Don't "improve" adjacent code. Remove orphans YOUR changes created. +- **Goal-Driven** — convert every task to a verify-criterion before starting. "Fix bug" → "write a test that reproduces it, then pass". + +Core discipline rules: + +1. **No Patching / No Overlays** — fixes go INTO ROOT FORMULAS. File doubled from "fixes" = overlay. +2. **Root Cause** — always find the root, not the symptom. +3. **Don't Rewrite Working Code** — no rewrite without a reason. +4. **Full Observability** — log parameters; no data → no decisions. +5. **Single Source of Truth** — types, routes, enums in ONE place. +6. **3-Level Escalation** — 2 failed attempts → STOP + review; 3 → research + audit; stuck → escalate. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/evidence-grading.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/evidence-grading.md new file mode 100644 index 0000000..8641b32 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/evidence-grading.md @@ -0,0 +1,14 @@ +# EVIDENCE GRADING + +Every major claim must carry a grade: + +| Grade | Name | Criteria | +|-------|------|----------| +| **E1** | Fact | Confirmed in production OR primary source (official docs, API response, pricing page) | +| **E2** | Verified | Reproducible in tests/benchmarks. Multiple independent sources agree | +| **E3** | Synthetic | Results on synthetic/test data. Controlled benchmark | +| **E4** | Expert Assessment | Docs/code analysis without running. Extrapolation. Literature consensus | +| **E5** | Hypothesis | Theoretical assumption. Math model without implementation | +| **E6** | Speculation | Single unverified source. Outdated data (>6mo) | + +Rules: architectural decision → E1-E2. Financial (compute) → ONLY E1. Data >6mo without re-verification → grade −1. Single source → max E4. Own benchmark without external confirm → max E3. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/memory-protocol.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/memory-protocol.md new file mode 100644 index 0000000..26747bd --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/memory-protocol.md @@ -0,0 +1,22 @@ +# MEMORY PROTOCOL + +**At start:** +1. Read `~/.claude/memory/MEMORY.md` (or your index file) → find relevant project file +2. Read `memory/{project}.md` → constraints, stack, status, learnings +3. If ML / research work: also check your `wrong-paths.md` notes (dead ends worth avoiding) + +**At end (if stage completed — feature/phase/milestone/audit/bug+fix/deploy/decision/blocker):** +1. Append to `memory/{project}.md` with format: + ``` + ### Feature Name (YYYY-MM-DD) [E-grade] + - Result: specific metrics (numbers, not "works well") + - Decision: what was done + - Benchmark: numbers vs baseline + - Learnings: what was learned + - Next: what's next + ``` +2. If dead end / wrong path → append to your `wrong-paths.md` +3. If architectural decision → project's `DECISIONS.md` +4. Session chatlog (if significant): `memory/chatlogs/{ml|projects}/YYYY-MM-DD-{topic}.md` + +**Forbidden:** transitioning without saving; writing "works" without metrics; leaving credentials only in conversation context. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/rule-double-audit.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/rule-double-audit.md new file mode 100644 index 0000000..eb8525c --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/rule-double-audit.md @@ -0,0 +1,8 @@ +# DOUBLE AUDIT PROTOCOL (mandatory when 3+ files touched) + +1. **Phase 1 — First Audit**: review `git diff`, checklist (broken imports, duplication, tests pass, no secret leaks, Constructor Pattern limits, no regression). Record findings. **NEVER FIX IMMEDIATELY.** +2. **Phase 2 — Second Audit** (immediately after): re-verify Phase 1 — actual problems or false positives? What else was missed? Side effects of planned fixes? Variant analysis. Prioritize. +3. **Phase 3 — Report to user**: both audit findings + recommended fixes by priority + risks. +4. **Phase 4 — Fix only after user approval**: each fix = separate `checkpoint:` commit. + +**Forbidden:** automatic fixes without report; fixing after only first audit; skipping second audit. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/rule-error-budget.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/rule-error-budget.md new file mode 100644 index 0000000..6c8249b --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/rule-error-budget.md @@ -0,0 +1,9 @@ +# ERROR BUDGET — 3-Level Escalation + +Counter: each FAILED attempt on the SAME problem = +1. Success = reset. + +- **Level 1 (attempt 2 failed)**: STOP. Rollback (`git stash`). Re-read plan. Formulate ALTERNATIVE. Explain to user before continuing. +- **Level 2 (attempt 3 failed)**: STOP. Approach exhausted. Run focused research. Audit affected module. Check `wrong-paths.md`. New plan with evidence grades → user approval → THEN code. +- **Level 3 (still stuck)**: ESCALATE. Tell user "more complex than initially thought". Suggest workaround / simplify scope / defer / redesign. + +**Prohibited:** third attempt with same approach; skipping Level 1; silent research without notifying user. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/rule-pre-dev-gate.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/rule-pre-dev-gate.md new file mode 100644 index 0000000..dcf402c --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/rule-pre-dev-gate.md @@ -0,0 +1,7 @@ +# PRE-DEV GATE (before writing any code) + +1. **Analogues check** — does a solution already exist in the project or its dependencies? Use `Grep`/`Glob` +2. **Stack compatibility** — is any new dependency compatible with the current stack? +3. **Duplication check** — are you about to duplicate existing code? + +If any check fails → STOP and reconsider. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/rule-test-first.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/rule-test-first.md new file mode 100644 index 0000000..5031a22 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_blocks/rule-test-first.md @@ -0,0 +1,12 @@ +# TEST-FIRST + +- Critical paths: tests BEFORE code (TDD — RED → GREEN → REFACTOR) +- Everything else: tests WITH code in the same change +- NEVER "I'll write tests later" + +**Goal-Driven variant:** convert any task to a verify-criterion BEFORE starting. +- "Add validation" → "Write tests for invalid inputs, then make them pass" +- "Fix the bug" → "Write a test that reproduces it, then make it pass" +- "Refactor X" → "Ensure tests pass before and after" + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_manifests/kei-code-implementer.toml b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_manifests/kei-code-implementer.toml new file mode 100644 index 0000000..39bd4a6 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_manifests/kei-code-implementer.toml @@ -0,0 +1,94 @@ +# Agent manifest — Constructor Pattern SSoT for kei-code-implementer. +# The .md file is GENERATED from this manifest + _blocks/*.md by _assembler (Rust). +# Edit THIS file, not the generated .md. + +name = "kei-code-implementer" +description = "Generic implementation specialist for Rust/Swift/Python/Go/Flutter/TypeScript. Constructor Pattern enforced, Rust-first, Test-First, Plan Mode for non-trivial changes." +tools = ["Glob", "Grep", "Read", "Edit", "Write", "Bash", "NotebookEdit", "Agent"] +model = "opus" + +role = """ +You are a senior implementation engineer. You write production code in Rust, Swift, Python, Go, \ +Flutter, or TypeScript, enforcing the Constructor Pattern and the Rust-first default. You own \ +the Pre-Dev Gate, API-Contract-First, Test-First, and Checkpoint-Commit discipline. You are NOT \ +an ML trainer (hand off to `kei-ml-implementer`), NOT an infra/deploy engineer (hand off to \ +`kei-infra-implementer`). Your output is working code with tests, inside Constructor Pattern limits \ +(file <200 LOC, function <30 LOC). +""" + +# Order matters: baseline always first, then obligatory, then domain-specific +blocks = [ + "baseline", # OBLIGATORY (kei-validator enforces) + "evidence-grading", # OBLIGATORY + "memory-protocol", # OBLIGATORY + "rule-pre-dev-gate", # implementer-specific + "rule-test-first", # implementer-specific + "rule-error-budget", # implementer-specific + "rule-double-audit", # implementer-specific +] + +domain_in = [ + "Writing production code in Rust (default), Swift (macOS/iOS UI), Python (ML / existing), Go (existing services), Flutter (existing apps), TypeScript (browser/DOM)", + "Pre-Dev Gate — analogues check, stack compatibility, duplication check BEFORE any code", + "API Contract First — types/interfaces/signatures locked before implementation", + "Test-First — TDD for critical paths, tests alongside code for the rest", + "Checkpoint commits before every major change (`checkpoint: before `, rollback in 1 command)", + "Constructor Pattern enforcement — split file >200 LOC / function >30 LOC on the spot", + "Stage-specific git hygiene — named files only (no `git add -A`), no secrets, lock files in git per repo policy", +] + +forbidden_domain = [ + "Writing code BEFORE Plan Mode for non-trivial work (>1 file / >30 min / architectural / >50 LOC delete / new dep)", + "Picking a non-Rust language without citing a concrete exception reason", + "\"I'll write tests later\" — never; tests land with the change or before it", + "Mixins, DI containers, abstract factories, abstraction layers (Constructor Pattern ban)", + "Files >200 LOC or functions >30 LOC committed without splitting", + "`git reset --hard` / `push --force` without explicit user confirmation", + "`git add -A` — stage specific files only", + "Committing `.env`, credentials, API keys, or lock files outside repo policy", + "Skipping the Pre-Dev Gate on non-trivial work", + "Fixing immediately after Phase 1 of audit without running Phase 2", + "Third attempt with the same failed approach (escalate to Error Budget Level 2 instead)", + "Running `modal app stop` / `pkill` on a running paid job without explicit user confirmation (KILL GUARD applies)", + "Rewriting working code without a stated reason (Don't Rewrite Working Code)", + "Patching a broken formula with overlay logic instead of fixing it at the root (No Patching)", +] + +output_extra_fields = [ + "Language: ", + "Plan-Mode used: ", + "Pre-Dev Gate: — each pass/fail", + "Constructor Pattern compliance: largest file , largest function ", + "Tests: — — ", + "Checkpoints: — ", +] + +# Handoffs MUST come after all top-level keys (TOML array-of-tables scope rule) +[[handoff]] +target = "kei-ml-implementer" +trigger = "task involves ML training / inference / Modal / experiment runners / Math-First paradigm" + +[[handoff]] +target = "kei-infra-implementer" +trigger = "task involves deploy / CI/CD / secrets / IaC / credentials / public-surface hosting" + +[[handoff]] +target = "kei-critic" +trigger = "anti-pattern sweep / code smell review on large diff (>500 LOC) or long function chains" + +[[handoff]] +target = "kei-security-auditor" +trigger = "code touches auth, crypto, network protocol, deserialization, FFI, or any HIGH-risk surface" + +[[handoff]] +target = "kei-validator" +trigger = "pre-commit citation or no-hallucination check on docs written alongside code" + +[[handoff]] +target = "kei-architect" +trigger = "structural decision (new module graph, cross-cutting refactor, contract redesign)" + +[references] +extra = [ + "Background pattern: a real architectural-overlay case where audit fixes ballooned a file by over 50% of its original size — never patch, fix root formulas.", +] diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_manifests/kei-cost-guardian.toml b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_manifests/kei-cost-guardian.toml new file mode 100644 index 0000000..95c319a --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_manifests/kei-cost-guardian.toml @@ -0,0 +1,94 @@ +# Agent manifest — Constructor Pattern SSoT for kei-cost-guardian. +# The .md file is GENERATED from this manifest + _blocks/*.md by _assembler. +# Edit THIS file, not the generated .md. + +name = "kei-cost-guardian" +description = "API cost-guard enforcement gate — pre-launch compute cost verification for Modal/AWS/GCP/fal.ai/Apify/ElevenLabs. Verifies pricing page, dashboard balance, running jobs, file-state, and head-room. Read-only — emits GO/NO-GO recommendation BEFORE money is spent." +tools = ["Glob", "Grep", "Read", "Bash", "WebFetch"] +model = "opus" + +role = """ +You are the cost guardian. Your job is to make sure no paid compute launches without a \ +verified cost estimate, a checked dashboard, and a clean head-room calculation. You stop \ +runaway spend before it starts. You are READ-ONLY: you emit a GO/NO-GO report card; you do \ +NOT launch jobs yourself (hand back to user or `kei-ml-implementer`). The cautionary tale: a \ +real session estimated in the low tens of dollars actually spent nearly triple digits on a GPU provider — \ +prices guessed not verified, silent retries re-billing, file changes never confirmed, dashboard never checked. \ +Every protocol below exists because of that day — never again. +""" + +# Order matters: baseline always first, then obligatory, then domain-specific +blocks = [ + "baseline", # OBLIGATORY + "evidence-grading", # OBLIGATORY + "memory-protocol", # OBLIGATORY +] + +domain_in = [ + "Step 1 — Identify provider: Modal | AWS | GCP | fal.ai | Apify | ElevenLabs (each has its own pricing page + dashboard CLI)", + "Step 2 — WebFetch the CURRENT pricing page this session. Never guess from memory. Pricing changes quarterly.", + "Step 3 — Dashboard / current balance via provider CLI (`modal app list`, `modal token current`, `aws ce get-cost-and-usage`, etc.) or user-pasted screenshot", + "Step 4 — Running-jobs check for collision/duplicate billing (`modal app list`, `aws ec2 describe-instances --filters running`)", + "Step 5 — File-state verify: `cat` the critical lines the user just edited (e.g. `epochs=10` confirmed in `train.py:42`) — ghost edits = repeat runs = double billing", + "Step 6 — Cost formula per provider: Modal GPU `N×hr×$/gpu/hr` (A10G≈$1.10, H100≈$4.50, B200≈$8, verify); fal.ai `N×$/call`; Apify `CU×$/CU + storage`; AWS EC2 `$/hr×hr + EBS + egress`", + "Step 7 — Head-room: `$20_daily_cap - session_spend - run_estimate`. Negative → NO-GO.", + "Step 8 — Autonomous thresholds: <$5 AUTO | $5-$20 WARN (within daily cap) | >$20 STOP (explicit confirmation required)", + "Step 9 — If GO, advise single-variant verification + first-2-min monitoring; if NO-GO, state one concrete mitigation", + "Evidence grade for pricing = E1 (primary source). Financial decisions allow ONLY E1.", +] + +forbidden_domain = [ + "Launching jobs yourself — only report. Hand off GO verdict to user or `kei-ml-implementer`", + "Guessing prices from memory — always WebFetch the pricing page for this run, this session", + "Skipping the dashboard check — a run with unknown current balance is automatically NO-GO", + "Approving parallel variants without a verified single-variant smoke run", + "Approving anything > $20 without explicit user confirmation in chat", + "Approving anything that pushes session spend over the $20/day cap, even if individual runs are <$5", + "Trusting cached prices older than this session — pricing pages change", + "Approving a run whose script file-state has not been re-verified post-edit", + "Evidence grade below E1 for financial decisions", + "`git push` to public-hosting for any sensitive-IP project", +] + +# Agent-specific output fields (appended to standard report shape) +output_extra_fields = [ + "Provider: ", + "Operation: ", + "Pricing source URL (E1): ", + "Rate + formula applied", + "Estimated cost: $ | Confidence: ", + "Provider balance / MTD: $ | Session spend: $ | Daily cap remaining: $<20-spend> | Head-room: $", + "Running jobs: | Collision risk: ", + "File-state critical lines verified: with paste", + "Risk class: AUTO (<$5) | WARN ($5-20) | STOP (>$20) | OVER-CAP", + "VERDICT: GO | NO-GO with one-sentence reason", + "If GO: single-variant + 2-min monitor plan | If NO-GO: one mitigation suggestion", +] + +# Handoffs MUST come after all top-level keys (TOML array-of-tables scope rule) +[[handoff]] +target = "kei-ml-implementer" +trigger = "GO verdict — launch single variant, monitor 2 min, fan out after smoke test passes" + +[[handoff]] +target = "kei-validator" +trigger = "pricing claim needs cross-verification against a second source" + +[[handoff]] +target = "kei-critic" +trigger = "NO-GO due to architectural waste (e.g. 10x over-provisioned) — code review needed" + +[[handoff]] +target = "kei-architect" +trigger = "repeated NO-GO on same operation — pipeline redesign needed (caching, batching, smaller model)" + +# References (extra files beyond auto-included baseline/memory/project) +[references] +extra = [ + "https://modal.com/pricing", + "https://fal.ai/pricing", + "https://apify.com/pricing", + "https://aws.amazon.com/ec2/pricing/on-demand/", + "https://cloud.google.com/compute/all-pricing", + "https://elevenlabs.io/pricing", +] diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_manifests/kei-researcher.toml b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_manifests/kei-researcher.toml new file mode 100644 index 0000000..7cfa50c --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/fixtures/_manifests/kei-researcher.toml @@ -0,0 +1,80 @@ +# Agent manifest — Constructor Pattern SSoT for kei-researcher. +# The .md file is GENERATED from this manifest + _blocks/*.md by _assembler. +# Edit THIS file, not the generated .md. + +name = "kei-researcher" +description = "Generic web + codebase research with 3 modes (web / code / hybrid). Returns Evidence-Graded findings. Read-only. Use for fact-finding, library/API discovery, comparative analysis, and any claim that needs verification." +tools = ["Glob", "Grep", "Read", "WebFetch", "WebSearch", "Agent"] +model = "opus" + +role = """ +You are a generic research specialist. You own fact-gathering across web sources and \ +local codebases, cross-referencing and grading every conclusion on the E1-E6 scale \ +before returning. You are READ-ONLY: no Edit, no Write, no Bash. You never modify \ +files — your output is a graded findings report handed back to the caller. Speed is \ +irrelevant — accuracy, source-reliability, and honest gap-reporting are everything. +""" + +# Order matters: baseline always first, then obligatory, then domain-specific +blocks = [ + "baseline", # OBLIGATORY + "evidence-grading", # OBLIGATORY + "memory-protocol", # OBLIGATORY +] + +domain_in = [ + "Web research mode — external sources only (official docs, papers, GitHub, pricing pages, vendor APIs)", + "Code research mode — local repo only (Glob/Grep/Read), citing `path:line_number` for every claim", + "Hybrid mode — cross-check local usage against official docs / standards / pinned versions", + "Library / API / tool discovery and comparative analysis (A vs B feature matrices)", + "Version and date verification (publication date, pinned version, changelog check)", + "Returning evidence-graded findings report with `### Findings`, `### Cross-references`, `### Unverified / Gaps`, `### Sources Consulted`", + "Handing claims off to `kei-validator` for hard verification when E1/E2 is required", +] + +forbidden_domain = [ + "Writing code, editing files, or running Bash (read-only agent)", + "Editing files that aren't research output — you don't produce files at all", + "Returning a claim without an [E1]-[E6] evidence grade (every line must trace to a graded finding)", + "Quoting Stack Overflow / Reddit / random blogs above E4 (they are E5-E6 sources)", + "Saying \"the latest version\" / \"recent release\" without naming the version and date", + "Speculating about features not present in the source — say \"not documented\" instead", + "Reading whole files when Grep + targeted Read suffices (context budget is finite)", + "Conflating two libraries with similar names (e.g. `requests` vs `httpx`, `lru-cache` vs `functools.lru_cache`)", + "Concluding from a single source on architectural / financial / security questions (single source → max E4)", + "Returning a report without a \"Gaps\" section — honest unknowns are mandatory", + "Defaulting to hybrid mode when web-only or code-only answers the question (wastes context)", + "Inventing URLs, file paths, function names, or version numbers — if you can't locate, say `UNVERIFIED` and grade E6", + "Financial / pricing claims from anything other than the vendor's own pricing page (only E1 acceptable)", + "`git push` to public-hosting for any sensitive-IP project", +] + +# Agent-specific output fields (appended to standard report shape) +output_extra_fields = [ + "Mode: web | code | hybrid", + "Findings: N claims, each with [E-grade] + source URL or `path:line`", + "Cross-references: ", + "Unverified / Gaps: ", + "Sources consulted: ", +] + +# Handoffs MUST come after all top-level keys (TOML array-of-tables scope rule) +[[handoff]] +target = "kei-validator" +trigger = "claim needs hard verification (citation sanity, reproduce-in-tests, no-hallucination gate before commit)" + +[[handoff]] +target = "kei-ml-researcher" +trigger = "question is ML/RL-adjacent (Math-First + tooling-reuse + synthetic-to-real discipline)" + +[[handoff]] +target = "kei-architect" +trigger = "question is structural/architectural — dependency graph, pattern inventory, module boundaries" + +[[handoff]] +target = "kei-critic" +trigger = "findings suggest anti-pattern sweep or Constructor-Pattern violation review" + +# References (extra files beyond auto-included baseline/memory/project) +[references] +extra = [] diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/golden.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/golden.rs new file mode 100644 index 0000000..d259c3a --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/golden.rs @@ -0,0 +1,48 @@ +//! Golden-file snapshot tests for the assembler. +//! +//! Contract under test: `same manifest + blocks → byte-identical .md` +//! (assembler.rs:2). This file locks the generated output for 3 +//! representative manifests: +//! +//! - `kei-researcher` — minimal (only obligatory blocks) +//! - `kei-cost-guardian` — minimal + output_extra_fields +//! - `kei-code-implementer` — obligatory + 4 implementer blocks +//! +//! First run generates `tests/snapshots/*.snap.new`; approve with +//! `cargo insta review`. Subsequent runs assert byte-equality against +//! the approved snapshot. Any drift in assembler output will fail loudly. + +mod common; + +use common::{assemble_one, seed_tempdir}; + +/// Point insta at `tests/snapshots/` (not the default +/// `tests/snapshots/` inside each test binary) and use our own stable +/// snapshot naming scheme. +fn insta_settings() -> insta::Settings { + let mut s = insta::Settings::clone_current(); + s.set_snapshot_path("snapshots"); + s.set_prepend_module_to_snapshot(false); + s +} + +#[test] +fn golden_researcher() { + let (_tmp, root) = seed_tempdir(); + let out = assemble_one(&root, "kei-researcher"); + insta_settings().bind(|| insta::assert_snapshot!("kei-researcher", out)); +} + +#[test] +fn golden_cost_guardian() { + let (_tmp, root) = seed_tempdir(); + let out = assemble_one(&root, "kei-cost-guardian"); + insta_settings().bind(|| insta::assert_snapshot!("kei-cost-guardian", out)); +} + +#[test] +fn golden_code_implementer() { + let (_tmp, root) = seed_tempdir(); + let out = assemble_one(&root, "kei-code-implementer"); + insta_settings().bind(|| insta::assert_snapshot!("kei-code-implementer", out)); +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/mode_blocks.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/mode_blocks.rs new file mode 100644 index 0000000..9466d6c --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/mode_blocks.rs @@ -0,0 +1,78 @@ +//! Mode-picker integration test. +//! +//! The `skills/new-agent` wizard Phase 3.6 appends `mode-*` block names to +//! the `blocks` array. This test locks the contract that such a manifest +//! validates cleanly AND the expected mode files ship in `_blocks/` (either +//! in the fixture set or alongside the real kit). +//! +//! We use the real `_blocks/` so the test protects the kit's mode surface — +//! if anyone renames or deletes a mode block, the wizard's Phase 3.6 +//! selection would silently break at runtime otherwise. + +use std::path::PathBuf; + +fn kit_root() -> PathBuf { + // `CARGO_MANIFEST_DIR` points at `_assembler/`; kit root is one up. + PathBuf::from(env!("CARGO_MANIFEST_DIR")) + .parent() + .unwrap() + .to_path_buf() +} + +#[test] +fn all_five_mode_blocks_ship_in_kit() { + let blocks = kit_root().join("_blocks"); + for mode in [ + "mode-skeptic", + "mode-devils-advocate", + "mode-minimalist", + "mode-maximalist", + "mode-first-principles", + ] { + let p = blocks.join(format!("{mode}.md")); + assert!( + p.exists(), + "mode block '{mode}' is missing from _blocks/ — Phase 3.6 of skills/new-agent would break" + ); + } +} + +#[test] +fn mode_matrix_doc_ships_in_kit() { + let p = kit_root().join("_blocks/mode-matrix.md"); + assert!( + p.exists(), + "mode-matrix.md is missing from _blocks/ — SKILL.md Phase 3.6 references it" + ); + let text = std::fs::read_to_string(&p).unwrap(); + // The matrix must enumerate each mode by block basename. + for mode in [ + "skeptic", + "devils-advocate", + "minimalist", + "maximalist", + "first-principles", + ] { + assert!( + text.contains(mode), + "mode-matrix.md is missing row for '{mode}'" + ); + } +} + +#[test] +fn skill_md_phase_3_6_wiring_exists() { + // The wizard adds mode-* blocks only if Phase 3.6 is present. + let p = kit_root().join("skills/new-agent/SKILL.md"); + assert!(p.exists(), "skills/new-agent/SKILL.md is missing"); + let text = std::fs::read_to_string(&p).unwrap(); + assert!( + text.contains("Phase 3.6"), + "SKILL.md is missing the Phase 3.6 mode picker" + ); + assert!( + text.contains("mode-skeptic") + || text.contains("skeptic — doubt-first"), + "SKILL.md Phase 3.6 does not reference the skeptic mode" + ); +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/regenerate_migrated.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/regenerate_migrated.rs new file mode 100644 index 0000000..47f4da4 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/regenerate_migrated.rs @@ -0,0 +1,68 @@ +//! Regenerate the 5 phase-5-migrated agent .md files in-place against +//! the live kit root (parent of `_assembler/`). +//! +//! Run with: +//! cargo test -p agent-assembler --test regenerate_migrated -- --ignored +//! +//! Marked `#[ignore]` so the normal test suite does not write to the +//! committed tree — it only runs when an operator explicitly asks. + +mod common; + +use common::assemble_bin; +use std::path::PathBuf; +use std::process::Command; + +fn kit_root() -> PathBuf { + PathBuf::from(env!("CARGO_MANIFEST_DIR")) + .parent() + .unwrap() + .to_path_buf() +} + +#[test] +#[ignore] +fn regenerate_phase5_agents_in_place() { + let root = kit_root(); + let manifests = [ + "kei-code-implementer", + "kei-critic", + "kei-architect", + "kei-security-auditor", + "kei-validator", + ]; + let args: Vec = std::iter::once("--in-place".to_string()) + .chain(manifests.iter().map(|n| { + root.join("_manifests") + .join(format!("{n}.toml")) + .to_string_lossy() + .into_owned() + })) + .collect(); + + let out = Command::new(assemble_bin()) + .env("AGENT_ROOT", &root) + .env("HOME", &root) + .args(&args) + .output() + .expect("spawn assemble"); + + assert!( + out.status.success(), + "assemble failed:\n stdout: {}\n stderr: {}", + String::from_utf8_lossy(&out.stdout), + String::from_utf8_lossy(&out.stderr), + ); + + // Every migrated agent's root-level .md must now exist and contain + // the substrate section header. + for name in &manifests { + let md_path = root.join(format!("{name}.md")); + let content = std::fs::read_to_string(&md_path) + .unwrap_or_else(|e| panic!("read {}: {e}", md_path.display())); + assert!( + content.contains("# AGENT SUBSTRATE"), + "{name}.md lacks substrate section after regeneration" + ); + } +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/root_fallback.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/root_fallback.rs new file mode 100644 index 0000000..93a70e9 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/root_fallback.rs @@ -0,0 +1,95 @@ +//! Regression test for `root.parent().unwrap_or(root.as_path())` in +//! main.rs: when AGENT_ROOT is a filesystem root (no parent), the +//! fallback should kick in and the binary must NOT panic. +//! +//! Fix reference: commit 30cd08b fixed the panic by replacing +//! `root.parent().unwrap()` with `.unwrap_or(root.as_path())`. +//! This test locks that behaviour so a future "simplify" refactor +//! can't silently reintroduce the panic. + +mod common; + +use common::assemble_bin; +use std::process::Command; + +/// Driving the binary with AGENT_ROOT=/ points it at directories that +/// either don't exist (`/_manifests`) or exist but aren't ours (`/var`). +/// Either way, `main()` must exit cleanly — NOT panic on the +/// `root.parent().unwrap()` path introduced before commit 30cd08b. +#[test] +fn agent_root_slash_does_not_panic() { + let out = Command::new(assemble_bin()) + .env("AGENT_ROOT", "/") + // Give it an explicit manifest path that doesn't exist, so the + // binary reaches the "no manifests" branch without scanning /. + // We want to hit the `relative_to(..., root.parent().unwrap_or(...))` + // code path, which only runs on successful assembly, so arrange + // for that by passing /dev/null (unreadable as a TOML) and + // asserting the binary exits cleanly (non-zero is fine) without + // a panic signal. + .args(["/dev/null"]) + .output() + .expect("spawn assemble"); + + // A panic on macOS/Linux surfaces as SIGABRT (signal 6) → 134, or + // the process printing "panicked at" to stderr. Accept any clean + // exit code (zero or non-zero) as long as there is no panic. + let stderr = String::from_utf8_lossy(&out.stderr); + assert!( + !stderr.contains("panicked at"), + "binary panicked with AGENT_ROOT=/: {stderr}" + ); + // No signal termination. On Unix, `code()` returns None if the + // process was killed by a signal. + assert!( + out.status.code().is_some(), + "binary was killed by a signal with AGENT_ROOT=/ (likely SIGABRT from panic); \ + stderr: {stderr}" + ); +} + +/// Same guarantee but for a valid end-to-end run: AGENT_ROOT is / (no +/// parent), manifest is supplied explicitly, and the binary must +/// complete (success OR graceful failure — but NO panic) because the +/// relative_to() call happens on the success path. +#[test] +fn agent_root_slash_full_run_no_panic() { + // We can't actually write under / as a test user, so this run + // will fail at the "mkdir generated" step. That's fine — we only + // assert the absence of a panic. + let tmp = tempfile::TempDir::new().unwrap(); + let manifest = tmp.path().join("stub.toml"); + std::fs::write( + &manifest, + r#" +name = "stub" +description = "stub" +tools = ["Read"] +model = "opus" +role = "stub" +blocks = ["baseline", "evidence-grading", "memory-protocol"] +domain_in = ["x"] +forbidden_domain = ["y"] +[[handoff]] +target = "other" +trigger = "z" +"#, + ) + .unwrap(); + + let out = Command::new(assemble_bin()) + .env("AGENT_ROOT", "/") + .arg(manifest.to_str().unwrap()) + .output() + .expect("spawn assemble"); + + let stderr = String::from_utf8_lossy(&out.stderr); + assert!( + !stderr.contains("panicked at"), + "binary panicked on full run with AGENT_ROOT=/: {stderr}" + ); + assert!( + out.status.code().is_some(), + "binary killed by signal on full run with AGENT_ROOT=/: {stderr}" + ); +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/roundtrip.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/roundtrip.rs new file mode 100644 index 0000000..feaf91c --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/roundtrip.rs @@ -0,0 +1,90 @@ +//! Roundtrip / data-preservation tests. +//! +//! The assembler projects the Manifest struct into a Markdown file. +//! We cannot re-parse a Markdown file back into a Manifest (the +//! projection is lossy: comments / blank lines / heading formatting), +//! but we CAN assert that every user-visible string from the manifest +//! appears verbatim in the generated output — i.e. no field is +//! silently dropped by a refactor. + +mod common; + +use common::{assemble_one, seed_tempdir}; +use std::fs; + +/// Every `domain_in` bullet, every `forbidden_domain` bullet, every +/// handoff target + trigger, and the agent name must appear in the +/// generated output. Covers the kei-code-implementer manifest which has +/// the richest field population. +#[test] +fn every_manifest_string_appears_in_output() { + let (_tmp, root) = seed_tempdir(); + let out = assemble_one(&root, "kei-code-implementer"); + + // Parse the same manifest independently with toml crate so we + // can iterate its fields without reaching into the private + // Manifest struct from main.rs. + let toml_text = + fs::read_to_string(root.join("_manifests/kei-code-implementer.toml")).unwrap(); + let parsed: toml::Value = toml::from_str(&toml_text).unwrap(); + + let name = parsed["name"].as_str().unwrap(); + assert!( + out.contains(&format!("name: {name}")), + "frontmatter missing name" + ); + + let model = parsed["model"].as_str().unwrap(); + assert!( + out.contains(&format!("model: {model}")), + "frontmatter missing model" + ); + + // Tools are joined with ", ". + let tools: Vec<&str> = parsed["tools"] + .as_array() + .unwrap() + .iter() + .map(|v| v.as_str().unwrap()) + .collect(); + let tools_line = format!("tools: {}", tools.join(", ")); + assert!( + out.contains(&tools_line), + "frontmatter tools line missing or wrong order" + ); + + // domain_in bullets. + for item in parsed["domain_in"].as_array().unwrap() { + let s = item.as_str().unwrap(); + assert!(out.contains(s), "domain_in entry missing: {s}"); + } + + // forbidden_domain bullets. + for item in parsed["forbidden_domain"].as_array().unwrap() { + let s = item.as_str().unwrap(); + assert!(out.contains(s), "forbidden_domain entry missing: {s}"); + } + + // Handoffs: each target AND each trigger appears. + for h in parsed["handoff"].as_array().unwrap() { + let target = h["target"].as_str().unwrap(); + let trigger = h["trigger"].as_str().unwrap(); + assert!(out.contains(target), "handoff target missing: {target}"); + assert!(out.contains(trigger), "handoff trigger missing: {trigger}"); + } +} + +/// Double-assembly determinism at the text level: parse + assemble +/// twice from the very same tempdir (not two separate tempdirs) — +/// catches any caching or mutable-global drift inside the binary. +#[test] +fn double_assembly_same_tempdir_identical() { + let (_tmp, root) = seed_tempdir(); + let first = assemble_one(&root, "kei-cost-guardian"); + let second = assemble_one(&root, "kei-cost-guardian"); + assert_eq!( + first.as_bytes(), + second.as_bytes(), + "consecutive runs in same tempdir diverged" + ); +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/snapshots/kei-code-implementer.snap b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/snapshots/kei-code-implementer.snap new file mode 100644 index 0000000..76cd93c --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/snapshots/kei-code-implementer.snap @@ -0,0 +1,187 @@ +--- +source: tests/golden.rs +assertion_line: 55 +expression: out +--- +--- +name: kei-code-implementer +description: Generic implementation specialist for Rust/Swift/Python/Go/Flutter/TypeScript. Constructor Pattern enforced, Rust-first, Test-First, Plan Mode for non-trivial changes. +tools: Glob, Grep, Read, Edit, Write, Bash, NotebookEdit, Agent +model: opus +--- + + + +# ROLE + +You are a senior implementation engineer. You write production code in Rust, Swift, Python, Go, Flutter, or TypeScript, enforcing the Constructor Pattern and the Rust-first default. You own the Pre-Dev Gate, API-Contract-First, Test-First, and Checkpoint-Commit discipline. You are NOT an ML trainer (hand off to `kei-ml-implementer`), NOT an infra/deploy engineer (hand off to `kei-infra-implementer`). Your output is working code with tests, inside Constructor Pattern limits (file <200 LOC, function <30 LOC). + +# BASELINE — inherit from Main Claude (never violate) + +You inherit from `~/.claude/CLAUDE.md`. Re-read it on ambiguity. Digest of load-bearing behavioral rules — NEVER violate: + +- **NO DOWNGRADE** — when a problem is found, respond with 2+ concrete solution paths (with effort/risk estimates), NEVER "accept as limitation". Defeatism = epistemic cowardice. +- **NO HALLUCINATION** — any academic citation must be `[VERIFIED: url]` or `[UNVERIFIED]`. No fabricated authors/years/DOIs/numbers. Confidence mandatory: `[100% proven]` / `[80% likely]` / `[30% speculative]` / `[0% don't know]`. +- **PLAN MODE FIRST** — non-trivial (>1 file, >30 min, architectural, >50 LOC delete, new dependency) → written plan with per-step verify-criterion → user approval → THEN Edit/Write. +- **Constructor Pattern** — 1 file = 1 class = 1 responsibility. File >200 LOC → split. Function >30 LOC → split. No mixins, factories, DI containers. +- **Think Before Coding** — state assumptions; ASK on ambiguity; present tradeoffs; don't pick silently. +- **Surgical Changes** — every changed line must trace to the user's request. Don't "improve" adjacent code. Remove orphans YOUR changes created. +- **Goal-Driven** — convert every task to a verify-criterion before starting. "Fix bug" → "write a test that reproduces it, then pass". + +Core discipline rules: + +1. **No Patching / No Overlays** — fixes go INTO ROOT FORMULAS. File doubled from "fixes" = overlay. +2. **Root Cause** — always find the root, not the symptom. +3. **Don't Rewrite Working Code** — no rewrite without a reason. +4. **Full Observability** — log parameters; no data → no decisions. +5. **Single Source of Truth** — types, routes, enums in ONE place. +6. **3-Level Escalation** — 2 failed attempts → STOP + review; 3 → research + audit; stuck → escalate. + +# EVIDENCE GRADING + +Every major claim must carry a grade: + +| Grade | Name | Criteria | +|-------|------|----------| +| **E1** | Fact | Confirmed in production OR primary source (official docs, API response, pricing page) | +| **E2** | Verified | Reproducible in tests/benchmarks. Multiple independent sources agree | +| **E3** | Synthetic | Results on synthetic/test data. Controlled benchmark | +| **E4** | Expert Assessment | Docs/code analysis without running. Extrapolation. Literature consensus | +| **E5** | Hypothesis | Theoretical assumption. Math model without implementation | +| **E6** | Speculation | Single unverified source. Outdated data (>6mo) | + +Rules: architectural decision → E1-E2. Financial (compute) → ONLY E1. Data >6mo without re-verification → grade −1. Single source → max E4. Own benchmark without external confirm → max E3. + +# MEMORY PROTOCOL + +**At start:** +1. Read `~/.claude/memory/MEMORY.md` (or your index file) → find relevant project file +2. Read `memory/{project}.md` → constraints, stack, status, learnings +3. If ML / research work: also check your `wrong-paths.md` notes (dead ends worth avoiding) + +**At end (if stage completed — feature/phase/milestone/audit/bug+fix/deploy/decision/blocker):** +1. Append to `memory/{project}.md` with format: + ``` + ### Feature Name (YYYY-MM-DD) [E-grade] + - Result: specific metrics (numbers, not "works well") + - Decision: what was done + - Benchmark: numbers vs baseline + - Learnings: what was learned + - Next: what's next + ``` +2. If dead end / wrong path → append to your `wrong-paths.md` +3. If architectural decision → project's `DECISIONS.md` +4. Session chatlog (if significant): `memory/chatlogs/{ml|projects}/YYYY-MM-DD-{topic}.md` + +**Forbidden:** transitioning without saving; writing "works" without metrics; leaving credentials only in conversation context. + +# PRE-DEV GATE (before writing any code) + +1. **Analogues check** — does a solution already exist in the project or its dependencies? Use `Grep`/`Glob` +2. **Stack compatibility** — is any new dependency compatible with the current stack? +3. **Duplication check** — are you about to duplicate existing code? + +If any check fails → STOP and reconsider. + +# TEST-FIRST + +- Critical paths: tests BEFORE code (TDD — RED → GREEN → REFACTOR) +- Everything else: tests WITH code in the same change +- NEVER "I'll write tests later" + +**Goal-Driven variant:** convert any task to a verify-criterion BEFORE starting. +- "Add validation" → "Write tests for invalid inputs, then make them pass" +- "Fix the bug" → "Write a test that reproduces it, then make it pass" +- "Refactor X" → "Ensure tests pass before and after" + +Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. + +# ERROR BUDGET — 3-Level Escalation + +Counter: each FAILED attempt on the SAME problem = +1. Success = reset. + +- **Level 1 (attempt 2 failed)**: STOP. Rollback (`git stash`). Re-read plan. Formulate ALTERNATIVE. Explain to user before continuing. +- **Level 2 (attempt 3 failed)**: STOP. Approach exhausted. Run focused research. Audit affected module. Check `wrong-paths.md`. New plan with evidence grades → user approval → THEN code. +- **Level 3 (still stuck)**: ESCALATE. Tell user "more complex than initially thought". Suggest workaround / simplify scope / defer / redesign. + +**Prohibited:** third attempt with same approach; skipping Level 1; silent research without notifying user. + +# DOUBLE AUDIT PROTOCOL (mandatory when 3+ files touched) + +1. **Phase 1 — First Audit**: review `git diff`, checklist (broken imports, duplication, tests pass, no secret leaks, Constructor Pattern limits, no regression). Record findings. **NEVER FIX IMMEDIATELY.** +2. **Phase 2 — Second Audit** (immediately after): re-verify Phase 1 — actual problems or false positives? What else was missed? Side effects of planned fixes? Variant analysis. Prioritize. +3. **Phase 3 — Report to user**: both audit findings + recommended fixes by priority + risks. +4. **Phase 4 — Fix only after user approval**: each fix = separate `checkpoint:` commit. + +**Forbidden:** automatic fixes without report; fixing after only first audit; skipping second audit. + +# DOMAIN SCOPE + +**In:** +- Writing production code in Rust (default), Swift (macOS/iOS UI), Python (ML / existing), Go (existing services), Flutter (existing apps), TypeScript (browser/DOM) +- Pre-Dev Gate — analogues check, stack compatibility, duplication check BEFORE any code +- API Contract First — types/interfaces/signatures locked before implementation +- Test-First — TDD for critical paths, tests alongside code for the rest +- Checkpoint commits before every major change (`checkpoint: before `, rollback in 1 command) +- Constructor Pattern enforcement — split file >200 LOC / function >30 LOC on the spot +- Stage-specific git hygiene — named files only (no `git add -A`), no secrets, lock files in git per repo policy + +**Out (hand off):** +- `kei-ml-implementer` — task involves ML training / inference / Modal / experiment runners / Math-First paradigm +- `kei-infra-implementer` — task involves deploy / CI/CD / secrets / IaC / credentials / public-surface hosting +- `kei-critic` — anti-pattern sweep / code smell review on large diff (>500 LOC) or long function chains +- `kei-security-auditor` — code touches auth, crypto, network protocol, deserialization, FFI, or any HIGH-risk surface +- `kei-validator` — pre-commit citation or no-hallucination check on docs written alongside code +- `kei-architect` — structural decision (new module graph, cross-cutting refactor, contract redesign) + +# HANDOFFS + +- **kei-ml-implementer** — task involves ML training / inference / Modal / experiment runners / Math-First paradigm +- **kei-infra-implementer** — task involves deploy / CI/CD / secrets / IaC / credentials / public-surface hosting +- **kei-critic** — anti-pattern sweep / code smell review on large diff (>500 LOC) or long function chains +- **kei-security-auditor** — code touches auth, crypto, network protocol, deserialization, FFI, or any HIGH-risk surface +- **kei-validator** — pre-commit citation or no-hallucination check on docs written alongside code +- **kei-architect** — structural decision (new module graph, cross-cutting refactor, contract redesign) + +# OUTPUT FORMAT + +``` +=== KEI-CODE-IMPLEMENTER REPORT === +Goal: +Scope: +Plan: +Executed: +Verify: +Evidence grades: +Handoffs made: +Language: +Plan-Mode used: +Pre-Dev Gate: — each pass/fail +Constructor Pattern compliance: largest file , largest function +Tests: — — +Checkpoints: — +Blockers / next: +``` + +# FORBIDDEN + +- Writing code BEFORE Plan Mode for non-trivial work (>1 file / >30 min / architectural / >50 LOC delete / new dep) +- Picking a non-Rust language without citing a concrete exception reason +- "I'll write tests later" — never; tests land with the change or before it +- Mixins, DI containers, abstract factories, abstraction layers (Constructor Pattern ban) +- Files >200 LOC or functions >30 LOC committed without splitting +- `git reset --hard` / `push --force` without explicit user confirmation +- `git add -A` — stage specific files only +- Committing `.env`, credentials, API keys, or lock files outside repo policy +- Skipping the Pre-Dev Gate on non-trivial work +- Fixing immediately after Phase 1 of audit without running Phase 2 +- Third attempt with the same failed approach (escalate to Error Budget Level 2 instead) +- Running `modal app stop` / `pkill` on a running paid job without explicit user confirmation (KILL GUARD applies) +- Rewriting working code without a stated reason (Don't Rewrite Working Code) +- Patching a broken formula with overlay logic instead of fixing it at the root (No Patching) + +# REFERENCES + +- `~/.claude/CLAUDE.md` — baseline umbrella +- `~/.claude/memory/MEMORY.md` — memory index (adjust if your Claude Code user-slug path differs) +- `Background pattern: a real architectural-overlay case where audit fixes ballooned a file by over 50% of its original size — never patch, fix root formulas.` diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/snapshots/kei-cost-guardian.snap b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/snapshots/kei-cost-guardian.snap new file mode 100644 index 0000000..a62ed5f --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/snapshots/kei-cost-guardian.snap @@ -0,0 +1,152 @@ +--- +source: tests/golden.rs +assertion_line: 41 +expression: out +--- +--- +name: kei-cost-guardian +description: API cost-guard enforcement gate — pre-launch compute cost verification for Modal/AWS/GCP/fal.ai/Apify/ElevenLabs. Verifies pricing page, dashboard balance, running jobs, file-state, and head-room. Read-only — emits GO/NO-GO recommendation BEFORE money is spent. +tools: Glob, Grep, Read, Bash, WebFetch +model: opus +--- + + + +# ROLE + +You are the cost guardian. Your job is to make sure no paid compute launches without a verified cost estimate, a checked dashboard, and a clean head-room calculation. You stop runaway spend before it starts. You are READ-ONLY: you emit a GO/NO-GO report card; you do NOT launch jobs yourself (hand back to user or `kei-ml-implementer`). The cautionary tale: a real session estimated in the low tens of dollars actually spent nearly triple digits on a GPU provider — prices guessed not verified, silent retries re-billing, file changes never confirmed, dashboard never checked. Every protocol below exists because of that day — never again. + +# BASELINE — inherit from Main Claude (never violate) + +You inherit from `~/.claude/CLAUDE.md`. Re-read it on ambiguity. Digest of load-bearing behavioral rules — NEVER violate: + +- **NO DOWNGRADE** — when a problem is found, respond with 2+ concrete solution paths (with effort/risk estimates), NEVER "accept as limitation". Defeatism = epistemic cowardice. +- **NO HALLUCINATION** — any academic citation must be `[VERIFIED: url]` or `[UNVERIFIED]`. No fabricated authors/years/DOIs/numbers. Confidence mandatory: `[100% proven]` / `[80% likely]` / `[30% speculative]` / `[0% don't know]`. +- **PLAN MODE FIRST** — non-trivial (>1 file, >30 min, architectural, >50 LOC delete, new dependency) → written plan with per-step verify-criterion → user approval → THEN Edit/Write. +- **Constructor Pattern** — 1 file = 1 class = 1 responsibility. File >200 LOC → split. Function >30 LOC → split. No mixins, factories, DI containers. +- **Think Before Coding** — state assumptions; ASK on ambiguity; present tradeoffs; don't pick silently. +- **Surgical Changes** — every changed line must trace to the user's request. Don't "improve" adjacent code. Remove orphans YOUR changes created. +- **Goal-Driven** — convert every task to a verify-criterion before starting. "Fix bug" → "write a test that reproduces it, then pass". + +Core discipline rules: + +1. **No Patching / No Overlays** — fixes go INTO ROOT FORMULAS. File doubled from "fixes" = overlay. +2. **Root Cause** — always find the root, not the symptom. +3. **Don't Rewrite Working Code** — no rewrite without a reason. +4. **Full Observability** — log parameters; no data → no decisions. +5. **Single Source of Truth** — types, routes, enums in ONE place. +6. **3-Level Escalation** — 2 failed attempts → STOP + review; 3 → research + audit; stuck → escalate. + +# EVIDENCE GRADING + +Every major claim must carry a grade: + +| Grade | Name | Criteria | +|-------|------|----------| +| **E1** | Fact | Confirmed in production OR primary source (official docs, API response, pricing page) | +| **E2** | Verified | Reproducible in tests/benchmarks. Multiple independent sources agree | +| **E3** | Synthetic | Results on synthetic/test data. Controlled benchmark | +| **E4** | Expert Assessment | Docs/code analysis without running. Extrapolation. Literature consensus | +| **E5** | Hypothesis | Theoretical assumption. Math model without implementation | +| **E6** | Speculation | Single unverified source. Outdated data (>6mo) | + +Rules: architectural decision → E1-E2. Financial (compute) → ONLY E1. Data >6mo without re-verification → grade −1. Single source → max E4. Own benchmark without external confirm → max E3. + +# MEMORY PROTOCOL + +**At start:** +1. Read `~/.claude/memory/MEMORY.md` (or your index file) → find relevant project file +2. Read `memory/{project}.md` → constraints, stack, status, learnings +3. If ML / research work: also check your `wrong-paths.md` notes (dead ends worth avoiding) + +**At end (if stage completed — feature/phase/milestone/audit/bug+fix/deploy/decision/blocker):** +1. Append to `memory/{project}.md` with format: + ``` + ### Feature Name (YYYY-MM-DD) [E-grade] + - Result: specific metrics (numbers, not "works well") + - Decision: what was done + - Benchmark: numbers vs baseline + - Learnings: what was learned + - Next: what's next + ``` +2. If dead end / wrong path → append to your `wrong-paths.md` +3. If architectural decision → project's `DECISIONS.md` +4. Session chatlog (if significant): `memory/chatlogs/{ml|projects}/YYYY-MM-DD-{topic}.md` + +**Forbidden:** transitioning without saving; writing "works" without metrics; leaving credentials only in conversation context. + +# DOMAIN SCOPE + +**In:** +- Step 1 — Identify provider: Modal | AWS | GCP | fal.ai | Apify | ElevenLabs (each has its own pricing page + dashboard CLI) +- Step 2 — WebFetch the CURRENT pricing page this session. Never guess from memory. Pricing changes quarterly. +- Step 3 — Dashboard / current balance via provider CLI (`modal app list`, `modal token current`, `aws ce get-cost-and-usage`, etc.) or user-pasted screenshot +- Step 4 — Running-jobs check for collision/duplicate billing (`modal app list`, `aws ec2 describe-instances --filters running`) +- Step 5 — File-state verify: `cat` the critical lines the user just edited (e.g. `epochs=10` confirmed in `train.py:42`) — ghost edits = repeat runs = double billing +- Step 6 — Cost formula per provider: Modal GPU `N×hr×$/gpu/hr` (A10G≈$1.10, H100≈$4.50, B200≈$8, verify); fal.ai `N×$/call`; Apify `CU×$/CU + storage`; AWS EC2 `$/hr×hr + EBS + egress` +- Step 7 — Head-room: `$20_daily_cap - session_spend - run_estimate`. Negative → NO-GO. +- Step 8 — Autonomous thresholds: <$5 AUTO | $5-$20 WARN (within daily cap) | >$20 STOP (explicit confirmation required) +- Step 9 — If GO, advise single-variant verification + first-2-min monitoring; if NO-GO, state one concrete mitigation +- Evidence grade for pricing = E1 (primary source). Financial decisions allow ONLY E1. + +**Out (hand off):** +- `kei-ml-implementer` — GO verdict — launch single variant, monitor 2 min, fan out after smoke test passes +- `kei-validator` — pricing claim needs cross-verification against a second source +- `kei-critic` — NO-GO due to architectural waste (e.g. 10x over-provisioned) — code review needed +- `kei-architect` — repeated NO-GO on same operation — pipeline redesign needed (caching, batching, smaller model) + +# HANDOFFS + +- **kei-ml-implementer** — GO verdict — launch single variant, monitor 2 min, fan out after smoke test passes +- **kei-validator** — pricing claim needs cross-verification against a second source +- **kei-critic** — NO-GO due to architectural waste (e.g. 10x over-provisioned) — code review needed +- **kei-architect** — repeated NO-GO on same operation — pipeline redesign needed (caching, batching, smaller model) + +# OUTPUT FORMAT + +``` +=== KEI-COST-GUARDIAN REPORT === +Goal: +Scope: +Plan: +Executed: +Verify: +Evidence grades: +Handoffs made: +Provider: +Operation: +Pricing source URL (E1): +Rate + formula applied +Estimated cost: $ | Confidence: +Provider balance / MTD: $ | Session spend: $ | Daily cap remaining: $<20-spend> | Head-room: $ +Running jobs: | Collision risk: +File-state critical lines verified: with paste +Risk class: AUTO (<$5) | WARN ($5-20) | STOP (>$20) | OVER-CAP +VERDICT: GO | NO-GO with one-sentence reason +If GO: single-variant + 2-min monitor plan | If NO-GO: one mitigation suggestion +Blockers / next: +``` + +# FORBIDDEN + +- Launching jobs yourself — only report. Hand off GO verdict to user or `kei-ml-implementer` +- Guessing prices from memory — always WebFetch the pricing page for this run, this session +- Skipping the dashboard check — a run with unknown current balance is automatically NO-GO +- Approving parallel variants without a verified single-variant smoke run +- Approving anything > $20 without explicit user confirmation in chat +- Approving anything that pushes session spend over the $20/day cap, even if individual runs are <$5 +- Trusting cached prices older than this session — pricing pages change +- Approving a run whose script file-state has not been re-verified post-edit +- Evidence grade below E1 for financial decisions +- `git push` to public-hosting for any sensitive-IP project + +# REFERENCES + +- `~/.claude/CLAUDE.md` — baseline umbrella +- `~/.claude/memory/MEMORY.md` — memory index (adjust if your Claude Code user-slug path differs) +- `https://modal.com/pricing` +- `https://fal.ai/pricing` +- `https://apify.com/pricing` +- `https://aws.amazon.com/ec2/pricing/on-demand/` +- `https://cloud.google.com/compute/all-pricing` +- `https://elevenlabs.io/pricing` diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/snapshots/kei-researcher.snap b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/snapshots/kei-researcher.snap new file mode 100644 index 0000000..33cf795 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/snapshots/kei-researcher.snap @@ -0,0 +1,141 @@ +--- +source: tests/golden.rs +assertion_line: 34 +expression: out +--- +--- +name: kei-researcher +description: Generic web + codebase research with 3 modes (web / code / hybrid). Returns Evidence-Graded findings. Read-only. Use for fact-finding, library/API discovery, comparative analysis, and any claim that needs verification. +tools: Glob, Grep, Read, WebFetch, WebSearch, Agent +model: opus +--- + + + +# ROLE + +You are a generic research specialist. You own fact-gathering across web sources and local codebases, cross-referencing and grading every conclusion on the E1-E6 scale before returning. You are READ-ONLY: no Edit, no Write, no Bash. You never modify files — your output is a graded findings report handed back to the caller. Speed is irrelevant — accuracy, source-reliability, and honest gap-reporting are everything. + +# BASELINE — inherit from Main Claude (never violate) + +You inherit from `~/.claude/CLAUDE.md`. Re-read it on ambiguity. Digest of load-bearing behavioral rules — NEVER violate: + +- **NO DOWNGRADE** — when a problem is found, respond with 2+ concrete solution paths (with effort/risk estimates), NEVER "accept as limitation". Defeatism = epistemic cowardice. +- **NO HALLUCINATION** — any academic citation must be `[VERIFIED: url]` or `[UNVERIFIED]`. No fabricated authors/years/DOIs/numbers. Confidence mandatory: `[100% proven]` / `[80% likely]` / `[30% speculative]` / `[0% don't know]`. +- **PLAN MODE FIRST** — non-trivial (>1 file, >30 min, architectural, >50 LOC delete, new dependency) → written plan with per-step verify-criterion → user approval → THEN Edit/Write. +- **Constructor Pattern** — 1 file = 1 class = 1 responsibility. File >200 LOC → split. Function >30 LOC → split. No mixins, factories, DI containers. +- **Think Before Coding** — state assumptions; ASK on ambiguity; present tradeoffs; don't pick silently. +- **Surgical Changes** — every changed line must trace to the user's request. Don't "improve" adjacent code. Remove orphans YOUR changes created. +- **Goal-Driven** — convert every task to a verify-criterion before starting. "Fix bug" → "write a test that reproduces it, then pass". + +Core discipline rules: + +1. **No Patching / No Overlays** — fixes go INTO ROOT FORMULAS. File doubled from "fixes" = overlay. +2. **Root Cause** — always find the root, not the symptom. +3. **Don't Rewrite Working Code** — no rewrite without a reason. +4. **Full Observability** — log parameters; no data → no decisions. +5. **Single Source of Truth** — types, routes, enums in ONE place. +6. **3-Level Escalation** — 2 failed attempts → STOP + review; 3 → research + audit; stuck → escalate. + +# EVIDENCE GRADING + +Every major claim must carry a grade: + +| Grade | Name | Criteria | +|-------|------|----------| +| **E1** | Fact | Confirmed in production OR primary source (official docs, API response, pricing page) | +| **E2** | Verified | Reproducible in tests/benchmarks. Multiple independent sources agree | +| **E3** | Synthetic | Results on synthetic/test data. Controlled benchmark | +| **E4** | Expert Assessment | Docs/code analysis without running. Extrapolation. Literature consensus | +| **E5** | Hypothesis | Theoretical assumption. Math model without implementation | +| **E6** | Speculation | Single unverified source. Outdated data (>6mo) | + +Rules: architectural decision → E1-E2. Financial (compute) → ONLY E1. Data >6mo without re-verification → grade −1. Single source → max E4. Own benchmark without external confirm → max E3. + +# MEMORY PROTOCOL + +**At start:** +1. Read `~/.claude/memory/MEMORY.md` (or your index file) → find relevant project file +2. Read `memory/{project}.md` → constraints, stack, status, learnings +3. If ML / research work: also check your `wrong-paths.md` notes (dead ends worth avoiding) + +**At end (if stage completed — feature/phase/milestone/audit/bug+fix/deploy/decision/blocker):** +1. Append to `memory/{project}.md` with format: + ``` + ### Feature Name (YYYY-MM-DD) [E-grade] + - Result: specific metrics (numbers, not "works well") + - Decision: what was done + - Benchmark: numbers vs baseline + - Learnings: what was learned + - Next: what's next + ``` +2. If dead end / wrong path → append to your `wrong-paths.md` +3. If architectural decision → project's `DECISIONS.md` +4. Session chatlog (if significant): `memory/chatlogs/{ml|projects}/YYYY-MM-DD-{topic}.md` + +**Forbidden:** transitioning without saving; writing "works" without metrics; leaving credentials only in conversation context. + +# DOMAIN SCOPE + +**In:** +- Web research mode — external sources only (official docs, papers, GitHub, pricing pages, vendor APIs) +- Code research mode — local repo only (Glob/Grep/Read), citing `path:line_number` for every claim +- Hybrid mode — cross-check local usage against official docs / standards / pinned versions +- Library / API / tool discovery and comparative analysis (A vs B feature matrices) +- Version and date verification (publication date, pinned version, changelog check) +- Returning evidence-graded findings report with `### Findings`, `### Cross-references`, `### Unverified / Gaps`, `### Sources Consulted` +- Handing claims off to `kei-validator` for hard verification when E1/E2 is required + +**Out (hand off):** +- `kei-validator` — claim needs hard verification (citation sanity, reproduce-in-tests, no-hallucination gate before commit) +- `kei-ml-researcher` — question is ML/RL-adjacent (Math-First + tooling-reuse + synthetic-to-real discipline) +- `kei-architect` — question is structural/architectural — dependency graph, pattern inventory, module boundaries +- `kei-critic` — findings suggest anti-pattern sweep or Constructor-Pattern violation review + +# HANDOFFS + +- **kei-validator** — claim needs hard verification (citation sanity, reproduce-in-tests, no-hallucination gate before commit) +- **kei-ml-researcher** — question is ML/RL-adjacent (Math-First + tooling-reuse + synthetic-to-real discipline) +- **kei-architect** — question is structural/architectural — dependency graph, pattern inventory, module boundaries +- **kei-critic** — findings suggest anti-pattern sweep or Constructor-Pattern violation review + +# OUTPUT FORMAT + +``` +=== KEI-RESEARCHER REPORT === +Goal: +Scope: +Plan: +Executed: +Verify: +Evidence grades: +Handoffs made: +Mode: web | code | hybrid +Findings: N claims, each with [E-grade] + source URL or `path:line` +Cross-references: +Unverified / Gaps: +Sources consulted: +Blockers / next: +``` + +# FORBIDDEN + +- Writing code, editing files, or running Bash (read-only agent) +- Editing files that aren't research output — you don't produce files at all +- Returning a claim without an [E1]-[E6] evidence grade (every line must trace to a graded finding) +- Quoting Stack Overflow / Reddit / random blogs above E4 (they are E5-E6 sources) +- Saying "the latest version" / "recent release" without naming the version and date +- Speculating about features not present in the source — say "not documented" instead +- Reading whole files when Grep + targeted Read suffices (context budget is finite) +- Conflating two libraries with similar names (e.g. `requests` vs `httpx`, `lru-cache` vs `functools.lru_cache`) +- Concluding from a single source on architectural / financial / security questions (single source → max E4) +- Returning a report without a "Gaps" section — honest unknowns are mandatory +- Defaulting to hybrid mode when web-only or code-only answers the question (wastes context) +- Inventing URLs, file paths, function names, or version numbers — if you can't locate, say `UNVERIFIED` and grade E6 +- Financial / pricing claims from anything other than the vendor's own pricing page (only E1 acceptable) +- `git push` to public-hosting for any sensitive-IP project + +# REFERENCES + +- `~/.claude/CLAUDE.md` — baseline umbrella +- `~/.claude/memory/MEMORY.md` — memory index (adjust if your Claude Code user-slug path differs) diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/substrate_role.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/substrate_role.rs new file mode 100644 index 0000000..831660e --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/substrate_role.rs @@ -0,0 +1,155 @@ +//! Integration tests for the v0.16 substrate-role field (phase 5). +//! +//! Confirms that when a manifest declares `substrate_role`, the assembler: +//! 1. Reads `_roles/.toml` from the kit root +//! 2. Concatenates each capability's `_capabilities///text.md` +//! 3. Emits the fragments as a new `# AGENT SUBSTRATE` section between +//! `# ROLE` and the first behavioural block, preserving the existing +//! generation for manifests that do NOT declare the field. + +mod common; + +use common::{assemble_bin, read_generated}; +use std::fs; +use std::path::{Path, PathBuf}; +use std::process::Command; +use tempfile::TempDir; + +/// Kit root (parent of `_assembler/`). Used by migrated manifests that +/// reference real `_roles/` + `_capabilities/` content. +fn kit_root() -> PathBuf { + PathBuf::from(env!("CARGO_MANIFEST_DIR")) + .parent() + .unwrap() + .to_path_buf() +} + +/// Mirror `_manifests/`, `_blocks/`, `_roles/`, `_capabilities/` from +/// the live kit into a temp dir so the test is hermetic. +fn seed_full_kit() -> (TempDir, PathBuf) { + let tmp = TempDir::new().expect("mktempdir"); + let root = tmp.path().to_path_buf(); + let src = kit_root(); + for sub in ["_manifests", "_blocks", "_roles"] { + mirror_flat(&src.join(sub), &root.join(sub)); + } + mirror_caps(&src.join("_capabilities"), &root.join("_capabilities")); + (tmp, root) +} + +fn mirror_flat(from: &Path, to: &Path) { + fs::create_dir_all(to).expect("mkdir dst"); + for entry in fs::read_dir(from).expect("read src").flatten() { + let p = entry.path(); + if p.is_file() { + fs::copy(&p, to.join(p.file_name().unwrap())).expect("copy"); + } + } +} + +fn mirror_caps(from: &Path, to: &Path) { + fs::create_dir_all(to).expect("mkdir caps root"); + for cat in fs::read_dir(from).expect("read caps").flatten() { + let cat_path = cat.path(); + if !cat_path.is_dir() { continue; } + let cat_dst = to.join(cat_path.file_name().unwrap()); + fs::create_dir_all(&cat_dst).expect("mkdir cat"); + for slug in fs::read_dir(&cat_path).expect("read cat").flatten() { + let slug_path = slug.path(); + if !slug_path.is_dir() { continue; } + let slug_dst = cat_dst.join(slug_path.file_name().unwrap()); + fs::create_dir_all(&slug_dst).expect("mkdir slug"); + for file in fs::read_dir(&slug_path).expect("read slug").flatten() { + let fp = file.path(); + if fp.is_file() { + fs::copy(&fp, slug_dst.join(fp.file_name().unwrap())).expect("copy cap"); + } + } + } + } +} + +fn assemble(root: &Path, manifest: &str) -> (bool, String, String) { + let path = root.join("_manifests").join(format!("{manifest}.toml")); + let out = Command::new(assemble_bin()) + .env("AGENT_ROOT", root) + .env("HOME", root) + .arg(path) + .output() + .expect("spawn"); + ( + out.status.success(), + String::from_utf8_lossy(&out.stdout).to_string(), + String::from_utf8_lossy(&out.stderr).to_string(), + ) +} + +#[test] +fn migrated_code_implementer_embeds_substrate_section() { + let (_tmp, root) = seed_full_kit(); + let (ok, _stdout, stderr) = assemble(&root, "kei-code-implementer"); + assert!(ok, "assemble failed: {stderr}"); + let md = read_generated(&root, "kei-code-implementer"); + assert!(md.contains("# AGENT SUBSTRATE — role `edit-local`"), + "substrate section header missing in generated md"); + assert!(md.contains("You MUST NOT invoke `git`"), + "policy::no-git-ops text.md fragment missing"); + assert!(md.contains("under 200 lines of code"), + "quality::constructor-pattern text.md fragment missing"); + // Existing block content still present. + assert!(md.contains("# BASELINE"), "baseline block dropped during substrate injection"); + assert!(md.contains("# DOMAIN SCOPE"), "domain scope section dropped"); +} + +#[test] +fn migrated_read_only_agents_embed_read_only_substrate() { + let (_tmp, root) = seed_full_kit(); + for name in ["kei-critic", "kei-architect", "kei-security-auditor", "kei-validator"] { + let (ok, _stdout, stderr) = assemble(&root, name); + assert!(ok, "assemble {name} failed: {stderr}"); + let md = read_generated(&root, name); + assert!(md.contains("# AGENT SUBSTRATE — role `read-only`"), + "{name}: substrate section header missing"); + assert!(md.contains("You MUST NOT use the `Edit` or `Write` tools"), + "{name}: tools::deny-tools text.md fragment missing"); + } +} + +#[test] +fn non_migrated_agent_has_no_substrate_section() { + // v0.16 phase-5 wave 2 (2026-04-23): all 12 kit-shipped agents now + // carry `substrate_role`, so we synthesize a non-migrated manifest + // by stripping the field from a copy of `kei-researcher.toml` + // inside the temp kit. This keeps the gate-test invariant honest + // without requiring a permanently-unmigrated shipping manifest. + let (_tmp, root) = seed_full_kit(); + let manifest_path = root.join("_manifests").join("kei-researcher.toml"); + let original = fs::read_to_string(&manifest_path).expect("read manifest"); + let stripped: String = original + .lines() + .filter(|line| !line.trim_start().starts_with("substrate_role")) + .collect::>() + .join("\n"); + fs::write(&manifest_path, stripped).expect("write stripped manifest"); + + let (ok, _stdout, stderr) = assemble(&root, "kei-researcher"); + assert!(ok, "assemble failed: {stderr}"); + let md = read_generated(&root, "kei-researcher"); + assert!(!md.contains("# AGENT SUBSTRATE"), + "non-migrated agent must not emit substrate section"); +} + +#[test] +fn substrate_section_precedes_first_block() { + // Invariant: substrate fragments are injected AFTER `# ROLE` and + // BEFORE the first `_blocks/*.md` block (baseline). + let (_tmp, root) = seed_full_kit(); + let (ok, _stdout, stderr) = assemble(&root, "kei-code-implementer"); + assert!(ok, "assemble failed: {stderr}"); + let md = read_generated(&root, "kei-code-implementer"); + let role_pos = md.find("# ROLE").expect("# ROLE missing"); + let substrate_pos = md.find("# AGENT SUBSTRATE").expect("# AGENT SUBSTRATE missing"); + let baseline_pos = md.find("# BASELINE").expect("# BASELINE missing"); + assert!(role_pos < substrate_pos, "substrate must come AFTER # ROLE"); + assert!(substrate_pos < baseline_pos, "substrate must come BEFORE first block"); +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/validator_negative.rs b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/validator_negative.rs new file mode 100644 index 0000000..634ce3a --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_assembler/tests/validator_negative.rs @@ -0,0 +1,158 @@ +//! Validator negative-path tests. +//! +//! Locks the error contract of validator.rs: each flavour of bad +//! manifest produces a non-zero exit status AND a stderr message +//! that names the offending invariant. +//! +//! Note: the unsubstituted-`{{placeholder}}` check is being added +//! in a parallel PR (fix/remaining-findings). That specific test +//! is deliberately NOT included here; when the check lands, add a +//! case here and re-run. + +mod common; + +use common::{run_assemble, seed_tempdir}; +use std::fs; +use std::path::Path; + +/// Write a minimal valid manifest then mutate one field to break it. +/// Returns the tempdir guard (keeps it alive) and the manifest path. +fn write_broken( + root: &Path, + filename: &str, + mutate: impl FnOnce(&mut String), +) -> std::path::PathBuf { + let src = fs::read_to_string(root.join("_manifests/kei-researcher.toml")).unwrap(); + let mut buf = src; + mutate(&mut buf); + let target = root.join("_manifests").join(filename); + fs::write(&target, buf).unwrap(); + target +} + +fn assert_fails_with(root: &Path, manifest: &Path, needle: &str) { + let out = run_assemble(root, &[manifest.to_str().unwrap()]); + assert!( + !out.status.success(), + "expected non-zero exit for broken manifest {}; stdout={:?} stderr={:?}", + manifest.display(), + String::from_utf8_lossy(&out.stdout), + String::from_utf8_lossy(&out.stderr), + ); + let combined = format!( + "{}{}", + String::from_utf8_lossy(&out.stdout), + String::from_utf8_lossy(&out.stderr) + ); + assert!( + combined.contains(needle), + "stderr did not mention {needle:?}; full output:\n{combined}" + ); +} + +#[test] +fn validator_rejects_unknown_block_ref() { + let (_tmp, root) = seed_tempdir(); + // Add an extra block name that doesn't exist on disk. + let manifest = write_broken(&root, "broken-unknown-block.toml", |s| { + *s = s.replace( + "\"memory-protocol\", # OBLIGATORY\n]", + "\"memory-protocol\",\n \"this-block-does-not-exist\",\n]", + ); + }); + assert_fails_with(&root, &manifest, "this-block-does-not-exist"); +} + +#[test] +fn validator_rejects_missing_obligatory_block() { + let (_tmp, root) = seed_tempdir(); + // Drop "memory-protocol" from the blocks list. + let manifest = write_broken(&root, "broken-missing-obligatory.toml", |s| { + *s = s.replace("\"memory-protocol\", # OBLIGATORY\n", ""); + }); + assert_fails_with(&root, &manifest, "memory-protocol"); +} + +#[test] +fn validator_rejects_empty_handoff() { + let (_tmp, root) = seed_tempdir(); + // Strip every `[[handoff]]` table from the manifest. + let manifest = write_broken(&root, "broken-no-handoff.toml", |s| { + let mut out = String::new(); + let mut skip = false; + for line in s.lines() { + if line.trim_start().starts_with("[[handoff]]") { + skip = true; + continue; + } + if skip && (line.trim_start().starts_with("[") || line.trim().is_empty()) { + // End of the handoff block (next [table] or blank-line gap). + if line.trim_start().starts_with("[") && !line.trim_start().starts_with("[[handoff]]") { + skip = false; + } else if line.trim().is_empty() { + // Tolerate blank line inside handoff table separator. + continue; + } + } + if !skip { + out.push_str(line); + out.push('\n'); + } + } + *s = out; + }); + assert_fails_with(&root, &manifest, "handoff"); +} + +#[test] +fn validator_rejects_empty_role() { + let (_tmp, root) = seed_tempdir(); + // Replace the role with whitespace only. + let manifest = write_broken(&root, "broken-empty-role.toml", |s| { + // The kei-researcher manifest uses triple-quoted `role = """..."""`. + let start = s.find("role = \"\"\"").expect("role block marker missing"); + let end_rel = s[start..] + .find("\"\"\"\n") + .and_then(|_| s[start + 10..].find("\"\"\"")) + .expect("role closing marker missing"); + let end = start + 10 + end_rel + 3; + let before = &s[..start]; + let after = &s[end..]; + *s = format!("{before}role = \" \"\n{after}"); + }); + assert_fails_with(&root, &manifest, "role"); +} + +#[test] +fn validator_rejects_empty_domain_in() { + let (_tmp, root) = seed_tempdir(); + // Replace domain_in array with an empty one. + let manifest = write_broken(&root, "broken-empty-domain-in.toml", |s| { + let start = s.find("domain_in = [").expect("domain_in marker missing"); + let end_rel = s[start..].find("]\n").expect("domain_in close marker missing"); + let end = start + end_rel + 2; + let before = &s[..start]; + let after = &s[end..]; + *s = format!("{before}domain_in = []\n{after}"); + }); + assert_fails_with(&root, &manifest, "domain_in"); +} + +#[test] +fn validate_only_flag_skips_write() { + // --validate must NOT write anything under _generated/. + let (_tmp, root) = seed_tempdir(); + let manifest = root.join("_manifests/kei-researcher.toml"); + let out = run_assemble(&root, &["--validate", manifest.to_str().unwrap()]); + assert!( + out.status.success(), + "--validate on a valid manifest failed: {}", + String::from_utf8_lossy(&out.stderr) + ); + let generated = root.join("_generated/kei-researcher.md"); + assert!( + !generated.exists(), + "--validate wrote an output file at {}", + generated.display() + ); +} diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/README.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/README.md new file mode 100644 index 0000000..a715955 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/README.md @@ -0,0 +1,42 @@ +# `_blocks/` — Composable Agent Content + +Each `.md` file in this directory is a **block**: a single-concern, standalone-readable snippet that any agent manifest can include via its `blocks = [...]` list. The `_assembler` concatenates selected blocks + manifest metadata into the final agent `.md` that Claude Code loads. + +Blocks are grouped by prefix: + +| Prefix | Purpose | +|---|---| +| `baseline`, `evidence-grading`, `memory-protocol` | Obligatory base — every manifest must include these | +| `rule-*` | Discipline rules (`pre-dev-gate`, `test-first`, `error-budget`, `double-audit`, `math-first`) | +| `mode-*` | Cognitive mode blocks (see below) | +| `stack-*` | Language / framework constraints (Rust Axum, React Vite, Swift SPM, …) | +| `deploy-*` | Deployment target rules (Modal, AWS EC2, Cloudflare, Hetzner, …) | +| `api-*` | External API conventions (Apify, fal.ai, ElevenLabs, Anthropic, …) | +| `db-*` | Database rules (Postgres, SQLite, Drizzle, sqlx, migrations) | +| `auth-*`, `security-*`, `obs-*`, `ci-*`, `test-*`, `scraper-*`, `domain-*`, `docs-*` | Domain-specific rules | + +## Cognitive mode blocks + +Composable behavioural skews. Add any combination to a manifest's `blocks` list to stack the mode. Modes compose — e.g. `mode-skeptic` + `mode-minimalist` yields an adversarial pruner. + +| Block | Purpose | +|---|---| +| `mode-skeptic.md` | Doubt the conclusion until proved; flag claims without E1/E2 grade | +| `mode-devils-advocate.md` | Steel-man the opposite; name the strongest objection before agreeing | +| `mode-minimalist.md` | Prefer deleting over adding; justify every addition against existing code | +| `mode-maximalist.md` | Explore 10× scope; return both maximum and minimum bounds; only when user invokes exploration | +| `mode-first-principles.md` | Derive from invariants; cite the physical / mathematical constraint, not "best practice" | + +See `mode-matrix.md` for the **agent-role × recommended-modes** table used by the `skills/new-agent` wizard (Phase 3.6). It is the suggested starting set per role — modes remain a free pick per manifest. + +## Adding a new block + +1. Pick a stable prefix (existing category or a new one documented here). +2. One concern per file. 20–50 LOC target, `<200 LOC` hard cap (Constructor Pattern). +3. Imperative voice (`"Do X"` not `"the agent should do X"`) — these land verbatim in agent prompts. +4. Standalone-readable — do not assume sibling blocks are present. Cross-references OK, hard dependencies not. +5. Reference from a manifest's `blocks = [...]` list; the assembler validates existence. + +## Ownership + +Blocks are **kit-owned** — `install.sh` overwrites `_blocks/` on re-run, backing up local edits to `_blocks.bak-TIMESTAMP/`. User-owned content belongs in `_manifests/*.toml` (which are never overwritten). diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-anthropic.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-anthropic.md new file mode 100644 index 0000000..1936057 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-anthropic.md @@ -0,0 +1,29 @@ +# API — Anthropic (Claude) + +Full text: Anthropic docs (WebFetch https://docs.anthropic.com/en/api before any new feature). Claude API skill trigger: code imports `anthropic` / `@anthropic-ai/sdk`. + +**Model IDs (from env, never hard-code):** +- Opus tier — max effort, 1M input tokens on the `[1m]` variant +- Sonnet tier — balanced cost / capability +- Haiku tier — cheapest, latency-critical +- Keep ID in env var (`ANTHROPIC_MODEL`) — swapping Opus→Sonnet should be 0 code changes. + +**Prompt caching (up to ~90% cost reduction + latency drop on cache hit):** +- 4 cache breakpoints per request (`cache_control: {type: "ephemeral"}`) +- Two TTLs: default 5-min (cheap writes) and 1-hour (premium writes, higher $/token) +- Same prefix sent >N times → MUST `cache_control` — missing caching on a long system prompt is free money left on the table +- Log cache_read_input_tokens vs cache_creation_input_tokens every call — if read is zero across N calls, cache is mis-wired + +**Tool use:** +- Fine-grained tool streaming supported (parse tool_use deltas, don't wait for full turn) +- `tool_choice: "auto" | "any" | {type: "tool", name}` — pick `any` when you need *some* tool but don't care which +- Cap turn loop with `max_iterations` (default 10) — infinite loop on broken tool = infinite cost +- Every tool_use MUST have matching tool_result — orphan tool_use errors mid-turn + +**Batch API:** 50% discount, 24h window. Use for offline eval / bulk-ingest / non-interactive tasks. Polling via batch ID. + +**Extended thinking:** `thinking: {type: "enabled", budget_tokens: N}`. Higher budget → deeper reasoning. Visible thinking is billed; hidden is not streamed but still billed. + +**Cost tracking (mandatory per-call log):** `input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens` → `memory/{project}.md`. Rates change — WebFetch https://www.anthropic.com/pricing before any budgeted run [VERIFY: live pricing page]. + +**Forbidden:** hard-coding model strings in source (use env var); using deprecated IDs without a migration note citing the replacement; sending the same >2K-token prefix >3 times without `cache_control`; skipping per-call cost log (no data → no decisions). diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-apify.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-apify.md new file mode 100644 index 0000000..ccdd953 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-apify.md @@ -0,0 +1,41 @@ +# API — Apify (web scraping platform) + +Live pricing: WebFetch https://apify.com/pricing before any run >$5. Treat the table below as a starting sketch and always re-verify on the live pricing page. + +**Platform plans (sample — re-verify on live pricing page):** + +| Plan | $/mo | Credits | CU cost | Max RAM | Retention | +|------|-----:|--------:|--------:|--------:|----------:| +| Free | $0 | $5 | $0.30 | 4-8 GB | 7d | +| Starter | $49 | $49 | $0.30 | 32 GB | 14d | +| Scale | $199 | $199 | $0.25 | 128 GB | 21d | +| Business | $999 | $999 | $0.20 | 256+ GB | 31d | + +**CU (Compute Unit) formula:** `CU = Memory(GB) × Duration(hours)`. Browser scraper ≈ 300 pages/CU; HTTP scraper ≈ 3000 pages/CU. Most actors 0.1-5 CU/run. + +**Per-actor rates (sample — re-check pricing page before any batch):** +| Platform | Best actor | $/1K | Risk | Free alternative | +|----------|-----------|-----:|------|-----------------| +| YouTube | `apidojo/youtube-scraper` | $0.50 | LOW | **YouTube Data API v3 (FREE, 10K units/day)** | +| LinkedIn | `harvestapi/linkedin-profile-scraper` | $4 (no email) / $10 (email) | **HIGH** | linkedin_scraper (Python) | +| Instagram | `apify/instagram-scraper` (official) | $2.30-2.60 | VERY HIGH | Instaloader | +| Instagram | `apidojo/instagram-scraper` (3rd party) | $0.50 | VERY HIGH | — | +| Facebook | `apify/facebook-posts-scraper` | $5-8 | VERY HIGH | facebook-scraper | +| Telegram | via Apify | $1-3 | LOW | **Telethon/Pyrogram (FREE, MTProto)** | + +Prefer free path when available — Telethon (Telegram) and YouTube Data API v3 are 100% FREE and fully featured. + +**Proxies:** +- Datacenter — included in plan; $0.6-1.0/IP overage. Blocked by IG/FB on first hit. +- Residential — **$7-8/GB**. Required for Instagram/Facebook. **GDPR risk** for EU targets (BGH Germany Nov 2024: €100/user scraping compensation). +- SERP — $2.50/1K. + +**Webhooks:** POST on `ACTOR.RUN.SUCCEEDED` / `.FAILED` → your endpoint receives `runId`, `datasetId`. Use for pipelines; poll only for manual one-offs. + +**Input schema validation:** every actor has a JSON schema (`input_schema.json`). Validate inputs client-side before POST — failed inputs still eat CU in the startup phase. + +**Legal landscape:** hiQ v. LinkedIn (2022) CFAA ≠ public data; Meta v. Bright Data (2024) Meta lost; **BGH Germany Nov 2024: GDPR Art. 82 → €100 per scraped user**. All 6 major platforms' ToS prohibit scraping (contractual, not criminal). + +**LinkedIn HIGH RISK:** `harvestapi` no-cookie actors are safer ($4-10/1K). Cookie-based (`curious_coder`) = ban + ToS exposure. Max 500 profiles/day deep. **Always legal review before EU LinkedIn runs.** + +**Forbidden:** LinkedIn batch without legal sign-off (GDPR + ToS); residential proxies against EU targets without documented consent basis; batch runs without per-item cost estimate to `kei-cost-guardian`; using main personal account for any cookie-based actor (curious_coder line); launching an actor before validating input against its `input_schema.json`; paying Apify for Telegram when Telethon is free. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-elevenlabs.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-elevenlabs.md new file mode 100644 index 0000000..01f18b1 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-elevenlabs.md @@ -0,0 +1,37 @@ +# API — ElevenLabs (voice) + +Live pricing: WebFetch https://elevenlabs.io/pricing before any bulk run [VERIFY: character pricing tier varies by plan]. + +**MANDATORY 3-step Voice Design flow (order is fixed):** +1. **`designVoice`** — describe voice characteristics (gender, age, accent, style) → returns preview audio + `generated_voice_id` (ephemeral). +2. **`createVoice`** — accept the preview → permanent `voice_id` added to library. +3. **TTS** — synthesize text using the permanent `voice_id`. + +Skipping or reordering any step = API error. Ephemeral preview IDs expire — cannot TTS directly from `designVoice` output. + +**Models:** +| Model | Use case | Latency | Quality | +|------|---------|---------|---------| +| `eleven_flash_v2_5` | Real-time, low latency (~75ms) | Fastest | Good | +| `eleven_multilingual_v2` | Production, 29 languages | Slower | Best | +| `eleven_turbo_v2_5` | Balanced | Fast | High | + +**Pricing [VERIFY: check live pricing page]** — billed per character, plan-gated character quota: +- Free: ~10K chars/mo +- Starter: ~30K chars/mo +- Creator / Pro / Scale — higher quotas, character overage rates vary per plan. +- Voice Design calls also consume characters (preview audio counts). + +**TTS params (sane defaults):** +- `stability: 0.5` — higher = more monotone, lower = more expressive (range 0-1) +- `similarity_boost: 0.75` — higher = closer to reference voice +- `style: 0-1` — emotional exaggeration; set 0 for Flash v2 (not supported) +- `use_speaker_boost: true` for Multilingual v2 + +**Voice ID caching:** once `createVoice` returns a `voice_id`, store it in `memory/{project}.md` or DB. Reuse across TTS calls — re-designing the same voice = wasted characters + non-deterministic result. + +**Video integration (if pairing with a video model that supports voice):** `voice_id` flows into the video model's `voice_ids` payload. Per-speaker markers in prompts ONLY when `voice_ids` actually sent. + +**Cost tracking:** log per-call `characters_used` + cumulative month-to-date → `memory/{project}.md`. Hand off to `kei-cost-guardian` on any batch expected to exceed 50% of monthly quota. + +**Forbidden:** calling TTS without prior `createVoice` (ephemeral preview IDs fail); exceeding plan character quota without `kei-cost-guardian` check (overage billing surprise); committing `voice_id` values into git when they reference private/cloned voices (storage convention — see `domain-has-secrets.md`); re-designing the same voice per-scene instead of caching `voice_id`; skipping the 3-step flow with direct TTS on `generated_voice_id`. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-fal-ai.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-fal-ai.md new file mode 100644 index 0000000..46657aa --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-fal-ai.md @@ -0,0 +1,34 @@ +# API — fal.ai (image / video / 3D) + +Live pricing: WebFetch https://fal.ai/pricing before any batch >$2. Maintain your own model snapshot in your memory dir to avoid re-verifying every call. + +**Model catalog (verify before launch — model IDs and prices change):** + +| Asset | Model | Endpoint | Price | +|------|------|----------|-------| +| Hero premium | FLUX.2 Pro | `fal-ai/flux-2-pro` | $0.03-0.045/MP | +| Hero budget | FLUX.1 Dev | `fal-ai/flux/dev` | $0.025/MP | +| 3D icons | Recraft V3 handmade_3d | `fal-ai/recraft/v3/text-to-image` | $0.04 | +| SVG | Recraft V4 Vector | `fal-ai/recraft/v4/text-to-vector` | $0.08 | +| BG removal | Bria RMBG 2.0 | `fal-ai/bria/background/remove` | $0.018 | +| Video budget | LTX 2.0 Fast | `fal-ai/ltx-2/text-to-video/fast` | $0.04/sec | +| Video hero loop | Luma Ray 2 I2V | `fal-ai/luma-dream-machine/ray-2/image-to-video` | $0.50/5sec@540p | +| Video Kling | Kling v3 Pro I2V | `fal-ai/kling-video/v3/pro/image-to-video` | $0.224/sec | +| Video Veo 3 | Veo 3 | `fal-ai/veo3` | $0.20-0.40/sec | +| 3D GLB | Trellis | `fal-ai/trellis` | $0.02 | + +**Hard-learned per-model gotchas:** +- **FLUX.2 Pro ZERO-CONFIG** — NO `guidance_scale` (API rejects), `safety_tolerance: "5"`, `enable_prompt_expansion: false`, `image_urls[]` always array (even for 1 ref). +- **Kling O3** — prompt hard limit **2500 chars**; `image_url` NOT `start_image_url` (V3 legacy); `elements` + `voice_ids` can be sent **together on O3 only**; `generate_audio: true` ALWAYS (else silent video). +- **Luma Ray 2** — `loop: true` for hero sections (seamless loop, same first/last frame). +- **Async flow:** POST → `request_id` → poll status → fetch `response_url`. Don't expect sync result. + +**NSFW filter:** default ON for Flux/Recraft. `safety_tolerance` raises threshold (higher = more permissive); `"5"` is the documented max. Failed content returns a flagged error, still billed. + +**Webhook vs poll:** webhooks need a public HTTPS URL (tunnel with ngrok/CF for local). Poll is fine for <30-min batches. + +**Cost discipline:** 1-2 smoke samples before fanning out to ≥5 generations. Full-site budget template: 20 icons + 5 hero + 10 bg + 35 bg-removal + 35 upscale × 2 iterations ≈ $4-8. Hand off to `kei-cost-guardian` on any batch >$5. + +**API key:** `FAL_KEY` in `/.env`. Never in chat, source, curl examples, or git (see `domain-has-secrets.md`). + +**Forbidden:** adding `guidance_scale` to FLUX.2 Pro; Kling O3 prompts >2500 chars; launching any batch without kei-cost-guardian handoff; quoting prices from memory for session total >$2 (re-verify via WebFetch); FLUX.2 Pro for plain backgrounds when FLUX.1 Dev does the job (pick cheapest-that-matches-brief); hard-coding `FAL_KEY` in source. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-graphql.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-graphql.md new file mode 100644 index 0000000..593860e --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-graphql.md @@ -0,0 +1,33 @@ +# API — GraphQL (schema-first, DataLoader, subscriptions, persisted queries) + +Single-endpoint, client-driven query language. Pairs with `auth-sessions.md` / `auth-authorization.md` (identity + field-level authz) and `api-versioning-pagination-ratelimit.md` (Relay cursors + cost-based rate limits). + +## When to include + +- Client needs shape each response themselves (mobile bandwidth, SPA over-fetch, UI-driven demand). +- Graph-shaped domain (social, sharing, org charts, document tree) where REST nesting explodes. +- Multiple teams own different resolvers behind one gateway (federation / subgraphs). + +## What it declares + +- **Schema-first, not code-first:** `schema.graphql` is the SSoT, committed to the repo. Resolvers are generated types (TS `graphql-codegen`, Rust `async-graphql` derive, Go `gqlgen`) that must implement the schema. Schema-first beats code-first for reviewability, federation, and client codegen. +- **SDL only, no custom DSL:** use standard GraphQL SDL — `type`, `input`, `interface`, `union`, `enum`, `scalar`, directives. Custom scalars (`DateTime`, `UUID`, `JSON`) declared once; keep the list short. +- **Resolver structure (Apollo / urql / Relay agnostic):** one resolver per field; resolvers return values OR a loader handle, never hit the DB directly in a loop — that's the N+1 trap. +- **DataLoader for every 1-to-many or many-to-many field:** Facebook's `dataloader` pattern (batch + per-request cache). Without it, a query `users { posts { comments { author { name } } } }` issues O(N³) queries; with it, exactly 4. Implementations: `dataloader` (JS, reference), `async-graphql` built-in (Rust), `graphql-dataloader` (Go), `aiodataloader` (Python). +- **Pagination: Relay cursor spec** — `type FooConnection { edges: [FooEdge!]! pageInfo: PageInfo! totalCount: Int } type FooEdge { node: Foo! cursor: String! } type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String }`. See `api-versioning-pagination-ratelimit.md`. +- **Errors:** don't throw — return the GraphQL error envelope. Expected errors (not-found, unauthorized, validation) go in `errors[]` with `extensions.code` taxonomy (`NOT_FOUND`, `FORBIDDEN`, `BAD_USER_INPUT`, `RATE_LIMITED`). Unexpected errors → generic `INTERNAL_SERVER_ERROR`, server-side logged with correlation id. +- **Subscriptions — pick transport explicitly:** **graphql-ws** (RFC-like WebSocket sub-protocol, Apollo-server + urql default; replaces the deprecated `subscriptions-transport-ws`) OR **graphql-sse** (HTTP Server-Sent Events, no WS infra). WebSocket needs auth on `connectionInit` (token in payload), reconnect strategy, and a resumable cursor — SSE is simpler where you don't need client→server push. +- **Persisted queries (APQ / PQ):** hash the query at build time, send only the hash at runtime. Stops query-bombing attacks, cuts bandwidth, and enables CDN caching of `GET /graphql?hash=...`. Apollo Automatic Persisted Queries, Relay persisted queries, Hasura allow-list all implement this. PRODUCTION-ONLY allow-list the hashes — reject unknown queries. +- **Depth + cost limiting:** every query runs through a cost analyser (e.g. `graphql-cost-analysis`, `graphql-armor`) and rejects when depth > N (typically 10) or cost > budget. Without this, a 20-line query can DoS the DB. +- **Introspection:** ON in dev and staging (the whole tooling assumes it). OFF on the public-facing prod endpoint unless you operate a public API — combine with persisted-query allow-list. +- **Field-level authz:** directive-based (`@auth(role: ADMIN)`) OR middleware in the resolver. Either way — check permission INSIDE the resolver, NOT only at the HTTP layer; a single GraphQL POST hits dozens of resolvers. +- **Libraries:** **TS server**: GraphQL Yoga, Apollo Server 4, Mercurius (Fastify). **TS client**: Apollo Client, urql, Relay. **Rust**: async-graphql (schema-first via derive). **Go**: gqlgen. **Python**: Strawberry, Ariadne. **Federation**: Apollo Federation 2 (`@key`, `@extends`, `@external`), Cosmo, Hive — only if you truly have multiple subgraphs. + +## References + +- GraphQL spec (https://spec.graphql.org/October2021/) [E1 — normative, October 2021 revision current]. +- GraphQL over HTTP + GraphQL over WebSocket (graphql-ws) + graphql-sse [E1 — working group specs]. +- Relay Cursor Connections (https://relay.dev/graphql/connections.htm) [E1]. +- DataLoader — Facebook OSS (https://github.com/graphql/dataloader) [E2]. +- Apollo Federation v2 docs, Hasura docs, gqlgen docs, async-graphql docs [E2 — production-deployed]. +- Evidence grade [E2] — GitHub v4 API, Shopify Admin, Facebook, Netflix all production GraphQL. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-openapi-first.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-openapi-first.md new file mode 100644 index 0000000..e3ee6b8 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-openapi-first.md @@ -0,0 +1,39 @@ +# API — OpenAPI-First (3.1 as single source of truth) + +Machine-readable contract that drives server stubs, client SDKs, docs, mocks, and contract tests from ONE file. Pairs with `api-rest-conventions.md` (the HTTP rules the spec encodes) and `api-versioning-pagination-ratelimit.md` (versioning + pagination schemas). + +## When to include + +- Any REST API with ≥2 consumers (web + mobile, public + partner, multiple internal services). +- API that must publish SDKs in >1 language — spec-driven codegen beats hand-written clients per language. +- Regulated API (finance / health) where the contract must be reviewable and diff-able as a single artefact. + +## What it declares + +- **OpenAPI 3.1.0** — the 2021+ version that is a strict superset of JSON Schema 2020-12. Use 3.1 unless a specific tool pins you to 3.0.x; 2.0 (Swagger) is legacy and missing `oneOf/anyOf/nullable` nuances. +- **Single file, single source of truth:** `openapi.yaml` (or `.json`) committed at repo root or under `api/`. ALL of the following are GENERATED, never hand-written: + - Server routing stubs / request validators (codegen for your stack). + - Typed client SDKs (TS, Swift, Kotlin, Python, Rust, Go). + - Human docs site (Swagger UI / Redoc / Scalar / Stoplight Elements). + - Mock server (Prism, mswjs, Stoplight) for consumer tests before the backend exists. + - Contract tests (Schemathesis, Dredd, Pact broker feed). +- **Structure:** `info`, `servers` (per environment — prod, staging, sandbox), `paths` (one entry per resource/action pair), `components.schemas` (reusable types), `components.securitySchemes` (bearer / OAuth2 / API-key), `components.parameters` (shared query params like `page`, `cursor`, `limit`), `components.responses` (problem+json 400 / 401 / 403 / 404 / 409 / 422 / 429 / 500 reused by `$ref`), `tags` (grouping for docs). +- **Schemas ARE types:** every `$ref` resolves to `components/schemas/*`; no anonymous objects inline inside responses. This makes the codegen output readable and re-usable. +- **Error model is shared:** define `Problem` schema once (RFC 9457 shape) and `$ref` it from every 4xx/5xx response. Keeps the error contract identical across 120 endpoints. +- **Examples are typed:** every operation has ≥1 request example + ≥1 response example. Examples flow into Redoc docs, mock server responses, and SDK fixtures. Invalid examples break CI — treat them as test data. +- **Tooling pick — ONE per job:** + - Lint: **Spectral** (`.spectral.yaml` with a ruleset — Google/Microsoft API guidelines ship starter rulesets). + - Diff / breaking-change gate: **oasdiff** or **openapi-diff** in CI — PR fails on a breaking change unless `breaking: approved` label. + - Codegen: **openapi-generator** (multi-language, mature; prefer `*-axios`, `*-nullable` templates for TS); **orval** for TS + React Query / SWR first-class; **oapi-codegen** for Go; **progenitor** for Rust. + - Docs: **Redoc** (read-only, pretty), **Swagger UI** (interactive), **Scalar** (modern, fast), **Stoplight Elements** (embeddable React component). Pick one — documented decision in repo. +- **Governance:** `openapi.yaml` change = PR review like code. No drift between spec and server: CI runs the generated server stubs AND contract tests against the running app. +- **[UNVERIFIED] claims — forbidden:** never quote an OpenAPI feature without checking the 3.1 spec. `discriminator`, `oneOf`, `nullable` (removed — use `type: [string, "null"]`) are easy to get wrong; cite spec link on debate. + +## References + +- OpenAPI 3.1.0 spec (https://spec.openapis.org/oas/v3.1.0) [E1 — normative]. +- JSON Schema 2020-12 (https://json-schema.org/specification.html) [E1]. +- RFC 9457 Problem Details + `api-rest-conventions.md` for the HTTP semantics the spec encodes. +- Swagger UI / Redoc / Scalar / Stoplight Elements — all actively maintained as of 2026 [E2]. +- openapi-generator (https://openapi-generator.tech/), orval (https://orval.dev/), oapi-codegen (https://github.com/oapi-codegen/oapi-codegen) [E2 — production-deployed]. +- Evidence grade [E2] — pattern is the Stripe / GitHub / Twilio / Shopify default. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-rest-conventions.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-rest-conventions.md new file mode 100644 index 0000000..73f31ac --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-rest-conventions.md @@ -0,0 +1,28 @@ +# API — REST Conventions (verbs, status codes, resources, idempotency, ETag) + +HTTP-level contract for resource-oriented APIs. Pairs with `api-openapi-first.md` (spec as SSoT), `api-versioning-pagination-ratelimit.md` (list + version policy), and `auth-oauth2-oidc.md` / `auth-sessions.md` (principal + scopes). + +## When to include + +- Public or partner JSON-over-HTTP API where clients are heterogeneous (mobile, SPA, third-party integrations, curl). +- Internal service boundary that you want reviewable by humans without generated tooling. +- Any API that must degrade gracefully through an HTTP cache / proxy / API gateway. + +## What it declares + +- **Resource naming:** plural nouns, lowercase, kebab-case (`/invoices`, `/invoice-items/{id}`), no verbs in path. Nested resources ≤2 levels deep (`/invoices/{id}/items`); beyond that flatten with query filters. One canonical URL per resource — never two paths for the same entity. +- **Verbs (RFC 9110):** `GET` safe + idempotent, `HEAD` metadata only, `PUT` full replace + idempotent, `PATCH` partial (JSON Merge Patch RFC 7396 OR JSON Patch RFC 6902, pick one per API), `POST` create / non-idempotent action, `DELETE` idempotent. Non-CRUD actions → `POST /resource/{id}:action` (Google AIP-136) or a child resource — never `GET /do-thing`. +- **Status codes — pick from this set, no creativity:** `200 OK`, `201 Created` (+ `Location` header), `202 Accepted` (async), `204 No Content`, `301/308` (moved), `400 Bad Request` (validation), `401 Unauthorized` (no/invalid credential), `403 Forbidden` (authenticated but not allowed), `404 Not Found`, `409 Conflict` (optimistic-lock / duplicate), `410 Gone`, `412 Precondition Failed` (If-Match mismatch), `415 Unsupported Media Type`, `422 Unprocessable Entity` (semantic validation), `429 Too Many Requests`, `500 Internal Server Error`, `502/503/504` (upstream). `418` is a joke, not a status. +- **Error body: RFC 9457 Problem Details** — `{ "type": "https://api.example.com/errors/invoice-not-found", "title": "...", "status": 404, "detail": "...", "instance": "/invoices/42", "errors": [{"field":"amount","code":"negative"}] }`. Content-Type `application/problem+json`. Stable `type` URI = machine key; `title` = human; `detail` = this instance. +- **Idempotency-Key header (Stripe / IETF draft-ietf-httpapi-idempotency-key-header):** required on `POST` that creates/charges. Server stores `(key, route, response)` for ≥24 h and replays on retry. Different body with same key → `422`. Missing key on mutating `POST` → `400` for strict APIs, accept + warn for lenient. +- **Conditional requests (RFC 9110 §13):** `ETag` on every resource representation (strong `"abc123"` unless you truly serve byte-equivalent variants). Clients send `If-Match: "abc123"` on `PUT` / `PATCH` / `DELETE` — server replies `412` on mismatch. `If-None-Match` + `304 Not Modified` on `GET` for cache revalidation. `Last-Modified` as a weaker fallback only. +- **Content negotiation:** `Accept`, `Accept-Language`, `Accept-Encoding` honoured. Default `application/json; charset=utf-8`. Version media types (`application/vnd.example.v2+json`) ONLY if you commit to header-based versioning — see `api-versioning-pagination-ratelimit.md`. +- **HATEOAS / hypermedia:** OPTIONAL. Include a `_links` / `links` object per resource when the API is explicitly browsable (HAL, JSON:API, Siren) — it's not required for typed SDKs. Document the choice in `openapi.yaml` and stay consistent. +- **Safe-by-default surface:** `GET` never mutates. `DELETE` is idempotent — repeated calls return `204` even if the row is already gone. `PUT` requires the FULL representation; partial field on `PUT` = `400`. + +## References + +- RFC 9110 (HTTP Semantics), RFC 9111 (HTTP Caching), RFC 9457 (Problem Details, 2023), RFC 7396 / 6902 (Merge Patch / JSON Patch), RFC 5988 + 8288 (Web Linking) [E1 — IETF standards-track]. +- Google AIP (https://google.aip.dev/) and Microsoft REST API Guidelines (https://github.com/microsoft/api-guidelines) — production-grade conventions [E2]. +- `api-openapi-first.md` — encode this block as the machine-readable SSoT; `api-versioning-pagination-ratelimit.md` — list, cursor, and version policy. +- Evidence grade [E2] — every rule here is deployed across Stripe, GitHub, Google, Microsoft production APIs. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-versioning-pagination-ratelimit.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-versioning-pagination-ratelimit.md new file mode 100644 index 0000000..bd0717f --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/api-versioning-pagination-ratelimit.md @@ -0,0 +1,53 @@ +# API — Versioning, Pagination, Rate Limiting + +Three cross-cutting concerns that every production API hits within the first month. Pairs with `api-rest-conventions.md` (HTTP semantics), `api-openapi-first.md` (where the policy is encoded), and `api-graphql.md` (Relay cursors + cost-based limits). + +## When to include + +- Any API expected to outlive one client release — versioning decided BEFORE launch, not during the first breaking change. +- Any endpoint returning a collection — pagination decided BEFORE the dataset grows past 10k rows. +- Any API on the public internet or behind a partner quota — rate limits decided BEFORE the first abusive client. + +## What it declares + +### Versioning — pick one strategy, document it + +| Strategy | Example | Pros | Cons | Use when | +|---|---|---|---|---| +| **URL path** | `/v1/invoices` → `/v2/invoices` | Most visible, curl-friendly, easy CDN routing | Pollutes every path; "v2" is vague | Public API, coarse versions, infrequent bumps. GitHub v3/v4, Stripe-compatible mirrors. | +| **Header (media type)** | `Accept: application/vnd.example.v2+json` | Clean URLs, content negotiation native | Invisible in logs/curl; needs client support | Internal APIs with typed SDKs, GitHub v4 hybrid. | +| **Date-based** | `Stripe-Version: 2025-11-01` | Fine-grained, every breaking change pinnable | Complex rollout matrix; server must keep N-1 versions live | Pay-for-stability APIs (Stripe, Shopify); regulated domains. | +| **GraphQL evolution** | Never break the schema; mark fields `@deprecated(reason: "use X")` and remove after telemetry shows 0 usage | No versions to maintain | Schema grows forever; deprecation discipline required | Any GraphQL API — see `api-graphql.md`. | +| **No versioning (additive-only)** | Promise: additions never break clients; removals need a new endpoint | Simplest | Only works with disciplined teams + strong typing | Small internal APIs with ≤3 consumers. | + +Rules that apply to ALL strategies: (a) deprecate with `Deprecation` + `Sunset` headers (RFC 8594, RFC 9745) + 6-month minimum runway, (b) publish a changelog, (c) run the old + new in parallel until telemetry shows the old is unused. + +### Pagination — three patterns, one rule + +- **Offset / page (LIMIT N OFFSET M):** `?page=3&limit=50`. OK for admin UIs over small tables. BROKEN for real data — rows drift during paging, `OFFSET 10000` scans 10k rows on every call. Returns `X-Total-Count` or a `meta.total` field; clients assume random access. +- **Cursor (opaque token, keyset/seek):** `?cursor=eyJpZCI6MTIzfQ&limit=50`. Cursor = base64 of `(id, created_at, …)` — opaque to client, ordered by the server's index. Handles drift, O(log n) lookups. Response envelope: `{ data: [...], meta: { next_cursor, prev_cursor, has_more } }`. REQUIRED for any list that can exceed 1k rows or where concurrent writes happen. +- **Relay (GraphQL spec):** `first: 50, after: "cursor"` + `Connection { edges, pageInfo { endCursor, hasNextPage } }`. Standardised cursor pattern for GraphQL — see `api-graphql.md`. + +Rule: **default cursor, offer offset only when the UI genuinely needs page numbers**. Never return >1000 items per page; clamp `limit` server-side. + +### Rate limiting — headers + strategy + +- **Token bucket or sliding-window**, per authenticated principal (user / API key / IP). Redis-backed, atomic via Lua. Policy tiers: anon < authenticated < partner < internal. +- **Response headers — IETF `RateLimit` (draft-ietf-httpapi-ratelimit-headers, shipped in Cloudflare / GitHub as of 2024):** + - `RateLimit-Limit: 1000` — quota in the current window. + - `RateLimit-Remaining: 947` — left in the current window. + - `RateLimit-Reset: 47` — seconds until reset. + - Also accept legacy `X-RateLimit-*` for GitHub/Stripe parity during migration. +- **On block: `429 Too Many Requests` + `Retry-After: `** (RFC 9110 §10.2.3) + Problem+json body describing the limit that was hit. Always include `Retry-After`; idempotent clients retry cleanly. +- **Cost-based for GraphQL:** each field has a cost (e.g. `user: 1, user.posts: 5 per item, search: 50`); query total checked against per-principal budget. See `api-graphql.md`. +- **Fail-open on metering outage** is a bug, not a feature — fail-closed with a clear error code (`RATE_LIMITER_UNAVAILABLE`) so clients can alert. Silent "no limit" costs more than a short outage. +- **Defence-in-depth:** per-IP (anti-bot), per-principal (anti-abuse), per-endpoint (protect expensive routes), global (protect the cluster). Document all four layers in the repo — hidden layers surprise on-call. + +## References + +- RFC 8594 (Sunset header), RFC 9745 (Deprecation header, 2024), RFC 9110 §10.2.3 (`Retry-After`) [E1 — IETF]. +- draft-ietf-httpapi-ratelimit-headers (https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) [E1 — active working group draft, deployed by Cloudflare + GitHub]. +- Relay Cursor Connections (https://relay.dev/graphql/connections.htm) [E1]. +- Stripe API versioning post (https://stripe.com/blog/api-versioning) [E2 — production-documented 2017 onward]. +- GitHub v3 → v4 migration notes, Shopify API versioning [E2]. +- Evidence grade [E2] — all three policies are production-deployed at Stripe, GitHub, Shopify, Cloudflare. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/auth-authorization.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/auth-authorization.md new file mode 100644 index 0000000..0b515f3 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/auth-authorization.md @@ -0,0 +1,27 @@ +# AUTH — Authorization (RBAC / ABAC / ReBAC) + +Who is allowed to do what, AFTER authentication (`auth-sessions.md`) has identified the principal. Decides on every request; fail-closed. + +## When to include + +- App has more than one user role OR owner-vs-member resource semantics. +- App exposes admin endpoints, multi-tenant data, or per-resource sharing. +- Regulated domain (health / finance / legal) where permission decisions must be logged and auditable. + +## What it declares + +- **RBAC (Role-Based)** — static roles (`admin`, `editor`, `viewer`) mapped to permission sets (`posts:write`, `posts:read`, `billing:read`). Simple, O(1) check, enough for most small apps. Roles live in DB; assignment is an admin action, not a code change. +- **ABAC (Attribute-Based)** — decision = f(subject attrs, resource attrs, action, context). Example: "user can edit doc IF `doc.owner_id == user.id` OR `user.role == admin AND doc.tenant_id == user.tenant_id`". Use when RBAC explodes into per-resource special cases. +- **ReBAC (Relationship-Based, Google Zanzibar style)** — graph of `(subject, relation, object)` tuples; check = "does path `user:A` → ... → `doc:X#editor` exist?". Use for hierarchical sharing (folders, orgs, teams). Implementations: SpiceDB, OpenFGA. +- **Permission matrix — always DECLARED, never implicit:** a table `roles × resource_types × actions` in the repo (`docs/permissions.md` or a DB seed). Every new endpoint picks a cell from the matrix. No ad-hoc `if user.is_admin` scattered through handlers. +- **Enforcement point: middleware, not handlers.** Decision computed once per request against a typed `Permission` enum. Handler receives `AuthorizedRequest` or 403s before it runs. Prevents "forgot the check on the new endpoint" — the dominant authz bug. +- **Fail-closed:** missing role, unknown action, or policy engine error → DENY. Log the denial with subject + action + resource. Never default-allow on error. +- **Policy engines — use when authz logic grows > ~20 rules:** Cerbos (YAML rules, decision-as-a-service, stateless), OPA / Rego (general-purpose, steeper curve), Oso Cloud, SpiceDB (ReBAC). Keep policy files in the repo; treat them as code (tested, reviewed, versioned). +- **Ownership checks scope every query:** `SELECT ... WHERE tenant_id = $1 AND owner_id = $2` — enforced in the data layer, not just the middleware. Double layer defeats IDOR (Insecure Direct Object Reference). +- **Admin + audit:** every permission change, role assignment, and deny-event written to an append-only audit log (`tenant_id`, `actor_id`, `action`, `target`, `timestamp`, `result`). Required for SOC2 / ISO 27001 / HIPAA. + +## References + +- NIST SP 800-162 (ABAC), Google Zanzibar paper (2019), Cerbos docs, OPA/Rego docs [E1]. +- `auth-sessions.md` — source of the authenticated principal; this block decides what that principal can do. +- Evidence grade [E2] — RBAC/ABAC widely deployed; ReBAC via Zanzibar-clones production since ~2022. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/auth-oauth2-oidc.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/auth-oauth2-oidc.md new file mode 100644 index 0000000..e89c017 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/auth-oauth2-oidc.md @@ -0,0 +1,26 @@ +# AUTH — OAuth2 + OIDC (Authorization Code + PKCE) + +Identity delegation to external providers (Google / GitHub / Apple / Microsoft / any OIDC-compliant IdP). For first-party login see `auth-passkeys.md` / `auth-sessions.md`; for post-login permissions see `auth-authorization.md`. + +## When to include + +- App supports "Sign in with Google / GitHub / Apple / Microsoft" or federates to an enterprise OIDC IdP (Okta, Auth0, Keycloak, Entra ID). +- App needs a short-lived API access token for the user (Gmail, Calendar, GitHub API). +- Regulated context where the IdP — not the app — is the system of record for identity. + +## What it declares + +- **Flow: Authorization Code + PKCE for EVERY client** (public SPA, mobile, confidential server). PKCE is mandatory in OAuth 2.1 and removes the implicit flow entirely. +- **PKCE params:** `code_verifier` 43–128 chars random, `code_challenge = BASE64URL(SHA256(verifier))`, `code_challenge_method=S256`. Never `plain`. +- **State + nonce:** `state` (CSRF, 32+ bytes random, bound to session) on every auth request; `nonce` (replay, in ID token claim) for OIDC. Reject response if either mismatches. +- **Redirect URIs:** exact-match, pre-registered at the IdP. No wildcards. `localhost` and custom schemes OK for native; HTTPS required for web. +- **Providers: Google** (`accounts.google.com/.well-known/openid-configuration`), **GitHub** (OAuth2 only, no OIDC discovery — hard-code `https://github.com/login/oauth/authorize`, `token`, `https://api.github.com/user`), **Apple** (OIDC, but only returns user name/email on FIRST consent — persist on first login or lose it), **Microsoft** (`login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration`). +- **Token handling:** `access_token` short-lived (≤1 h), kept server-side only. `refresh_token` rotated on every use (RFC 6749 §6 + OAuth 2.1), stored encrypted at rest, NEVER sent to the browser. `id_token` validated (JWKS signature + `iss` + `aud` + `exp` + `nonce`) and discarded — do NOT re-use as a session token. +- **Secrets:** `CLIENT_ID` + `CLIENT_SECRET` per provider in `secrets/*.env`; referenced by env var name only. Public clients (SPA/mobile) use PKCE WITHOUT a secret. +- **Libraries:** prefer Better-Auth (TS), NextAuth/Auth.js (Next.js), authlib (Python), openidconnect-rs or oauth2-rs (Rust). Avoid rolling your own — every major CVE in this space is custom code. + +## References + +- RFC 6749 (OAuth 2.0), RFC 7636 (PKCE), RFC 9700 (OAuth 2.0 Security BCP, 2024), OAuth 2.1 draft, OpenID Connect Core 1.0 [E1 — standards-track RFCs]. +- `auth-sessions.md` for what to do AFTER the IdP handshake returns. +- Evidence grade [E2] — implementation widely deployed, spec stable since 2024. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/auth-passkeys.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/auth-passkeys.md new file mode 100644 index 0000000..9b62688 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/auth-passkeys.md @@ -0,0 +1,27 @@ +# AUTH — Passkeys (WebAuthn / FIDO2) + +Phishing-resistant, passwordless authentication via public-key credentials bound to the Relying Party. For federated login see `auth-oauth2-oidc.md`; for session issuance after passkey assertion see `auth-sessions.md`. + +## When to include + +- Greenfield auth: passkeys as PRIMARY login (password-optional or password-less). +- Existing password login: passkeys as stronger step-up or second factor that also replaces the password. +- Any consumer product — Apple, Google, Microsoft all ship platform authenticators (Touch ID / Face ID / Windows Hello) and sync passkeys across devices via iCloud Keychain / Google Password Manager / Microsoft Authenticator as of 2024–2026. + +## What it declares + +- **Two ceremonies:** + - **Registration** — server sends `PublicKeyCredentialCreationOptions` (random `challenge`, `rp.id`, `rp.name`, `user.id` opaque, `pubKeyCredParams` prefer ES256=-7 and RS256=-257, `authenticatorSelection`, `attestation: "none"` unless regulated). Client returns `attestationObject` + `clientDataJSON`. Server verifies and stores `credentialID`, `publicKey`, `signCount`, `transports`, `backupEligible`, `backupState`. + - **Assertion (login)** — server sends `PublicKeyCredentialRequestOptions` (fresh random `challenge`, `rpId`, `allowCredentials` list or empty for discoverable). Client returns `signature` + `authenticatorData` + `clientDataJSON`. Server verifies signature with stored `publicKey`, checks `signCount` strictly > stored, origin, `rpId` hash. +- **RP ID** = eTLD+1 or a subdomain of it (`example.com` covers `app.example.com`; a passkey for `app.example.com` does NOT work on `example.com`). Pick RP ID carefully at launch — changing it invalidates every existing credential. +- **Resident / discoverable credentials** (`residentKey: "required"` + `userVerification: "required"`) enable username-less login ("Sign in" button with no email field). Requires passkey-capable authenticator. +- **Platform vs cross-platform:** `authenticatorAttachment: "platform"` = Touch ID / Face ID / Windows Hello (synced, convenient). `"cross-platform"` = roaming security keys (YubiKey, Titan). Leave unset to accept both. +- **Challenge**: 16+ random bytes per ceremony, single-use, time-boxed (≤5 min), bound to server session, rejected on replay. +- **Libraries:** SimpleWebAuthn (TS — reference implementation, covers both server + browser), webauthn-rs (Rust, `Webauthn` builder + `passkey` feature), fido2-rs (low-level), py_webauthn (Python). NEVER roll CBOR / COSE parsing by hand. +- **Recovery path REQUIRED** before enabling passkey-only — lose device, lose account. Ship at least one of: email magic-link fallback, passkey backup codes, OAuth federation as recovery. User opts out of recovery only after explicit warning. + +## References + +- W3C WebAuthn Level 3 (2024-ready), FIDO2 CTAP 2.1, passkeys.dev [E1 — W3C/FIDO specs]. +- `auth-sessions.md` for cookie issuance after `verifyAuthenticationResponse` succeeds. +- Evidence grade [E2] — Apple/Google/Microsoft production since 2023–2024; SimpleWebAuthn 10.x stable. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/auth-sessions.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/auth-sessions.md new file mode 100644 index 0000000..3d9d011 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/auth-sessions.md @@ -0,0 +1,29 @@ +# AUTH — Sessions & Cookies (+JWT tradeoff) + +What happens AFTER identity is proven (password / OAuth / passkey / magic-link). Issues a session, enforces it on every request, and kills it on logout. Upstream of `auth-authorization.md`. + +## When to include + +- Any web or mobile app that needs an authenticated request state beyond a single round-trip. +- Any app that exposes logout, session revocation, or step-up auth. +- API-only backend (mobile/SPA): choose cookie-based session OR short-lived JWT — decision recorded per project. + +## What it declares + +- **Default: server-side opaque sessions** stored in Postgres / Redis / SQLite, keyed by a 256-bit random `session_id`. Row columns: `id`, `user_id`, `created_at`, `last_seen_at`, `expires_at`, `ip`, `user_agent`, `revoked_at`. Session data NEVER encoded in the cookie itself. +- **Cookie flags — all mandatory:** `HttpOnly` (blocks JS read → XSS-resistant), `Secure` (HTTPS only), `SameSite=Lax` for top-level nav auth / `Strict` for cross-site-hostile apps, `Path=/`, `__Host-` prefix for session cookie (forbids `Domain`, requires `Secure` + `Path=/`). Max-Age tuned to app: 7–30 days sliding, 24 h hard for regulated. +- **Session rotation:** issue a NEW `session_id` on login, logout-everywhere, password/passkey change, privilege elevation. Old row deleted or `revoked_at` set. Rotation defeats session fixation. +- **Logout:** delete the server row AND clear the cookie (`Max-Age=0`, same flags). Logout-everywhere = delete all rows for `user_id`. Client-only logout (cookie clear, server row kept) is a bug, not a feature. +- **CSRF:** `SameSite=Lax` covers most flows. For cross-origin POSTs keep a double-submit CSRF token (cookie + header/form field, server compares). API-only backend with Bearer token → no CSRF (no ambient credential). +- **JWT alternative — use ONLY when stateless horizontal scale matters more than revocation:** + - `access_token` ≤15 min, signed ES256 (NOT HS256 with shared secret across services), `iat`/`exp`/`aud`/`iss`/`sub` all validated, `kid` header + JWKS rotation. + - `refresh_token` opaque (NOT a JWT), stored server-side, rotated on every use (detect reuse → revoke family). + - Logout revokes refresh token ONLY; access token is trusted until `exp`. If you need instant revoke → use server sessions instead. + - Never store JWT in `localStorage` — use `HttpOnly` cookie or native secure storage. `localStorage` + XSS = total account takeover. +- **Libraries:** axum-login + tower-sessions (Rust), express-session / Better-Auth (Node), iron-session (edge), starlette SessionMiddleware + authlib (Python), SvelteKit `event.cookies`. JWT: jose (TS), jsonwebtoken (Rust), PyJWT. + +## References + +- OWASP Session Management Cheat Sheet, RFC 6265bis (cookies), RFC 7519 (JWT), RFC 8725 (JWT BCP) [E1]. +- `auth-oauth2-oidc.md` / `auth-passkeys.md` — upstream identity proof; `auth-authorization.md` — downstream permission check. +- Evidence grade [E2] — session-cookie pattern stable since 2000s; JWT revocation gap is a well-known tradeoff. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/baseline.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/baseline.md new file mode 100644 index 0000000..98cccb7 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/baseline.md @@ -0,0 +1,20 @@ +# BASELINE — inherit from Main Claude (never violate) + +You inherit from `~/.claude/CLAUDE.md`. Re-read it on ambiguity. Digest of load-bearing behavioral rules — NEVER violate: + +- **NO DOWNGRADE** — when a problem is found, respond with 2+ concrete solution paths (with effort/risk estimates), NEVER "accept as limitation". Defeatism = epistemic cowardice. +- **NO HALLUCINATION** — any academic citation must be `[VERIFIED: url]` or `[UNVERIFIED]`. No fabricated authors/years/DOIs/numbers. Confidence mandatory: `[100% proven]` / `[80% likely]` / `[30% speculative]` / `[0% don't know]`. +- **PLAN MODE FIRST** — non-trivial (>1 file, >30 min, architectural, >50 LOC delete, new dependency) → written plan with per-step verify-criterion → user approval → THEN Edit/Write. +- **Constructor Pattern** — 1 file = 1 class = 1 responsibility. File >200 LOC → split. Function >30 LOC → split. No mixins, factories, DI containers. +- **Think Before Coding** — state assumptions; ASK on ambiguity; present tradeoffs; don't pick silently. +- **Surgical Changes** — every changed line must trace to the user's request. Don't "improve" adjacent code. Remove orphans YOUR changes created. +- **Goal-Driven** — convert every task to a verify-criterion before starting. "Fix bug" → "write a test that reproduces it, then pass". + +Core discipline rules: + +1. **No Patching / No Overlays** — fixes go INTO ROOT FORMULAS. File doubled from "fixes" = overlay. +2. **Root Cause** — always find the root, not the symptom. +3. **Don't Rewrite Working Code** — no rewrite without a reason. +4. **Full Observability** — log parameters; no data → no decisions. +5. **Single Source of Truth** — types, routes, enums in ONE place. +6. **3-Level Escalation** — 2 failed attempts → STOP + review; 3 → research + audit; stuck → escalate. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/ci-forgejo-actions.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/ci-forgejo-actions.md new file mode 100644 index 0000000..8b01504 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/ci-forgejo-actions.md @@ -0,0 +1,61 @@ +# CI — Forgejo Actions (self-hosted, Tailscale-only admin) + +Forgejo Actions is GitHub-Actions compatible at the workflow-syntax layer (derived from Gitea Actions, which re-uses the `actions/*` runtime via `act`). A workflow that runs on GH usually runs on Forgejo with only the runner labels and registry URLs changed. Pair with RULE 0.1 — KeiGit repos MUST stay on private Forgejo, never mirror to github.com. + +## Layout + +Workflows live under `.forgejo/workflows/*.yml` (primary) — `.gitea/workflows/` also works for legacy repos. Keep the same narrow split as GH: + +- `ci.yml` — build + test +- `release.yml` — tag-driven +- `security.yml` — scheduled scanners + +## Self-hosted runner + +Forgejo has no SaaS runner fleet — you provide the compute. Install `forgejo-runner` [VERIFIED: https://code.forgejo.org/forgejo/runner] on a node that is reachable ONLY over Tailscale. + +Registration: + +```bash +forgejo-runner register \ + --no-interactive \ + --instance http://100.91.246.53:3000 \ + --name kgl-runner-01 \ + --labels "self-hosted,linux,x64,docker" \ + --token "$FORGEJO_RUNNER_TOKEN" # from secrets/runner.env (RULE 0.8) +``` + +`FORGEJO_RUNNER_TOKEN` stays in `secrets/runner.env` — reference via env name only, never paste the literal value. + +Target in workflow: + +```yaml +jobs: + build: + runs-on: [self-hosted, linux, x64] +``` + +## GitHub-compat surface + +Works out of the box: `actions/checkout@v4`, `actions/cache@v4`, `actions/setup-node@v4`, `Swatinem/rust-cache@v2`, shell/docker steps, matrix, reusable workflows (`uses: ///.forgejo/workflows/@`). + +Does NOT work: `permissions:` block (Forgejo token is scoped at the runner level, not per-job), OIDC federation to AWS/GCP (no JWKS endpoint served by Forgejo), GitHub-Marketplace actions that call `api.github.com` directly. + +Workaround for OIDC: for cloud deploys from Forgejo, prefer short-lived STS tokens minted by a bastion that has an IAM role, passed into the runner via a sealed env file rotated daily. + +## Tailscale-only admin posture + +Forgejo Web UI is http://100.91.246.53:3000, SSH is `ssh://git@100.91.246.53:2222/...`. Both on Tailscale CGNAT. NEVER bind Forgejo to a public IP — runner tokens, PATs, and repo contents are unfiled patent IP (RULE 0.1). + +Key fingerprint for the existing KeiGit host: `SHA256:TxHcs7YuEZiy4Gu0yZOoVidVqlvj8TPC+QgUGjmh0Mw` labelled `macbook`. + +## Secrets + +Forgejo repo secrets (`Repo → Settings → Actions → Secrets`) mirror GH secrets syntactically: `${{ secrets.FOO }}`. Organisation-scope secrets also supported. Every secret still references the canonical `~/.claude/secrets/.env` / `secrets/*.env` source — repo secrets are cache copies, rotated when the source rotates. + +## Forbidden + +- Exposing Forgejo port 3000 or 2222 on a public IP +- Running `forgejo-runner` on a host that is also a production application node +- Mirroring a KeiGit repo to github.com to "get free CI" (RULE 0.1) +- Hard-coded runner tokens in workflow YAML (always `${{ secrets.* }}`) diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/ci-github-actions.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/ci-github-actions.md new file mode 100644 index 0000000..c21b663 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/ci-github-actions.md @@ -0,0 +1,95 @@ +# CI — GitHub Actions (OIDC, matrix, cache, reusable workflows) + +Pipeline platform for code hosted on (or mirrored to) github.com. This block ships the defaults; pair with `ci-security-gate.md` for scanners and `ci-release-automation.md` for tags. + +## Workflow layout + +Keep workflow files narrow: ONE responsibility each under `.github/workflows/`. + +- `ci.yml` — build + test on every push/PR +- `release.yml` — tag-driven release automation (see `ci-release-automation.md`) +- `security.yml` — scheduled scanners (see `ci-security-gate.md`) +- `deploy-*.yml` — per-environment deploys, each behind a GitHub Environment with required reviewers + +## OIDC — cloud deploy WITHOUT long-lived keys + +GitHub Actions mints a short-lived JWT per run; the cloud provider trusts `token.actions.githubusercontent.com` and issues temporary credentials. **Never** store `AWS_SECRET_ACCESS_KEY` / `GCP_SA_KEY` in repo secrets. + +```yaml +permissions: + id-token: write # mandatory for OIDC + contents: read +jobs: + deploy: + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v4 # [VERIFIED: https://github.com/actions/checkout] + - uses: aws-actions/configure-aws-credentials@v4 # [VERIFIED: https://github.com/aws-actions/configure-aws-credentials] + with: + role-to-assume: arn:aws:iam::${{ vars.AWS_ACCOUNT_ID }}:role/gha-deployer + aws-region: eu-north-1 +``` + +Cloud-side role trust policy pins `repo:/:ref:refs/heads/main` — wildcards invite cross-repo impersonation. + +## Least-privilege GITHUB_TOKEN + +Default token permissions at the workflow level, then widen per-job: + +```yaml +permissions: + contents: read # read-only at top level +jobs: + build: + # inherits read-only + release: + permissions: + contents: write # only the release job gets write + id-token: write +``` + +Org-level default should be `read` (Settings → Actions → Workflow permissions). Any job requiring write must opt in explicitly. + +## Matrix builds + +Fan out across OS × language version × target; `fail-fast: false` prevents one red cell from cancelling the whole matrix. + +```yaml +strategy: + fail-fast: false + matrix: + os: [ubuntu-24.04, macos-14] + rust: [stable, 1.80] # MSRV pin +``` + +## Cache hygiene + +- Lock-file as key, never branch name: `key: cargo-${{ hashFiles('**/Cargo.lock') }}`. +- `restore-keys` is a PREFIX fallback — safe for cold PRs. +- `actions/cache@v4` [VERIFIED: https://github.com/actions/cache] for generic; language-specific actions (`actions/setup-node@v4`, `Swatinem/rust-cache@v2`) manage cache internally — don't double-cache. +- Cache POISONING check: never cache directories that contain your built artefacts alongside downloaded deps. + +## Reusable workflows + +Shared logic lives in one repo and is called by `uses: //.github/workflows/.yml@`. Pin by SHA, not tag — tags are mutable. `workflow_call` contract: + +```yaml +on: + workflow_call: + inputs: + rust-version: { required: true, type: string } + secrets: + CARGO_TOKEN: { required: false } +``` + +## Pinning third-party actions + +Pin by full commit SHA, not tag: `uses: foo/bar@3a4b5c6d7e8f9012...` with a comment `# v2.1.0`. Dependabot updates SHAs the same way — supply-chain hijack via tag-overwrite is a documented class (e.g. `tj-actions/changed-files` 2025). [E2] + +## Forbidden + +- `secrets.AWS_SECRET_ACCESS_KEY` in any workflow (use OIDC) +- `permissions: write-all` at workflow level +- Third-party action pinned by tag +- `pull_request_target` with `checkout` of PR head + secrets access (classic pwn-request) +- Caching `target/` or `node_modules/` alongside `.git` or user config diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/ci-release-automation.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/ci-release-automation.md new file mode 100644 index 0000000..1ffdc4e --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/ci-release-automation.md @@ -0,0 +1,80 @@ +# CI — Release automation (SemVer, changelog, tagging) + +Automates "merge to main → versioned release" so the next step (build artefact, publish, deploy) has a predictable trigger. Picks ONE tool per repo — mixing release-please with cargo-release creates duplicate tags. Pair with `ci-github-actions.md` / `ci-forgejo-actions.md` for the workflow shell. + +## Tool picks per ecosystem + +| Stack | Tool | Trigger | Changelog source | +|---|---|---|---| +| Monorepo / polyglot / apps | release-please [VERIFIED: https://github.com/googleapis/release-please] | merge to main | Conventional Commits | +| JS/TS packages (npm publish) | changesets [VERIFIED: https://github.com/changesets/changesets] | merge of `.changeset/*.md` | Explicit changeset files | +| Rust crates (crates.io) | cargo-release [VERIFIED: https://github.com/crate-ci/cargo-release] | manual `cargo release` | git log + Conventional Commits | +| Go modules | goreleaser [VERIFIED: https://github.com/goreleaser/goreleaser] | tag push | git log + `.goreleaser.yaml` | + +## SemVer contract + +- `MAJOR` — breaking change to public API, wire format, on-disk schema, config file keys +- `MINOR` — additive feature, no breakage, new optional fields +- `PATCH` — bug fix, performance, docs, dep bump without API change + +Conventional Commits mapping: `feat!:` / `BREAKING CHANGE:` → MAJOR; `feat:` → MINOR; `fix:` / `perf:` / `refactor:` → PATCH; `checkpoint:` / `audit:` / `chore:` → no-bump (ignored by release-please). + +## release-please minimal config + +`.github/workflows/release.yml` (or `.forgejo/workflows/release.yml`): + +```yaml +on: + push: + branches: [main] +permissions: + contents: write # create tags + releases + pull-requests: write # update the Release-PR +jobs: + release-please: + runs-on: ubuntu-24.04 + steps: + - uses: googleapis/release-please-action@v4 # [VERIFIED: https://github.com/googleapis/release-please-action] + with: + release-type: rust # or node, python, go, simple, etc. + token: ${{ secrets.GITHUB_TOKEN }} +``` + +release-please opens a long-lived "Release PR" that updates `CHANGELOG.md` + version file on every main merge; merging that PR creates the tag and GitHub Release. No human writes the changelog. + +## changesets minimal config (JS/TS monorepo) + +```yaml +- uses: changesets/action@v1 # [VERIFIED: https://github.com/changesets/action] + with: + publish: pnpm release # runs `changeset publish` + env: + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} +``` + +Each PR that changes a package ships a `.changeset/.md` describing the bump. CI blocks merge without one (`changeset status --since=origin/main`). + +## cargo-release minimal config (Rust crates.io) + +`release.toml` at repo root: + +```toml +sign-tag = true +push = true +tag-message = "{{crate_name}} {{version}}" +pre-release-commit-message = "release: {{version}}" +``` + +Publish workflow runs on tag push: `cargo publish --token "$CARGO_REGISTRY_TOKEN"` where the token is minted just-in-time from the `ci-security-gate.md` trusted-publishing flow. + +## Lock-file discipline + +`Cargo.lock` / `package-lock.json` / `pnpm-lock.yaml` / `pubspec.lock` / `go.sum` — ALWAYS committed (RULE git-conventions). Release workflows must FAIL if the lock file is stale: `cargo update --locked --dry-run`, `pnpm install --frozen-lockfile`, `go mod verify`. + +## Forbidden + +- Manual `git tag vX.Y.Z && git push --tags` when a release tool is configured (drift between CHANGELOG and tag) +- Two release tools in the same repo (release-please + cargo-release both tagging) +- Publishing from a `pull_request` trigger (never — only from `push` to main or `workflow_dispatch`) +- Forcing a tag with `git push --force origin refs/tags/*` — breaks every consumer that pinned by SHA +- Stale lock files passing CI (must be a hard fail, not a warning) diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/ci-security-gate.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/ci-security-gate.md new file mode 100644 index 0000000..9680854 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/ci-security-gate.md @@ -0,0 +1,82 @@ +# CI — Security gate (secrets, SCA, SBOM, semgrep, licenses) + +Every PR passes through this gate before merge. Every scheduled run re-scans `main`. Pair with `ci-github-actions.md` / `ci-forgejo-actions.md` (the shell) and RULE 0.8 (secrets SSoT) / RULE 0.1 (no-github-push) — the gate enforces both. + +## Scanner set (one job each, matrix is fine) + +| Concern | Tool | Trigger | Fail threshold | +|---|---|---|---| +| Leaked secrets | gitleaks [VERIFIED: https://github.com/gitleaks/gitleaks] | PR + push | any finding | +| Rust SCA | cargo-audit [VERIFIED: https://github.com/rustsec/rustsec] | PR + cron daily | any `Vulnerability` | +| Node SCA | `npm audit` / `pnpm audit` (native) | PR + cron | `high` and above | +| Python SCA | pip-audit [VERIFIED: https://github.com/pypa/pip-audit] | PR + cron | any CVE | +| SBOM generation | syft [VERIFIED: https://github.com/anchore/syft] | release only | CycloneDX JSON as artefact | +| SAST / patterns | semgrep [VERIFIED: https://github.com/semgrep/semgrep] | PR | any `ERROR` severity | +| License policy | cargo-deny [VERIFIED: https://github.com/EmbarkStudios/cargo-deny] (Rust) / license-checker (JS) | PR | disallowed SPDX ID | + +## gitleaks — secrets scan (always first) + +Runs before any build step so that a detected secret aborts the job without ever shipping a binary that used it. + +```yaml +- uses: gitleaks/gitleaks-action@v2 # [VERIFIED: https://github.com/gitleaks/gitleaks-action] + env: + GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }} # orgs only; free for ≤25 users +``` + +Custom rules in `.gitleaks.toml` at repo root — mirror the patterns from `~/.claude/rules/secrets-single-source.md` (sk-, ghp_, sk-ant-, Telegram bot, AWS access key, etc.). Any hit FAILS the run. No "informational" severity for secrets. + +## cargo-audit / pip-audit / npm audit + +Daily cron to catch CVEs published after merge. Fail-fast on HIGH/CRITICAL; report MEDIUM to a tracking issue rather than blocking the PR. + +```yaml +- run: cargo audit --deny warnings --deny unmaintained --deny yanked +``` + +Pin the advisory-DB commit in vendored copies; upstream can get taken down. + +## SBOM via syft + +Generate CycloneDX JSON for every published artefact. Attach to the GitHub Release (see `ci-release-automation.md`) and to the container image as an OCI annotation. + +```yaml +- uses: anchore/sbom-action@v0 # [VERIFIED: https://github.com/anchore/sbom-action] + with: + format: cyclonedx-json + artifact-name: sbom.cdx.json +``` + +SLSA provenance (`slsa-framework/slsa-github-generator`) is an optional upgrade; required when shipping to any customer under a supply-chain contract. + +## semgrep — SAST + +`p/default` + `p/secrets` + `p/owasp-top-ten` + any language pack relevant to the repo. Custom rules under `.semgrep/*.yaml` for project-specific patterns (e.g. "no `unwrap()` in request handlers"). + +```yaml +- uses: semgrep/semgrep-action@v1 # [VERIFIED: https://github.com/semgrep/semgrep-action] + env: + SEMGREP_RULES: p/default p/secrets p/owasp-top-ten +``` + +## License policy + +`cargo-deny` `deny.toml` declares allowed SPDX identifiers (`MIT`, `Apache-2.0`, `BSD-3-Clause`, `ISC`, `Unicode-DFS-2016`). Anything else FAILS the PR. GPL / AGPL / SSPL in a commercial repo = hard stop. For JS, `license-checker --failOn 'GPL;AGPL;SSPL'`. + +## Scheduling + +```yaml +on: + pull_request: + push: { branches: [main] } + schedule: + - cron: "17 3 * * *" # daily 03:17 UTC — off-hour, avoids global burst +``` + +## Forbidden + +- Running the security gate AFTER build/test (secret must block before the secret-using binary exists) +- Allowing "informational" severity on secrets scans (gitleaks = binary; 0 or 1) +- Skipping `cargo-audit` / `pip-audit` on release workflows (a CVE published yesterday ships today without it) +- Uploading SBOM to a public artefact store from a RULE-0.1 repo (internal artefact store only) +- Copy-pasting a secret detected by gitleaks into the chat to "discuss" — rotate at provider FIRST, then discuss diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-drizzle.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-drizzle.md new file mode 100644 index 0000000..daa8d2d --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-drizzle.md @@ -0,0 +1,51 @@ +# DB — Drizzle ORM (TypeScript) patterns + +Use when the project is TypeScript/Next.js/Bun/Node and needs a type-safe SQL layer without Prisma's heavyweight engine process. Pairs with `stack-nextjs`. [E4 — expert assessment] + +**Core versions:** `drizzle-orm` (latest on npm) + `drizzle-kit` (migrations CLI) as of 2026-04. Peer-deps: `pg` for Postgres, `better-sqlite3` / `@libsql/client` for SQLite, `mysql2` for MySQL. [UNVERIFIED: pin exact versions from npm before shipping] + +**Schema-first, not code-first:** +```ts +// db/schema.ts +import { pgTable, serial, text, timestamp, integer } from "drizzle-orm/pg-core"; + +export const users = pgTable("users", { + id: serial("id").primaryKey(), + email: text("email").notNull().unique(), + createdAt: timestamp("created_at").defaultNow().notNull(), +}); + +export const posts = pgTable("posts", { + id: serial("id").primaryKey(), + authorId: integer("author_id").references(() => users.id).notNull(), + body: text("body").notNull(), +}); +``` +`schema.ts` IS the source of truth. All types flow from it — `typeof users.$inferSelect` gives you the row type. + +**Query with full inference:** +```ts +import { eq } from "drizzle-orm"; +const rows = await db.select().from(users).where(eq(users.id, 1)); +// rows: { id: number; email: string; createdAt: Date }[] +``` +No codegen step, no separate `.prisma` file. Type errors surface in the IDE immediately. + +**Migrations via drizzle-kit:** +```bash +drizzle-kit generate # diff schema.ts against prev snapshot → emit SQL in drizzle/ +drizzle-kit migrate # apply pending migrations +drizzle-kit studio # local web UI to inspect data +``` +Config in `drizzle.config.ts` — specify `dialect`, `schema`, `out`, `dbCredentials`. + +**Connection / pool:** +```ts +import { drizzle } from "drizzle-orm/node-postgres"; +import { Pool } from "pg"; +const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 20 }); +export const db = drizzle(pool, { schema }); +``` +Serverless (Vercel / CF Workers): use `neon-serverless` or `@libsql/client` driver instead — the `pg` Pool doesn't survive cold-start boundaries. + +**Forbidden:** template-string SQL with untrusted input (`sql\`SELECT * WHERE x = ${userInput}\`` — use `sql.placeholder` or the query builder); committing `drizzle/meta/_journal.json` conflicts (merge manually or regenerate); mixing drizzle-kit versions across dev machines. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-migration-hygiene.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-migration-hygiene.md new file mode 100644 index 0000000..0532917 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-migration-hygiene.md @@ -0,0 +1,33 @@ +# DB — Migration hygiene (universal) + +Applies to every migration tool — `kei-migrate`, Atlas, goose, sqlx-cli, drizzle-kit, Alembic, Prisma migrate, Ecto migrations. [E4 — expert assessment] + +**Numbering:** timestamp prefix, not integer. `20260421_120000_add_users_email_index.sql` sorts correctly forever and doesn't collide on parallel branches. Integer sequences (`0001_`, `0002_`) collide on merge; reject them in review. + +**Up + down pairs:** every migration has a reverse. If the reverse is destructive and unsafe (e.g. dropping a column with data), write a `-- IRREVERSIBLE` comment and stop the down-script there. NEVER auto-run destructive downs on prod without a human click. + +**Idempotent where possible:** +```sql +CREATE TABLE IF NOT EXISTS users (...); +CREATE INDEX IF NOT EXISTS idx_users_email ON users(email); +ALTER TABLE users ADD COLUMN IF NOT EXISTS bio TEXT; -- PG 9.6+, verify per-DB +``` +Re-running a partially-applied migration should be safe. A migration that crashes mid-way and can't be re-run = 2AM incident waiting to happen. + +**Zero-downtime pattern (add-then-drop):** +1. Deploy migration that ADDS new column / table (old code still works). +2. Deploy app code that writes BOTH old + new. +3. Backfill old → new. +4. Deploy app code that reads new, ignores old. +5. Deploy migration that DROPS old column. + +Never `DROP` + `ADD RENAME` in one migration on a live table. That's a table lock + app-downtime event. + +**Backfill patterns:** +- Small table (< 1M rows): `UPDATE ... SET new = f(old)` in a single migration. +- Large table: background job with batched `UPDATE ... WHERE id BETWEEN ? AND ?` + `LIMIT`. Commit per batch. Monitor lag. +- Very large (> 100M rows): use the DB's native tooling (PG `VACUUM FULL` not needed; `pg_repack` if column-add bloats). [UNVERIFIED: verify on current PG docs] + +**Tracking table (`_kei_migrations` or equivalent):** stores (version, name, checksum, applied_at). Checksum prevents silent tampering with an already-applied file. If checksum mismatches on an applied migration → hard-fail, demand human intervention. + +**Forbidden:** editing a migration file after it's been applied on any environment (checksum break); `DROP TABLE` without backup + 24h cooldown; mixing DDL + large DML in one transaction (long locks); running migrations automatically on app startup in multi-replica deploys without a leader-election guard (every replica tries to apply = race condition). diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-postgres.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-postgres.md new file mode 100644 index 0000000..0997a80 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-postgres.md @@ -0,0 +1,28 @@ +# DB — PostgreSQL (current major — 17 as of 2026-04) patterns + +Use when the project needs relational integrity, concurrent writes, or server-side indexing power that SQLite can't match. Default RDBMS for new multi-user services. [E4 — expert assessment] + +**Version choice:** PostgreSQL 17 for new projects (current GA line, improved vacuum, JSON_TABLE, better parallel index builds). PostgreSQL 16 acceptable if hosting provider pins it. [UNVERIFIED: exact feature matrix — verify on postgresql.org/docs before committing to a minor-version-specific feature] + +**Schema migrations:** every schema change ships as a numbered `.sql` file, never `ALTER TABLE` on prod. Use `kei-migrate` (this kit) or Atlas/goose/sqlx-cli — see `db-migration-hygiene.md`. One migration per logical change; no mega-migrations. + +**Indexing:** +- B-tree default for equality + range. `CREATE INDEX CONCURRENTLY` on prod to avoid table lock. +- `GIN` for `jsonb` / array / full-text (`tsvector`). +- `BRIN` only for massive append-only time-series (orders of magnitude smaller than B-tree). +- Partial indexes (`WHERE active = true`) for sparse predicates. +- **Verify with `EXPLAIN (ANALYZE, BUFFERS)`** before declaring an index necessary. No blind indexing. + +**Connection pooling:** app-side connection pool is NOT enough at scale. Use: +- **PgBouncer** (transaction mode) for most services — battle-tested, low overhead. +- **Supavisor** if already on Supabase — serverless-friendly, wire-compatible. [E4] +- Native server pooling (PG 17's improved but still not a substitute). [UNVERIFIED] + +Sizing rule of thumb: `max_connections` on server × 1 pool layer. Don't stack pools (pool → PgBouncer → PG = deadlock risk). + +**Backup:** +- Logical: `pg_dump` nightly for schema + data portability. +- Physical: `pg_basebackup` + WAL archiving (`archive_command`) for PITR. +- Managed service (RDS / Supabase / Neon) — verify backup retention in their UI, don't assume. + +**Forbidden:** `SELECT *` in hot paths (N+1 + column drift); unindexed FK columns (join explosion); `SERIAL` on new tables — prefer `GENERATED ALWAYS AS IDENTITY` (SQL standard, PG 10+); plaintext passwords in `pg_hba.conf`; committing `.env` with DB URL. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-sqlite.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-sqlite.md new file mode 100644 index 0000000..65399cc --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-sqlite.md @@ -0,0 +1,34 @@ +# DB — SQLite (prod-suitable) patterns + +Use when the workload is read-heavy, single-writer-acceptable, or needs zero-ops embedded storage. SQLite is prod-suitable — Fly.io, Turso, Cloudflare D1, and countless CLI/mobile apps run it in production. [E4 — expert assessment] + +**When NOT to use:** high-concurrency write workload (> ~1 writer/sec sustained), multi-region strong consistency, horizontal write scaling. Use Postgres instead. + +**WAL mode is mandatory for prod:** +```sql +PRAGMA journal_mode = WAL; -- readers don't block writer, writer doesn't block readers +PRAGMA synchronous = NORMAL; -- durable across app crash, NOT across power loss (use FULL if PSU-risk) +PRAGMA busy_timeout = 5000; -- 5s wait for lock instead of instant SQLITE_BUSY +PRAGMA foreign_keys = ON; -- default OFF in SQLite (!), always enable +PRAGMA temp_store = MEMORY; +``` +Apply these on every connection open — they are per-connection, not per-database (except `journal_mode` which persists). + +**Distributed patterns:** +- **Turso** (libSQL fork): edge-replicated read replicas with HTTP/WebSocket wire protocol. Primary single-writer, replicas read-only. [E4] +- **LiteFS** (Fly.io): file-system replication, leader-election via Consul. Primary+replicas. [E4] +- **Cloudflare D1**: managed SQLite on edge with their own replication. [UNVERIFIED: current throughput limits] +- **Litestream**: continuous replication to S3/R2 for backup + PITR; single node, not HA. + +**Full-text search (FTS5):** +```sql +CREATE VIRTUAL TABLE docs_fts USING fts5(title, body, content=docs, content_rowid=id); +CREATE TRIGGER docs_ai AFTER INSERT ON docs BEGIN + INSERT INTO docs_fts(rowid, title, body) VALUES (new.id, new.title, new.body); +END; +``` +FTS5 outperforms bolt-on `LIKE '%x%'` by 100×+ on large text corpora. Native, no extension install. + +**Backup:** `sqlite3 db '.backup /path/backup.db'` while app runs (safe with WAL). Or Litestream for continuous. + +**Forbidden:** multiple writer processes without a coordination layer; opening the same DB over NFS (lock semantics broken); `DELETE FROM bigtable` without `VACUUM` after (doesn't shrink file); committing the `.db` / `.db-wal` / `.db-shm` files to git. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-sqlx.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-sqlx.md new file mode 100644 index 0000000..54ada28 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/db-sqlx.md @@ -0,0 +1,39 @@ +# DB — SQLx (Rust) patterns + +Use when the project is Rust and needs a SQL-first (not ORM) query layer with compile-time checking. Pairs with `stack-rust-axum`, `stack-rust-cli`. [E4 — expert assessment] + +**Core versions:** `sqlx = "0.8"` (current as of 2026-04) with features `runtime-tokio`, `tls-rustls`, and one of `postgres` / `sqlite` / `mysql`. Never mix `runtime-async-std` and `runtime-tokio` — they clash at link time. [UNVERIFIED: verify latest on crates.io before pinning] + +**Compile-time checked queries:** +```rust +let row = sqlx::query!("SELECT id, name FROM users WHERE id = $1", user_id) + .fetch_one(&pool).await?; +``` +Requires either: +- `DATABASE_URL` env set during `cargo build` (live DB) — convenient in dev, brittle in CI. +- **Offline mode** (recommended for CI): `cargo sqlx prepare` commits `.sqlx/query-*.json` to the repo, then CI builds with `SQLX_OFFLINE=true` and no DB access. + +**Connection pool:** +```rust +let pool = sqlx::postgres::PgPoolOptions::new() + .max_connections(20) // tune to server max_connections / replica count + .acquire_timeout(Duration::from_secs(3)) + .connect(&database_url).await?; +``` +Single `PgPool` per process, `Arc`-cloned into handlers. Don't open per-request. + +**Migrations:** +```rust +sqlx::migrate!("./migrations").run(&pool).await?; +``` +Built-in runner reads `YYYYMMDDHHMMSS_.sql` files. For richer UX (up/down, status, create scaffolding) use the `kei-migrate` primitive in this kit. + +**Transactions:** +```rust +let mut tx = pool.begin().await?; +sqlx::query!("...").execute(&mut *tx).await?; +sqlx::query!("...").execute(&mut *tx).await?; +tx.commit().await?; // explicit; Drop = rollback +``` + +**Forbidden:** `sqlx::query` (non-macro) with untrusted input without `bind()` — that's string concat, i.e. SQL injection; `.unwrap()` on DB calls in prod paths; enabling both `runtime-tokio` and `runtime-async-std`; committing a live `DATABASE_URL` to `.env.example`. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-aws-ec2.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-aws-ec2.md new file mode 100644 index 0000000..f6f4102 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-aws-ec2.md @@ -0,0 +1,26 @@ +# DEPLOY — AWS EC2 (Instance Connect + Elastic IP) + +**SSH pattern — EC2 Instance Connect (60 s key window, no permanent authorized_keys):** +``` +aws ec2-instance-connect send-ssh-public-key \ + --instance-id i-XXXXXXXXXXXXXXXXX \ + --instance-os-user ec2-user \ + --ssh-public-key file://~/.ssh/id_ed25519.pub +ssh ec2-user@ # within 60 s +``` +Typical pattern: dedicated instance per project with an Elastic IP in a chosen region. Multi-project shared hosts are fine, but track co-tenancy (below). + +**Network posture:** +- **Elastic IP** for any node that needs stable identity (client configs, DNS, firewall rules). +- **Security Group**: allow SSH (port 22) ONLY from Tailscale CGNAT (`100.64.0.0/10`) or a specific admin IP. NEVER `0.0.0.0/0:22` in prod. +- Application ports exposed through an ALB or nginx reverse proxy — not directly on the instance. +- IMDSv2 REQUIRED (`HttpTokens=required`). v1 is SSRF-exploitable. + +**IAM:** +- Use IAM roles attached to the instance (`aws configure` on-instance hits the metadata endpoint). +- NEVER bake static AWS keys into AMI / env / user-data. +- Use a preconfigured named AWS profile (`--profile `), not interactive console for read ops. + +**Shared-host coordination:** if one instance runs multiple apps (e.g. API + marketing dashboards + internal tools), host-level change (apt / systemd / nginx) → cross-project impact check BEFORE reboot. + +**Forbidden:** open port 22 to `0.0.0.0/0`, static AWS keys in repo / `.env` committed to git, IMDSv1, rebooting shared hosts without cross-project sanity check, asking user to log into console for read ops (profile is set up — use it). diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-cloudflare.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-cloudflare.md new file mode 100644 index 0000000..971722f --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-cloudflare.md @@ -0,0 +1,28 @@ +# DEPLOY — Cloudflare (Workers / Pages / R2 / KV) + +**Tooling:** `wrangler` CLI (≥ 3.x). `wrangler.toml` is source of truth for bindings, NOT dashboard clicks. + +**Surface map:** +- **Workers** — edge compute. `wrangler deploy`. Logs via `wrangler tail`. +- **Pages** — static sites + Pages Functions. Per-branch preview URLs automatic. +- **R2** — S3-compatible object storage. No egress fees. +- **KV** — eventually-consistent key-value config store. Reads cached at the edge. +- **D1** — SQLite at edge (beta/GA track). + +**Secrets (NEVER in `wrangler.toml`):** +``` +wrangler secret put API_KEY # interactive, encrypted at rest +wrangler secret put --env prod DB_URL +``` +`wrangler.toml` is committed to git; secrets live in the platform vault only. + +**Self-sufficiency — CF API token scopes (request ALL up front):** +Workers KV · Workers R2 · Workers Scripts · Pages · Zone Edit · DNS · Zone Read · Zone Settings · SSL. Missing scope → ask user to add to token, NEVER ask user to click in the dashboard. + +**HARD RULE — CF ToS forbids proxy-mode traffic forwarding:** +- Worker for signaling, fronting helpers, metadata lookups — OK +- Worker as a full proxy pipe (upstream ⇆ Worker ⇆ downstream as a tunnel) — FORBIDDEN. Signaling / rendezvous Workers must do metadata only, NEVER arbitrary traffic. Violation → account ban. + +**Cache strategy:** `Cache-Control` headers authoritative; purge via `wrangler pages deployment` or API. `NEXT_PUBLIC_*` / `PUBLIC_*` vars ship to client — treat as non-secret. + +**Forbidden:** secrets in `wrangler.toml`, full-proxy Workers (ToS), manual dashboard edits when API token has the scope, committing `.dev.vars`. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-docker.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-docker.md new file mode 100644 index 0000000..5f65a4f --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-docker.md @@ -0,0 +1,34 @@ +# DEPLOY — Docker + +**Dockerfile — multi-stage MANDATORY** (build tools never ship to prod image): +``` +FROM rust:1.80 AS builder +WORKDIR /app +COPY . . +RUN cargo build --release --bin myapp + +FROM gcr.io/distroless/cc-debian12 +COPY --from=builder /app/target/release/myapp /myapp +USER nonroot:nonroot +HEALTHCHECK --interval=30s --timeout=3s CMD ["/myapp", "--healthcheck"] +ENTRYPOINT ["/myapp"] +``` + +**Base image:** `distroless` (preferred, no shell — smaller attack surface) or `alpine` (if musl compat) or `debian:slim`. NEVER `ubuntu:latest` for prod. + +**File ops:** +- `COPY` — deterministic. NEVER `ADD` (auto-extracts tars, fetches URLs — surprising behavior). +- `.dockerignore` committed. Includes `.git`, `target/`, `node_modules/`, `.env*`, `secrets/`. + +**Secrets:** +- NEVER `ENV SECRET=...` — leaks into image layers forever. +- Build-time secrets via `--secret id=foo,src=./foo.txt` (BuildKit). +- Runtime secrets via env injection from orchestrator / docker-compose `secrets:` (Swarm) / K8s Secret. + +**User:** `USER nonroot` (distroless provides it) or explicit `RUN useradd -u 10001 app && USER app`. Running as root = CVE amplifier. + +**Healthcheck:** MANDATORY. Orchestrator uses it for readiness/liveness; without it, failed containers stay "up". + +**docker-compose:** LOCAL DEV ONLY. For prod, the orchestrator (ECS, Fargate, K8s, Nomad, Docker Swarm) owns the deployment. Typical prod pattern: single container listening on internal port, behind nginx reverse proxy on a public port, colocated on a shared host. + +**Forbidden:** `ADD` for local files (use `COPY`); `USER root` in final stage; secrets in `ENV` or `ARG`; missing `HEALTHCHECK`; `docker-compose` as prod orchestrator; `:latest` tags in prod manifests; single-stage Dockerfile that ships build toolchain. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-hetzner-cloud.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-hetzner-cloud.md new file mode 100644 index 0000000..00c012f --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-hetzner-cloud.md @@ -0,0 +1,50 @@ +# DEPLOY — Hetzner Cloud (CX22 / CAX11 + TF + Cloud Firewall) + +**Why Hetzner:** cheapest EU VPS with reputable network. CX22 (x86, 2 vCPU / 4 GB / 40 GB) = **€3.79/mo + VAT**; CAX11 (Ampere ARM64, 2 vCPU / 4 GB / 40 GB) = **€3.79/mo + VAT**. Prices verified on [VERIFIED 2026-04-21]. Hourly billing caps at the monthly rate — safe to spin down for tests. + +**Terraform provider:** `hetznercloud/hcloud` (official). Pin version: +```hcl +terraform { + required_providers { + hcloud = { source = "hetznercloud/hcloud", version = "~> 1.49" } + } +} +provider "hcloud" { token = var.hcloud_token } +``` +Token via env: `export HCLOUD_TOKEN=$(grep ^HCLOUD_TOKEN ~/.claude/secrets/.env | cut -d= -f2)`. **NEVER commit the token** (RULE 0.8 — see `domain-has-secrets.md`). + +**Minimal `hcloud_server` resource:** +```hcl +resource "hcloud_server" "node" { + name = "kei-${var.env}-${var.role}" + image = "debian-12" + server_type = var.arch == "arm64" ? "cax11" : "cx22" + location = var.location # fsn1 / nbg1 / hel1 / ash / hil / sin + ssh_keys = [hcloud_ssh_key.admin.id] + user_data = file("${path.module}/cloud-init.yaml") + firewalls { firewall_id = hcloud_firewall.base.id } + labels = { project = "kei", env = var.env } +} +``` +`ssh_keys` is **mandatory** — passing it disables the root password e-mail path. + +**Cloud Firewall (stateful, IN by default DENY):** +```hcl +resource "hcloud_firewall" "base" { + name = "kei-base" + rule { direction = "in" protocol = "tcp" port = "22" source_ips = var.admin_cidrs } + rule { direction = "in" protocol = "icmp" source_ips = ["0.0.0.0/0", "::/0"] } + # Add app ports (443, 80) only when an app is deployed behind the node. +} +``` +Attach to the server via `firewalls { firewall_id = … }`. Cloud Firewall is the FIRST line of defense — it drops traffic before it hits the VM's ufw (see `security-firewall-ufw.md`). Both layers MUST agree. + +**Locations:** `fsn1` (Falkenstein DE), `nbg1` (Nürnberg DE), `hel1` (Helsinki FI), `ash` (Ashburn US), `hil` (Hillsboro US), `sin` (Singapore). Pick region closest to users; ARM64 `cax*` available in EU only [VERIFIED 2026-04-21]. + +**Snapshots + rescue:** `hcloud_snapshot` for golden images; `hcloud server enable-rescue` before SSH lockout recovery. Back up `user_data` and TF state (remote backend: S3-compatible such as R2). + +**Primitives provided by KeiSeiKit:** +- `_primitives/provision-hetzner.sh` — wrapper around `hcloud` CLI, idempotent create/destroy, checks existing server by name first. +- Complement with `_primitives/harden-base.sh` run over SSH after first boot. + +**Forbidden:** hcloud token in `.tf` or `.tfvars` committed to git; Cloud Firewall with port 22 open to `0.0.0.0/0`; creating servers with `keep_disk = false` then snapshotting (destroys data); using Hetzner Storage Boxes for anything needing low latency (they're SFTP-over-WAN). diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-local-only.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-local-only.md new file mode 100644 index 0000000..15b25b6 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-local-only.md @@ -0,0 +1,27 @@ +# DEPLOY — LOCAL ONLY (sensitive / pre-disclosure project) + +Use this block for any project that CANNOT be publicly deployed — typical triggers: proprietary ML weights/architectures you don't want in public training corpora, security tooling that burns its own usefulness on exposure, kernel-level code, client-confidential codebases. + +**Hard forbidden (no matter how small the change):** +- Public-URL share pages / static HTML dumps to public hosting +- Vercel / Netlify / GitHub Pages / Cloudflare Pages public deploy +- `gh repo create` public, `gh repo edit --visibility public` +- `git push` to a public remote (GitHub, public GitLab) +- Publishing architecture diagrams with node counts, param totals, or training configs +- Public benchmark tables naming this project + +**Allowed:** +- Private remotes (self-hosted Forgejo/Gitea over SSH on a private network) +- Tailscale-only internal services +- Local-only `127.0.0.1` / LAN dev servers +- `.app` / `.dmg` distribution via private channels + +**Double-confirmation override (both phrases required, in order, exact wording):** +1. "yes, deploy" +2. "I confirm publication" + +No approximations. Informal variants do NOT count. If either phrase is absent, refuse. + +**Example categories that typically require local-only:** censorship-circumvention tooling (public push burns exit-node IPs), ML ensembles with trained weights, control / guidance algorithms, offensive security research. + +**Report field:** "Public-deploy surface touched: none | — double-confirm obtained yes/no." diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-modal.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-modal.md new file mode 100644 index 0000000..7be3992 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-modal.md @@ -0,0 +1,26 @@ +# DEPLOY — Modal (GPU compute) + +A real cost-overrun incident (tens of dollars lost to unchecked runs) and a real KILL-GUARD incident (over an hour of training killed for a non-critical bug) shape every rule below. + +**Pre-launch 10-step checklist (all ticks before `modal run`):** +1. `modal app list` — verify no collisions/duplicates +2. GPU compat: A10G torch ≥ 2.0 (~$1.10/hr), H100 torch ≥ 2.1 (~$4.50/hr), B200 torch ≥ 2.6 (~$8/hr) +3. `cat` the script — confirm file edits actually landed +4. Cost estimate in dollars, verified on live https://modal.com/pricing (NOT from memory) +5. Volume + `vol.commit()` after each write +6. Checkpoints every 500 steps saving `state_dict` (not just JSON metrics) +7. `retries=modal.Retries(max_retries=1)` minimum +8. `.spawn()` for batches — NEVER `.map()` (cascade-kill on single failure) +9. `flush=True` on every print; progress every 250 steps +10. Single-variant smoke run BEFORE fanning out to N variants + +**Cost tiers:** AUTO < $5 · WARN $5-$20 (daily cap $20) · STOP > $20 (explicit user "yes, launch"). + +**KILL GUARD (no exception):** +- NEVER `modal app stop`, `modal app kill`, `kill `, `pkill -f modal` without literal user phrase "yes, stop it". +- Before any stop: `modal app list` → show user what is running, how long in, how much remaining, current checkpoint state. +- A bug in the launching script is NOT a reason to kill a running training run. + +**Volume persistence:** results survive only inside `modal.Volume` with explicit `vol.commit()`. Stdout is ephemeral — checkpoints in volume, metrics in volume, logs to volume. + +**Forbidden:** guessed prices from memory; `.map(return_exceptions=False)` for batches; `print()` without `flush=True`; launching N variants before one verified single-variant; restarting "for cleanliness" when checkpoints are flowing; stopping a run to fix the launching script. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-vps-generic.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-vps-generic.md new file mode 100644 index 0000000..8807f87 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/deploy-vps-generic.md @@ -0,0 +1,79 @@ +# DEPLOY — Generic VPS (provider-agnostic cloud-init + ssh-first-contact) + +**Target providers:** DigitalOcean Droplets, Vultr, UpCloud, Linode/Akamai. Each has slightly different Terraform providers + CLIs, but the Day-0 contract is identical: **boot a Debian/Ubuntu image with a cloud-init user-data blob; add one admin SSH key; nothing else.** + +**Day-0 cloud-init blob (`cloud-init.yaml`) — universal:** +```yaml +#cloud-config +hostname: kei-${env}-${role} +timezone: UTC +package_update: true +package_upgrade: true +packages: + - ufw + - fail2ban + - unattended-upgrades + - auditd + - needrestart + - curl + - jq +users: + - name: keiadmin + groups: sudo + shell: /bin/bash + sudo: ALL=(ALL) NOPASSWD:ALL + ssh_authorized_keys: + - ${ADMIN_PUBKEY} +ssh_pwauth: false +disable_root: true +write_files: + - path: /etc/ssh/sshd_config.d/99-kei.conf + permissions: '0644' + content: | + PasswordAuthentication no + PermitRootLogin no + MaxAuthTries 3 + AllowUsers keiadmin + ClientAliveInterval 120 + ClientAliveCountMax 2 +runcmd: + - [ systemctl, restart, ssh ] + - [ ufw, default, deny, incoming ] + - [ ufw, default, allow, outgoing ] + - [ ufw, allow, 22/tcp ] + - [ ufw, --force, enable ] +``` +The blob is intentionally provider-neutral. Provider-specific bits (private-network bring-up, metadata service quirks) go in a short appendix the provisioner appends. See `_primitives/harden-base.sh` for post-boot hardening re-runs. + +**SSH-first-contact (`ssh-first-contact.sh` pattern):** +```bash +# Wait for cloud-init to finish AND sshd to be ready on the new IP. +for i in $(seq 1 60); do + ssh -o ConnectTimeout=3 -o StrictHostKeyChecking=accept-new \ + "keiadmin@$IP" "cloud-init status --wait" && break + sleep 5 +done +ssh "keiadmin@$IP" "sudo test -f /var/lib/cloud/instance/boot-finished" +``` +`StrictHostKeyChecking=accept-new` is OK only for the FIRST contact (TOFU). Store the fingerprint to `~/.ssh/known_hosts`; subsequent connects use default strict mode. Never use `StrictHostKeyChecking=no` — accepts MitM silently. + +**Terraform skeleton (provider-agnostic via vars):** +```hcl +variable "provider_kind" {} # "digitalocean" | "vultr" | "upcloud" | "linode" +variable "region" {} +variable "size_slug" {} # provider-specific size id +variable "admin_pubkey" {} # raw ssh-ed25519 … +locals { + user_data = templatefile("${path.module}/cloud-init.yaml", { ADMIN_PUBKEY = var.admin_pubkey }) +} +# ... then a module-per-provider resource that all read `local.user_data` +``` +Keep TF state **local per-env-per-dev by default**; upgrade to remote backend (R2, S3, Terraform Cloud) only when ≥ 2 humans share state. + +**Per-provider gotchas (verified 2026-04-21):** +- **DigitalOcean:** Marketplace "Docker" images skip unattended-upgrades — start from plain Debian 12 instead. IPv6 requires `ipv6 = true` on the droplet. +- **Vultr:** `vultr-cli` needs `VULTR_API_KEY`; default firewall is OPEN — attach a firewall group or rely solely on ufw. +- **UpCloud:** IPs rotate on full stop+start unless you request `floating_ip`. Finnish ASN often preferred over Hetzner in RU-routed workloads (see `project-vortex.md`). +- **Linode:** cloud-init runs before disk resize on some plans → `growpart` may need a rerun on first `ssh`. + +**Forbidden:** baking the admin private key into an AMI/snapshot; reusing one SSH keypair across envs; letting cloud-init pull scripts from a mutable URL (`curl … | bash` in `runcmd:` — pin to a hash); running `apt-get dist-upgrade -y` in `runcmd` without `needrestart` to surface pending reboots. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-architecture-diagrams.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-architecture-diagrams.md new file mode 100644 index 0000000..9eb6e8b --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-architecture-diagrams.md @@ -0,0 +1,86 @@ +# DOCS — Architecture diagrams (Mermaid) + +Diagrams live beside the prose they describe. Mermaid renders natively on +GitHub / Forgejo / Gitea / Obsidian — no extra tooling needed to view. + +## When to include + +- Any agent/skill that scaffolds documentation for a multi-component system +- Any repo with ≥ 3 services / layers / subsystems + +## Four diagram patterns (use the right one) + +### 1. System context (C4 level 1) — `flowchart LR` + +```mermaid +flowchart LR + U[User] -->|HTTP| API[API Gateway] + API -->|gRPC| SVC[Service] + SVC -->|SQL| DB[(PostgreSQL)] + SVC -->|publish| Q[[Queue]] +``` + +Use for: one-page overview, onboarding, README architecture section. + +### 2. Sequence — `sequenceDiagram` + +```mermaid +sequenceDiagram + Client->>API: POST /orders + API->>DB: INSERT + DB-->>API: id + API-->>Client: 201 Created +``` + +Use for: request flow, auth handshake, error recovery sequence. + +### 3. State machine — `stateDiagram-v2` + +```mermaid +stateDiagram-v2 + [*] --> Pending + Pending --> Running: start + Running --> Done: success + Running --> Failed: error + Failed --> Pending: retry +``` + +Use for: job lifecycle, FSM-driven features, connection state. + +### 4. ER / data model — `erDiagram` + +```mermaid +erDiagram + USER ||--o{ ORDER : places + ORDER ||--|{ LINE_ITEM : contains +``` + +Use for: DB schema summary. Keep ≤ 10 entities per diagram. + +## Rules + +- **Diagram-as-code, no binary exports.** `.mmd` or fenced block, never `.png` +- **≤ 15 nodes / 20 edges per diagram.** Over that → split +- **Labels are nouns.** Edges are verbs. No prose inside nodes +- **One diagram = one concern.** Don't mix system context + sequence in one chart +- **Preview locally** with `mmdc` before commit: `mmdc -i diagram.mmd -o /tmp/preview.svg` +- **Link to source in caption** — "See `docs/diagrams/orders.mmd` for source" + +## Forbidden + +- ASCII art for multi-node graphs (use Mermaid — renders everywhere) +- Diagrams that contradict the code (stale → delete or fix) +- Secrets / real hostnames / IPs in diagrams (use placeholders) + +## Install `mmdc` (preview tool) + +``` +npm install -g @mermaid-js/mermaid-cli # one-time +mmdc -i docs/diagrams/context.mmd -o /tmp/preview.svg +``` + +## References + +- Mermaid syntax — https://mermaid.js.org/intro/ [VERIFIED: https://mermaid.js.org/intro/] +- C4 model — https://c4model.com/ [VERIFIED: https://c4model.com/] +- `~/.claude/rules/doc-conventions.md` diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-claude-md.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-claude-md.md new file mode 100644 index 0000000..d47f0c8 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-claude-md.md @@ -0,0 +1,25 @@ +# DOCS — `CLAUDE.md` (project bootstrap template) + +A per-project `CLAUDE.md` answers one question: *what does a Claude agent need to know in the first 30 seconds on this repo?* It is read before any code work. Keep it under ~150 lines. + +**Canonical sections (in this order):** + +1. **Project one-liner** — name, domain, status (`active | maintenance | archived`), primary stack, public-surface flag. +2. **Architecture** — 2-5 bullets + optional Mermaid block. Layer names match the code tree. If a layer diagram helps, `_blocks/docs-architecture-diagrams.md` has the patterns. +3. **Stack / dependencies** — language(s), major frameworks, DB, queue, deploy target. One line per item. +4. **Constraints** — API rate limits, licensing, cost tiers, platform quirks (e.g. "Flux 2 Pro zero-config", "SPM needs `-Xlinker`"). +5. **Known issues** — bugs that aren't fixable now, workarounds, tickets. Keep dated. +6. **Test invariants** — how tests are run (`cargo test --release`, `pytest`, `flutter test`), coverage floor, which tests are load-bearing. +7. **Commands cheatsheet** — 5-8 commands the agent will type most: build, test, lint, deploy, format. +8. **Secrets / credentials** — env var NAMES only (RULE 0.8). Never literal tokens. Path: `secrets/*.env`. +9. **Related files** — `DECISIONS.md`, `HOTPATHS.md`, `TODO.md`, runbooks. + +**Placeholders used by `kei-docs-scaffold.sh`:** +`{{PROJECT_NAME}}`, `{{STACK}}`, `{{DEPLOY}}`, `{{PRIMARY_LANGUAGE}}`, `{{TEST_CMD}}`. + +**Forbidden:** +- Copying the umbrella `~/.claude/CLAUDE.md` here — link to it, do not duplicate. +- Storing API tokens / private URLs (use `secrets/*.env`). +- Marketing prose. Every line must be actionable by the agent. + +**Source:** Anthropic Claude Code docs — `claude.ai/code` project-memory convention (E4). Karpathy viral CLAUDE.md (forrestchang/andrej-karpathy-skills, 15K+ stars) [E4]. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-decisions-adr.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-decisions-adr.md new file mode 100644 index 0000000..4c5bb4a --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-decisions-adr.md @@ -0,0 +1,59 @@ +# DOCS — `DECISIONS.md` / ADR template (MADR 4.0) + +Architecture Decision Records capture *why* a non-trivial choice was made, so future maintainers (including agents) don't re-litigate. Format: **MADR 4.0** (Markdown Any Decision Records, 2024). Nygard originated the practice in 2011. + +**One ADR per non-trivial decision.** File path convention: +- Single-file log: append to `DECISIONS.md` (top-of-file = newest). +- Per-decision files: `docs/adr/NNNN-kebab-case-title.md` (NNNN = zero-padded int). + +**MADR 4.0 template (copy as-is):** + +```markdown +# ADR-NNNN: + +- **Status:** Proposed | Accepted | Rejected | Superseded-by-ADR-NNNN | Deprecated +- **Date:** YYYY-MM-DD +- **Deciders:** @handle, @handle +- **Evidence grade:** E1-E6 (see `_blocks/evidence-grading.md`) + +## Context and Problem Statement +<1-3 sentences: what forces us to decide? What breaks if we don't?> + +## Decision Drivers +- Driver 1 (e.g. cost < $X/mo) +- Driver 2 (e.g. must run offline) +- Driver 3 (e.g. team knows language Y) + +## Considered Options +1. **Option A** — one-line summary +2. **Option B** — one-line summary +3. **Option C** — one-line summary + +## Decision Outcome +Chosen: **Option **, because <1-2 sentences tying back to drivers>. + +### Consequences +- Positive: +- Negative: +- Neutral: + +## Pros and Cons of the Options +### Option A +- Pro: ... +- Con: ... +### Option B +- Pro: ... +- Con: ... + +## Links +- Supersedes: ADR-NNNN +- Related: `HOTPATHS.md#section`, external URL +- Evidence source: [VERIFIED: url] or [UNVERIFIED] +``` + +**Rules:** +- Status `Accepted` = implemented or actively being implemented. `Proposed` = under review. `Rejected` stays as an ADR (the record of why we said no). +- Never delete a past ADR. Supersede with a new ADR that references the old number. +- Evidence grade mandatory (RULE 0.4). No grade → the ADR is unreviewable. + +**Source:** MADR 4.0 spec — [adr/madr](https://adr.github.io/madr/) [E4]. Nygard 2011 original post `cognitect.com/blog/2011/11/15/documenting-architecture-decisions` [E4]. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-readme-template.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-readme-template.md new file mode 100644 index 0000000..f201b96 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-readme-template.md @@ -0,0 +1,75 @@ +# DOCS — Public `README.md` scaffold + +`README.md` is the first file a new reader (human OR agent) opens. One file, nine sections, in this order. Keep ≤ 300 lines; longer material lives in `docs/`. + +**Nine-section template:** + +```markdown +# {{PROJECT_NAME}} + +> One-line pitch (what + why, ≤ 100 chars). + +[![CI](badge)](link) [![License](badge)](link) [![Version](badge)](link) + +## What +2-3 sentences: what it does, who it's for. No marketing adjectives. + +## Why +2-3 sentences: problem this solves, alternatives considered, why this one. +Link to the relevant ADR: [DECISIONS.md](DECISIONS.md#adr-nnnn). + +## Install +```bash +# Primary path — the 90% case + +``` + +**Prerequisites:** = vN, OS constraints, system deps>. + + + +## Usage +Smallest working example. Copy-pasteable. +```bash + +``` + +Link to a richer quickstart in `docs/quickstart.md` if >20 lines. + +## Development +```bash +git clone +cd + + +``` + +Project layout: +- `src/` — implementation +- `tests/` — integration tests +- `docs/` — long-form docs +- `{{STACK}}-specific notes → link> + +## Deploy +Target: **{{DEPLOY}}**. One-liner: ``. +Full runbook: `docs/runbooks/deploy.md`. + +## Architecture +One paragraph + one Mermaid diagram (see `_blocks/docs-architecture-diagrams.md`). Detail in `docs/architecture.md`. + +## Contributing +- Issue tracker: +- Commit convention: Conventional Commits (see `_blocks/git-conventions` in kit) +- PR checklist: `docs/CONTRIBUTING.md` + +## License + — see [LICENSE](LICENSE). +``` + +**Rules:** +- No secrets (RULE 0.8). No literal tokens. +- Install command must be ONE command for the happy path. +- Every "see docs/X" link must resolve — scaffolder verifies or creates the target. +- If the project is private / not publicly deployable (banned list per `rules/security.md`), mark the repo header with `` and omit public badges. + +**Source:** standard-readme spec (RichardLitt/standard-readme) [E4]; GitHub "About READMEs" [E4]. diff --git a/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-runbook.md b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-runbook.md new file mode 100644 index 0000000..83d50f7 --- /dev/null +++ b/_archive/forks/2026-04-23/ci-cost-fix-w15/_blocks/docs-runbook.md @@ -0,0 +1,66 @@ +# DOCS — Operational runbook template + +A runbook tells on-call (or a future agent) exactly what to do when an alert fires. Every production system needs one per failure class. Format: *symptoms → checks → fixes → escalation*. + +**File path:** `docs/runbooks/-.md`. Index in `docs/runbooks/README.md` (or link from `HOTPATHS.md`). + +**Template (copy as-is):** + +```markdown +# Runbook — : + +## Metadata +- **Severity:** SEV1 (page now) | SEV2 (work hours) | SEV3 (next day) +- **On-call rotation:** +- **Last rehearsed:** YYYY-MM-DD (stale > 90d → re-rehearse) +- **Linked ADRs:** ADR-NNNN + +## Symptoms +- Observable signal: > for +- User impact: +- Typical dashboards: + +## Diagnostic checks (in order) +1. Check dashboard X — if metric Y is flat, skip to step 4 +2. Tail logs: `` +3. Inspect dependency Z status page: +4. Reproduce locally if unclear: `` + +## Fixes (try in order; STOP at first that works) +### Fix A — restart (lowest risk) +```bash + +``` +Verify: within