futura-scion 0.2.0 → 0.2.1

package/README.md

@@ -617,6 +617,154 @@ default) keeps it fully inert even for tasks that opt in with
 `payload.generate: true`. The doctrine is unchanged — the LLM proposes,
 the Gate disposes, the certificate proves it.
 
+### Self-improvement — the harness evolves under its own Gate (`scion evolve`)
+
+FS applies its verification doctrine to ITSELF. The nightly evolution loop
+(imp_doc adoption, zero-LLM) is: **mine → propose → gate → apply**.
+
+- **Weakness miner** — failures from the queue and trail are normalized to
+  signature hashes (`failureSignatureOf`); a signature with ≥3 occurrences
+  across ≥2 goal families is a HARNESS weakness (not one goal's bad luck),
+  classified into the 4-layer taxonomy (environment-contract /
+  procedural-skill / action-realization / trajectory-regulation).
+- **Proposals** — deterministic per layer (bounds-field, verifier-recipe,
+  tool-filter-rule, spec-note), hard 20-line diff budget, targets must
+  exist. No LLM anywhere; a generator can be attached later but is still
+  gate-checked.
+- **The harness-edit Gate** — SICA utility scoring
+  (`U = 0.5·passRate + 0.25·(1−cost) + 0.25·(1−time)`) over the replay
+  window: accept only if utility improves AND pass-rate does not regress.
+  Every decision lands in the `harness_edits` audit table; rejected
+  edit-hashes are remembered (never re-proposed); bounded to ≤3 accepted
+  edits per batch; addressed signatures skip (idempotent). Gate-passing but
+  utility-unproven edits ARCHIVE in `harness_variants` for monthly re-scoring
+  (`scion evolve variants`) — population thinking, nothing promising is lost.
+
+```bash
+scion evolve              # one bounded, idempotent batch
+scion evolve --dry-run    # mine + propose only
+scion evolve variants     # re-score the archive (G4)
+```
+
+### Stuck-trajectory watchdog + completeness + grading (the guardrails)
+
+- **Watchdog** (`src/kernel/watchdog.js`) — hash consecutive `(action,
+  state)` pairs; 3 identical → stuck, abort before burning the bounds.
+  Key-order-insensitive, pure, also usable as an audit (`findStuckPoint`).
+- **Completeness** (`src/mind/completeness.js`) — every research bundle now
+  carries a deterministic completeness verdict: entity coverage,
+  subquestion corroboration (stem-folded), source-quality floor. Incomplete
+  results produce gap-targeted `replan_hints` and a bounded replan loop
+  (`verifyWithReplan`, ≤2 replans) — the VMAO orchestration-level check.
+- **Run records + grading** (`scion eval`) — every task appends a portable
+  JSONL run record to `eval/runs.jsonl` (trajectory, cost, outcome); the
+  3-scorer grader (outcome 0.5 / trajectory 0.3 / economy 0.2) emits
+  per-run grades and a trend file. `scion eval regression` gates on
+  per-family pass-rate drops; `scion eval capability` trends pass-rate per
+  difficulty tier.
+
+### Graph-linked memory + interventions (the brain connects and travels)
+
+- **Memory graph** — every save links into `memory_links`:
+  token-overlap → `related` (weight = Jaccard), same family + opposite
+  outcome polarity → `contradicts` (the older side ranks lower —
+  suppression, never deletion), newer-higher-confidence → `supersedes`.
+  Recall does 1-hop expansion (neighbors at ×0.5) and trust ranking:
+  gate-verified memories weigh 1.0, observed 0.95, web 0.7, LLM 0.6.
+- **Interventions** (`scion interventions import [dir]`) — accepted harness
+  edits export as `interventions/<hash>.intervention.yaml` artifacts
+  (signature, layer, edit, evidence, provenance) and import into another
+  FS instance ONLY if that instance's own history shows the same failure
+  signature ≥2 times: no blind cross-pollination. This is the fleet brain's
+  transport format for learned fixes.
+
+### Call-tree context + indexed actions (Jev/LLM-as-code discipline)
+
+- **Call-tree context** (`src/mind/calltree-context.js`) — the generate
+  rung's context is the task's ANCESTOR CHAIN from the trail, each ancestor
+  budget-capped by depth (deeper → less), total ≤4000 chars — replacing
+  flat truncation. Flat inputs stay backward compatible.
+- **Indexed action space** — clarification options render as numbered
+  ACTIONS with executable consequences (`[2] analyze the named file and
+  apply a gate-verified fix`); answering `2` is a complete decision.
+- **Pre-execution revalidation** — tool calls re-check freshness before
+  spawning: file targets that vanished since the decision refuse loudly
+  (`stale decision`) instead of executing into a world that moved.
+
+### The learn → build → improve → repeat layer (`scion learn`)
+
+The mandate: FS must get BETTER at every kind of problem it takes on —
+software, research, finding things — from its own mistakes, without anyone
+remembering to run a command. This layer is the always-on circulatory
+system connecting every learning organ:
+
+- **LEARN** — every task outcome (verified fix, gate failure, escalation,
+  error) is observed automatically by the worker and written as a graded
+  run record. Failures are the raw material; nothing escapes the loop.
+- **BUILD** — repeated verified fixes forge into seeds (precision-floored);
+  clarifications teach the NLU lexicon; interventions export to the fleet.
+- **IMPROVE** — the weakness miner finds recurring failure patterns across
+  ALL domains; the harness gate utility-verifies bounded self-edits; the
+  variant archive re-scores what didn't win yet.
+- **REPEAT** — every cycle is measured into the `learn_cycles` ledger
+  (pass rate, replay hit rate, deterministic share, seeds, edits accepted);
+  improvement is a TREND over rows, never a claim.
+
+```bash
+scion learn            # one full cycle now
+scion learn trend      # is FS improving? (ledger-backed, ≥2 cycles)
+scion learn vitals     # current vital signs
+```
+
+With `learn: { auto: true }` in config, `scion serve` runs a cycle every
+`learn.interval_ms` (default 6h) in-process — the harness improves itself
+while it works. Zero-LLM by construction.
+
+### FS Desktop — the standalone UI (chat / agent / plan / architect)
+
+FS ships a real UI in two forms, both zero-build:
+
+- **Web console (ships in the npm package):** `scion serve` now serves the
+  FS Desktop SPA at `http://127.0.0.1:5107/ui` — open it in any browser.
+  Nothing extra to install; works over SSH tunnels and on remote machines.
+- **Electron desktop shell (`desktop/`):** a thin host that boots the kernel
+  as a child process and renders the same UI in a native window.
+  ```bash
+  npm run desktop        # dev (needs: cd desktop && npm install)
+  npm run desktop:build  # installers (NSIS / DMG / AppImage) via electron-builder
+  ```
+
+**Surfaces** (every action goes through the same kernel routes the CLI and
+MCP use — the UI can never do more than the kernel allows):
+
+- **Chat with streaming + history** — replies stream over SSE with live
+  NLU/agent progress events; every conversation persists in the brain with a
+  sidebar (new / open / rename / delete), auto-titling, and secret redaction
+  at write time — history survives restarts and travels with the DB.
+- **Chat mode** — plain language in, state-grounded answers out: status,
+  brain/economy/queue lookups, brain search. Deterministic NLU; no LLM.
+- **Agent mode** — real work: your utterance is NLU-interpreted, slotted,
+  enqueued, and run through the full ladder→Gate pipeline with a rung+
+  certificate summary in the transcript.
+- **Plan mode** — research with tools + the deterministic completeness
+  verdict (entity coverage, corroboration, source floor) as evidence.
+- **Architect mode** — one-click declared-architecture scan with violations.
+- **Review queue** — the human gate in the loop: escalations with the
+  ladder's last proposal, Approve/Reject/Defer, badge counts live.
+- **Trail / Brain / Economy dashboards** — the journaled decision trail,
+  brain stats, and the token-economy report as live views.
+- **Autonomy toggle** — semi-autonomous (default: each agent action asks
+  through the Gate + Review flow) vs autonomous (apply directly; the Gate
+  still verifies everything, destructive work still escalates).
+
+**LLM attach (optional):** Settings → Provider covers Ollama, LM Studio,
+OpenAI, Anthropic, OpenRouter, and any OpenAI-compatible endpoint, with a
+connection test. Saving sets `llm.provider/baseUrl/model/apiKey` +
+`llm.daily_tokens` in config, which arms rung G (the governance-shell
+generator): the model PROPOSES patches, the Gate verifies them by exit code,
+and nothing unverified is learned or shipped. `daily_tokens: 0` keeps FS
+fully deterministic — a local model (Ollama/LM Studio) works offline.
+
 ### Semi-autonomous auto-fix (`scion watch` + `daemon.auto_fix`)
 
 By default the daemon only **detects and remembers**. With `daemon.auto_fix: true`

package/bin/scion.js

@@ -18,6 +18,7 @@
 import { createInterface } from 'node:readline';
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
 import * as trail from '../src/kernel/trail.js';
 import {
   enqueue, runSwarm, economy, trailList, runTask, claim as claimTask,
@@ -441,6 +442,54 @@ switch (cmd || '') {
     console.log(JSON.stringify({ dry_run: dryRun, ...result }, null, 2));
     break;
   }
+  case 'eval': {
+    // Portable run records + grading (workstream F):
+    //   scion eval regression   per-family pass-rate drop check (gate-able)
+    //   scion eval capability   pass-rate per difficulty tier (trend only)
+    const { regressionCheck, capabilityReport } = await import('../src/mind/grade.js');
+    if (arg === 'capability') console.log(JSON.stringify(capabilityReport(), null, 2));
+    else console.log(JSON.stringify(regressionCheck(), null, 2));
+    const reg = regressionCheck();
+    if (arg !== 'capability' && Object.values(reg).some(f => f.ok === false)) process.exitCode = 1;
+    break;
+  }
+  case 'interventions': {
+    // Shared failure-intervention library (workstream E):
+    //   scion interventions import [dir]   import artifacts with the local-occurrence floor
+    const { importInterventions } = await import('../src/mind/interventions.js');
+    const dir = arg && arg !== 'import' ? arg : 'interventions';
+    console.log(JSON.stringify(importInterventions(dir), null, 2));
+    break;
+  }
+  case 'learn': {
+    // THE learn → build → improve → repeat layer:
+    //   scion learn            one full cycle (mine → gate → forge → rescore → ledger)
+    //   scion learn trend      is FS improving? (ledger-backed, ≥2 cycles)
+    //   scion learn vitals     the current vital signs
+    const loop = await import('../src/mind/learn-loop.js');
+    if (arg === 'trend') console.log(JSON.stringify(loop.trend(), null, 2));
+    else if (arg === 'vitals') console.log(JSON.stringify(loop.vitals(), null, 2));
+    else console.log(JSON.stringify(loop.cycle(), null, 2));
+    break;
+  }
+  case 'evolve': {
+    // The nightly harness-evolution pass (A4): mine weaknesses → propose
+    // harness edits → gate them (SICA utility) → apply the accepted. Bounded
+    // (≤3 accepted per batch), idempotent (addressed signatures skip),
+    // zero-LLM. `scion evolve --dry-run` mines+proposes but applies nothing.
+    //   scion evolve              one bounded batch
+    //   scion evolve --dry-run    mine + propose only
+    //   scion evolve variants     re-score archived harness variants (G4)
+    const hGate = await import('../src/mind/harness-gate.js');
+    if (arg === 'variants') {
+      console.log(JSON.stringify(hGate.rescoreVariants({}), null, 2));
+      break;
+    }
+    const dryRun = arg === '--dry-run';
+    const result = hGate.evolveBatch(dryRun ? { applyAfter: undefined } : {});
+    console.log(JSON.stringify({ dry_run: dryRun, ...result }, null, 2));
+    break;
+  }
   case 'recipes': {
     // The recipe library: gate verifier bundles per stack.
     //   scion recipes             list the library
@@ -565,9 +614,21 @@ switch (cmd || '') {
     //   scion conventions <file>     deviations of one file (evidence rows)
     const c = await import('../src/mind/conventions.js');
     if (arg && !arg.startsWith('--')) {
-      const { readFileSync } = await import('node:fs');
-      const source = readFileSync(arg, 'utf8');
-      console.log(JSON.stringify({ file: arg, deviations: c.deviationsFor(source) }, null, 2));
+      const { readFileSync, statSync } = await import('node:fs');
+      let st = null;
+      try { st = statSync(arg); } catch { /* handled below */ }
+      if (st?.isDirectory()) {
+        // A directory argument means: discover + persist over that tree.
+        const result = c.discoverConventions(arg);
+        c.saveConventions(result);
+        console.log(JSON.stringify({ ok: true, files: result.files, conventions: result.conventions }, null, 2));
+      } else if (st?.isFile()) {
+        const source = readFileSync(arg, 'utf8');
+        console.log(JSON.stringify({ file: arg, deviations: c.deviationsFor(source) }, null, 2));
+      } else {
+        console.error(`conventions: no such file or directory: ${arg}`);
+        process.exitCode = 1;
+      }
     } else {
       const result = c.discoverConventions(arg && arg !== '--all' ? arg : 'src');
       c.saveConventions(result);
@@ -641,11 +702,35 @@ switch (cmd || '') {
     });
     const api = await startApi({ port: Number(arg) || undefined, leader });
     leader.start();
+    // FS Desktop support: provider-backed generator (rung G) from config,
+    // and the default agent-mode runTask over the real oracle.
+    const { makeGenerator } = await import('../src/mind/provider.js');
+    const { configureLlm } = await import('../src/ladder.js');
+    const generator = makeGenerator(cfg.llm);
+    configureLlm({ generator, daily_tokens: cfg.llm?.daily_tokens ?? 0 });
+    const { setRunTask } = await import('../src/http.js');
+    setRunTask(async (task) => runTask(claimTask('ui', task.id), oracle));
+    // The always-on learn→build→improve→repeat layer (config learn.auto).
+    if (cfg.learn?.auto) {
+      const { startAuto } = await import('../src/mind/learn-loop.js');
+      startAuto();
+      console.log(`  learn-loop: auto-cycle every ${Math.round((cfg.learn.interval_ms ?? 21600000) / 60000)} min`);
+    }
     // Observability (env-gated): OTLP log export + ntfy push.
     const { startObservers } = await import('../src/kernel/observe.js');
     startObservers();
     console.log(`scion serve: http://127.0.0.1:${api.port} role=${leader.role}${leader.primaryUrl ? ` primary=${leader.primaryUrl}` : ''} (SCION_TOKEN guards routes when set)`);
-    console.log('  flags: --follower --lease-ms N --leader-poll-ms N --primary-url URL');
+    console.log(`  UI:      http://127.0.0.1:${api.port}/ui   ← FS Desktop (chat, agent, dashboards)`);
+    console.log('  flags: --follower --lease-ms N --leader-poll-ms N --primary-url URL [--open]');
+    // --open: launch the default browser at the UI (best-effort, every OS).
+    if (process.argv.includes('--open')) {
+      const { spawn } = await import('node:child_process');
+      const url = `http://127.0.0.1:${api.port}/ui`;
+      const opener = process.platform === 'win32' ? spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' })
+        : process.platform === 'darwin' ? spawn('open', [url], { detached: true, stdio: 'ignore' })
+        : spawn('xdg-open', [url], { detached: true, stdio: 'ignore' });
+      opener.unref();
+    }
     const sweep = setInterval(() => {
       try { dailyMaintenance(); } catch { /* maintenance never kills the server */ }
     }, 60_000);
@@ -659,6 +744,16 @@ switch (cmd || '') {
     }
     break;
   }
+  case 'ui': {
+    // `scion ui` — the one-command desktop experience: serve + open the UI.
+    // Identical to `scion serve --open`; a separate word because that's what
+    // people type after `npm i -g futura-scion`.
+    const self = process.argv[1];
+    const rest = process.argv.slice(2).filter(a => a !== 'ui');
+    const r = spawnSync(process.execPath, [self, 'serve', ...rest, '--open'], { stdio: 'inherit', env: process.env });
+    process.exitCode = r.status ?? 0;
+    break;
+  }
   case 'remote': {
     // Distributed tier: drain a remote scion's queue from THIS machine.
     //   scion remote --url http://host:5107 --workerId rw-1 [--max N] [--token T]
@@ -687,9 +782,13 @@ switch (cmd || '') {
   }
   case 'dash': {
     // Live TUI dashboard — one ANSI refresh loop over kernel state.
+    // `scion dash <frames> <intervalMs>` runs N frames then exits (CI/trial
+    // friendly); bare `scion dash` loops until Ctrl+C as before.
     const { runDashboard } = await import('../src/kernel/dash.js');
-    const intervalMs = Number(restArgs.find(a => /^\d+$/.test(a))) || 2000;
-    await runDashboard({ intervalMs });
+    const nums = [arg, ...restArgs].filter(a => /^\d+$/.test(a)).map(Number);
+    const frames = nums[0] ?? null;
+    const intervalMs = nums[1] ?? 2000;
+    await runDashboard({ intervalMs, ...(frames ? { maxFrames: frames } : {}) });
     break;
   }
   case 'mcp': {
@@ -778,6 +877,6 @@ switch (cmd || '') {
     break;
   }
   default:
-    console.error(`unknown command: ${cmd}\nusage: scion [run "<task>" | swarm [n] | plan <target> [--out m.json] [--run] | workflow <manifest.json> | analyze [dir] | fix <file> | watch [dir] [--auto-fix] [--concurrency N] | economy | brain | remember "<c>" | search "<q>" | reason "<topic>" | forge [--dry-run] | review [-i] | resolve <id> approve "<fix>"|reject|defer | gaps [teach <id> <intent> | forget <id> | --all] | scopes [list|add <name>|rm <name>] | serve [port] [--follower --lease-ms N --leader-poll-ms N --primary-url URL] | remote --url URL --workerId ID | leader | recipes [doctor | show <name>]`);
+    console.error(`unknown command: ${cmd}\nusage: scion [run "<task>" | swarm [n] | plan <target> [--out m.json] [--run] | workflow <manifest.json> | analyze [dir] | fix <file> | watch [dir] [--auto-fix] [--concurrency N] | economy | brain | remember "<c>" | search "<q>" | reason "<topic>" | forge [--dry-run] | review [-i] | resolve <id> approve "<fix>"|reject|defer | gaps [teach <id> <intent> | forget <id> | --all] | scopes [list|add <name>|rm <name>] | ui | serve [port] [--follower --lease-ms N --leader-poll-ms N --primary-url URL] | remote --url URL --workerId ID | leader | recipes [doctor | show <name>]`);
     process.exitCode = 1;
 }

package/knowledge/architecture.yaml

@@ -0,0 +1,98 @@
+# knowledge/architecture.yaml — software architecture and design knowledge.
+pack: architecture-design
+description: Architecture discipline — coupling, boundaries, dependency direction, design trade-offs
+entries:
+  - title: Dependencies point from volatile to stable
+    type: principle
+    importance: 9
+    tags: [architecture, dependencies]
+    content: >
+      The most stable abstractions (domain concepts, interfaces) should be
+      imported BY the most volatile ones (UI, infrastructure, adapters) —
+      never the reverse. When infrastructure dictates domain shape, every
+      database or framework change ripples into business logic. Source:
+      stable-dependencies principle, hexagonal architecture (Cockburn),
+      clean architecture (Martin).
+  - title: Coupling is about knowledge, not syntax
+    type: principle
+    importance: 8
+    tags: [architecture, coupling]
+    content: >
+      Two modules are coupled when a change in one forces a change in the
+      other. Sharing a database table, an implicit file format, or a timing
+      assumption couples more tightly than an explicit interface call.
+      Reduce shared knowledge before reducing call counts. Source: Parnas
+      information hiding, Connascence (Meilir Page-Jones).
+  - title: Boundaries earn their cost by isolating change
+    type: principle
+    importance: 8
+    tags: [architecture, boundaries, microservices]
+    content: >
+      Every boundary (module, service, team) has a real cost: serialization,
+      versioning, network failure, coordination. A boundary pays for itself
+      only where change frequency or failure isolation demands it. Uniform
+      micro-decomposition is a tax paid everywhere for benefits realized
+      somewhere. Source: Monolith-to-Microservices (Fowler), Saša Ćurčić
+      critique lineage.
+  - title: Contracts at boundaries — versioned, explicit, backward-aware
+    type: principle
+    importance: 8
+    tags: [api, versioning]
+    content: >
+      Any interface another party codes against (API, schema, event) is a
+      contract: add fields additively, never reinterpret existing fields,
+      deprecate before removal, and version when breaking. Implicit
+      contracts (undocumented JSON shapes) break at the worst time — in
+      production, in another team's code. Source: API design practice,
+      Postel-informed evolution guidance.
+  - title: Idempotency and retries are partners
+    type: principle
+    importance: 8
+    tags: [distributed, reliability]
+    content: >
+      A retry without idempotency multiplies effects (double charge, double
+      email); an idempotent operation without retries wastes its own safety.
+      Design write operations to be safely repeatable (idempotency keys,
+      conditional updates) before adding automatic retry logic. Source:
+      distributed-systems practice, AWS/Google API guidance.
+  - title: Caching invalidates — plan expiry before performance
+    type: principle
+    importance: 8
+    tags: [caching, performance]
+    content: >
+      A cache is a correctness trade dressed as an optimization: every cache
+      needs an invalidation story (TTL, explicit bust, event-driven) and a
+      staleness budget the business accepts. Two hard problems (naming,
+      cache invalidation) — the second one causes outages. Source: Kahle's
+      aphorism lineage, cache practice.
+  - title: Data outlives code — schema evolution is the long game
+    type: principle
+    importance: 8
+    tags: [database, schema]
+    content: >
+      Applications are replaced; databases persist. Design migrations as
+      expand → migrate → contract (never in-place breaking changes), keep
+      constraints in the database (the last line of defense), and treat
+      backfills as explicit, resumable jobs. Source: evolutionary database
+      design, live-migration practice.
+  - title: Make illegal states unrepresentable
+    type: principle
+    importance: 8
+    tags: [modeling, types]
+    content: >
+      Model domains so impossible combinations cannot be constructed:
+      sum types/unions over boolean flags, constructors that establish
+      invariants over bare structs. Defense shifts from runtime checks
+      everywhere to construction-time guarantees in one place. Source:
+      type-driven design (Yaron Minsky lineage), algebraic data types.
+  - title: Concurrency design — shared mutable state is the enemy
+    type: principle
+    importance: 8
+    tags: [concurrency]
+    content: >
+      Races, deadlocks, and lost updates all require shared mutable state
+      reached by multiple actors. Prefer immutable data, message passing,
+      or single-owner designs; when sharing is unavoidable, define the
+      locking discipline once and document it — ad-hoc locking is a race
+      with a delay timer. Source: Hoare CSP, Java Concurrency in Practice
+      (Goetz), actor-model lineage.

package/knowledge/core.yaml

@@ -0,0 +1,99 @@
+# knowledge/core.yaml — the discipline's foundational principles.
+# Loaded into the reserved knowledge:core brain slice; consulted by recall
+# and the reasoner across every project. Data, not code — the Gate and the
+# analyzer never act on these; they inform judgment.
+pack: core-principles
+description: Foundational software engineering principles (source-attributed consensus)
+entries:
+  - title: Make change small and reversible
+    type: principle
+    importance: 9
+    tags: [change, review, risk]
+    content: >
+      Small, reversible changes fail cheaply and succeed verifiably. Large
+      changes hide defects behind review volume and make rollback impossible.
+      Decompose work into commits/PRs that can be understood, verified, and
+      reverted independently. Source: industry review-practice consensus.
+  - title: Verify behavior with executable checks, never intent
+    type: principle
+    importance: 10
+    tags: [testing, verification, gate]
+    content: >
+      A change is done when an executable check proves it — test, typecheck,
+      lint, or runtime assertion with a real exit code. "Should work" is not
+      a state; verification is the only truth source. Source: test-driven
+      development lineage (Beck), continuous delivery (Humble/Farley).
+  - title: Fail fast, fail loud
+    type: principle
+    importance: 9
+    tags: [errors, reliability]
+    content: >
+      Surface failure at the earliest possible moment with the fullest
+      possible context. Swallowed errors, silent defaults, and late crashes
+      multiply debugging cost. An error thrown at the boundary with context
+      is cheaper than one discovered downstream. Source: fail-fast design
+      (Fowler), defensive programming practice.
+  - title: The parser is the contract
+    type: principle
+    importance: 8
+    tags: [boundaries, data, robustness]
+    content: >
+      Every untrusted input crosses a parse boundary: validate shape, type,
+      and range at the edge, then trust the parsed value inside. Validating
+      lazily throughout the codebase guarantees gaps. Source: Postel's law
+      critiques, parse-don't-validate (Pingala/Alexis King lineage).
+  - title: Optimize for reading, secondarily for writing
+    type: principle
+    importance: 9
+    tags: [readability, maintenance]
+    content: >
+      Code is read far more often than written. Clear names, small functions,
+      obvious control flow beat cleverness. The cost of writing is paid once;
+      the cost of reading is paid for the code's lifetime. Source: The
+      Elements of Programming Style (Kernighan/Plauger), Clean Code debates.
+  - title: Measure before optimizing
+    type: principle
+    importance: 9
+    tags: [performance]
+    content: >
+      Intuition about hot paths is unreliable; profile first, optimize the
+      measured bottleneck, and re-measure. Premature optimization trades
+      clarity for unproven speed. Keep the simple version until evidence
+      demands otherwise. Source: Knuth's full warning, production profiling
+      practice.
+  - title: Design for the data you have, not the data you wish for
+    type: principle
+    importance: 8
+    tags: [modeling, schema]
+    content: >
+      Schema and model design should reflect observed reality and honest
+      constraints. Speculative generality (unused flags, hypothetical
+      entities) is dead weight; missing constraints are future corruption.
+      Source: YAGNI (XP), data modeling practice.
+  - title: Separation of concerns by responsibility, not by layer worship
+    type: principle
+    importance: 8
+    tags: [architecture, structure]
+    content: >
+      Divide code so each unit has one reason to change (single responsibility)
+      and dependencies point from volatile to stable. Layers are tools, not
+      rituals — an anemic layer structure that passes everything through adds
+      cost without isolation. Source: SOLID (Martin), stable-dependencies
+      principle.
+  - title: Automate the repeated, document the decided
+    type: principle
+    importance: 8
+    tags: [automation, docs, process]
+    content: >
+      Anything done twice by hand becomes a script; anything decided twice
+      becomes a written decision record. Humans are for judgment, machines
+      for repetition. Source: continuous-delivery practice, ADR lineage.
+  - title: Security is a property of the whole pipeline
+    type: principle
+    importance: 9
+    tags: [security]
+    content: >
+      Trust boundaries, least privilege, and secret handling must hold at
+      every layer — dependencies, build, runtime, transport. A strong lock
+      on a door that is never closed is not security. Source: defense in
+      depth, secure-by-default practice.

package/knowledge/git-sdlc.yaml

@@ -0,0 +1,82 @@
+# knowledge/git-sdlc.yaml — version control and software delivery lifecycle knowledge.
+pack: git-sdlc
+description: Git discipline, branching, commit hygiene, code review, and delivery flow
+entries:
+  - title: Commits are the unit of meaning — atomic, described, intentional
+    type: principle
+    importance: 8
+    tags: [git, commits]
+    content: >
+      One logical change per commit, with a message that says WHY (the subject
+      what, the body why). Mixed concerns ("refactor + fix + new feature") are
+      unreviewable and un-bisectable. git bisect only works on a history of
+      meaningful units. Source: git-workflow consensus, bisect practice.
+  - title: Branching serves integration, not isolation theater
+    type: principle
+    importance: 8
+    tags: [git, branching]
+    content: >
+      Long-lived branches accumulate merge debt and integration surprise;
+      trunk-based development with short-lived branches (hours to days) keeps
+      integration continuous. Feature flags decouple deployment from release
+      so incomplete work can integrate safely. Source: trunk-based
+      development, continuous-delivery lineage.
+  - title: Main is always releasable — the gate protects it
+    type: principle
+    importance: 9
+    tags: [git, ci, process]
+    content: >
+      The main branch passes the full verification pipeline at all times;
+      integration happens through gated merges (CI green, review approved).
+      A red main stops the entire team — reverting a broken change beats
+      debugging it in place. Source: continuous-integration canon.
+  - title: Rebase your work, merge the integration, never rewrite shared history
+    type: principle
+    importance: 8
+    tags: [git, history]
+    content: >
+      Local/unpushed commits: rebase for a clean, linear story. Published
+      shared branches: merge (or rebase only with team protocol) — rewriting
+      history others built on destroys their work and trust. Force-push to
+      shared branches is a destructive act gated by review. Source: git
+      workflow documentation, team practice.
+  - title: Code review reviews the change, the reviewer owns nothing
+    type: principle
+    importance: 8
+    tags: [process, review]
+    content: >
+      Review verifies correctness, tests, security, and comprehension by
+      someone other than the author. It is bounded: small diffs get real
+      review, huge diffs get rubber stamps. Authorial intent (what and why in
+      the description) is review input, not archaeology. Blocking comments
+      are about the code, never the person. Source: code-review research
+      (Bacchelli/Bird), Google engineering practice.
+  - title: Semver is a promise — break it explicitly
+    type: principle
+    importance: 8
+    tags: [versioning, release]
+    content: >
+      MAJOR.MINOR.PATCH encodes compatibility: breaking changes bump MAJOR,
+      additive features MINOR, fixes PATCH. Consumers pin ranges accordingly;
+      silent breaking changes in minors destroy downstream trust. Changelogs
+      and deprecation windows make upgrades plannable. Source: semver.org,
+      ecosystem release practice.
+  - title: Definition of done includes the boring guarantees
+    type: principle
+    importance: 8
+    tags: [process, quality]
+    content: >
+      Done means: tests pass, docs updated, observability present (logs/
+      metrics for new behavior), secrets absent, migration reversible,
+      rollback known. "Works on my machine" is the definition of not-done.
+      Source: definition-of-done practice (XP/Scrum lineage).
+  - title: Incidents are learning systems — blameless postmortems
+    type: principle
+    importance: 8
+    tags: [operations, incidents]
+    content: >
+      Postmortems assume everyone acted reasonably with the information they
+      had; the analysis targets systemic causes (missing guardrail, ambiguous
+      dashboard, absent test), not culprits. Every incident yields concrete
+      follow-ups with owners and dates — otherwise it recurs. Source:
+      blameless-postmortem practice (US FAA lineage, Google SRE).