From 58a7ef4a68026e07827579b520f31224b94d0768 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 22 Jun 2026 21:42:30 +0200 Subject: [PATCH] Seeded intent --- INTENT.md | 347 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 347 insertions(+) create mode 100644 INTENT.md diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..76c0c82 --- /dev/null +++ b/INTENT.md @@ -0,0 +1,347 @@ +--- +domain: infotech +repo: snuggles-inventor +updated: "2026-06-22" +--- + +# INTENT + +> snuggles-inventor is the Coulomb **meta-framework for structured code +> generation and evolution** — ingestion, planning artifacts, multi-agent +> generation, human-in-the-loop review, and PR-oriented output — while +> **consuming** sand-boxer for build environments and wise-validator for proof. +> This file is preliminary; refine as the invention boundary is implemented. + +**Naming note:** Sibling docs in `sand-boxer` and `glas-harness` refer to this +project as `snuggle-inventor` (singular). This repository slug is +`snuggles-inventor`; align naming across repos in a future consistency pass. + +--- + +## Why it exists + +Custodian domains need large, structured code changes — features, refactors, +modernization, security fixes — without every team operating a bespoke codegen +pipeline, prompt playbook, and review workflow. + +Commercial platforms (notably **Blitzy**) demonstrate a durable pattern: + +1. **Ingest** the codebase into a living technical specification +2. **Plan** via an Agent Action Plan (AAP) or equivalent with human review +3. **Generate** in isolated environments with secrets kept out of model context +4. **Validate** build and tests before merge +5. **Ship** as a pull request with human gates at every critical step + +That pattern bundles **invention concerns** (spec, generation, PR) with +**runtime concerns** (sandboxes, tests, agent sessions) when implemented as a +monolith. Coulomb splits the stack: + +| Layer | Owner | +|-------|--------| +| **Code generation and evolution** | **snuggles-inventor** | +| **Sandbox establishment** | **sand-boxer** | +| **E2e and health validation** | **wise-validator** | +| **Agent harness** | **glas-harness** | + +snuggles-inventor exists to be the invention layer: **one consistent way to +generate and evolve code** with extensions for ingestors, planners, generators, +and forge integrations — environments from sand-boxer, proof from +wise-validator, optional agent UX from glas-harness. + +sand-boxer establishes where work runs. snuggles-inventor **invents what to merge.** + +--- + +## The governing principle + +snuggles-inventor is the **code generation and evolution service** — repository +understanding, planning artifacts, generation orchestration, review gates, and +PR emission. Nothing more. + +It answers: + +1. **What codebase are we changing?** Ingestion, tech spec, dependency map. +2. **What should be built?** Prompts, rules, AAP / plan documents, human approval. +3. **How is code produced?** Multi-step generation, specialized agents, compile/runtime checks. +4. **Where does generation run?** By requesting sand-boxer build profiles — not by provisioning hosts. +5. **Does it work?** By invoking wise-validator (or delegating to CI) — not by owning e2e framework. +6. **How does it land?** PR creation, review workflow, merge/close/refine decisions. +7. **What happened?** Job lifecycle and audit events to State Hub. + +It must **not** become the sandbox provisioner, the validation orchestrator, the +agent gateway, the scheduler, work-state authority, tunnel/CA owner, or +production deployer on Railiance01. + +--- + +## Coulomb sibling boundaries + +### sand-boxer — sandbox establishment + +**sand-boxer owns:** Profiles, extensions, provision/teardown, placement, secret +resolution at the provision boundary. + +**snuggles-inventor owns:** Attaching **setup metadata** (Blitzy-style natural- +language build instructions, `secret_refs`, variable names) as inputs when +requesting a build sandbox. Generated source never transits sand-boxer APIs. + +```text +snuggles-inventor sand-boxer +─────────────── ────────── +job needs build env → POST /v1/sandboxes + profile: profile.build (or similar) + setup: { instructions, secret_refs } +agents run in sandbox via harness ← sandbox_id + reachability +destroy when job completes → DELETE /v1/sandboxes/{id} +``` + +### wise-validator — e2e test and health + +**wise-validator owns:** `e2e.yml` contracts, health polling, test commands, +pass/fail reporting. + +**snuggles-inventor owns:** **Triggering** validation after generation (job step), +interpreting pass/fail as a **merge gate** — not reimplementing health-wait or +test runners. + +Typical job DAG: `generate → build in sandbox → wise-validator.run → open PR`. + +### glas-harness — agent harness + +**glas-harness owns:** Agent sessions, tools, memory, channels. + +**snuggles-inventor does not** replace the harness. Long-running codegen may use +glas-harness for operator chat UX; snuggles-inventor owns the **job model**, +artifacts (spec, AAP, PR), and generation pipeline either way. + +### Boundary diagram + +``` + Human reviewer / glas-harness (optional UX) + │ + ▼ + snuggles-inventor + (invent + evolve) + │ + ┌─────────────┼─────────────┐ + ▼ ▼ ▼ + sand-boxer wise-validator forge (Gitea/GitHub) + (build env) (prove) (PR) +``` + +### Existing Custodian repos + +| Concern | Owner | +|---------|--------| +| Workstream, task, progress state | `state-hub` | +| Cron and orchestration | `activity-core` | +| SSH reverse tunnels | `ops-bridge` | +| SSH certificate issuance | `ops-warden` | +| Canon and agent instruction canon | `the-custodian` | +| Capability federation hub | `reuse-surface` | +| LLM inference routing | `llm-connect` | +| Agent runtime | **glas-harness** | +| Production on Railiance01 | `railiance-apps` / domain repos | + +snuggles-inventor **consumes** sand-boxer, wise-validator, llm-connect, and forge +integrations; it does not subsume them. + +--- + +## What it is + +snuggles-inventor is a **meta-framework** with four pillars (preliminary): + +### 1. Unified invention API + +One surface for codegen jobs: + +```bash +# Conceptual CLI (v0) +invent ingest --repo +invent plan --job # AAP / plan generation + human review gate +invent generate --job # runs in sand-boxer-backed env +invent validate --job # delegates to wise-validator +invent publish --job # open or update PR +invent status --job +``` + +**HTTP:** `POST /v1/jobs`, `GET /v1/jobs/{id}`, phase transitions with explicit +human approval endpoints where required. + +Consumers: human operators (`adm`), activity-core workflows (`atm`), glas-harness +agent tools (`agt`). + +### 2. Job lifecycle and artifacts + +Structured phases (Blitzy-aligned, Coulomb-owned): + +| Phase | Artifact | Human gate | +|-------|----------|------------| +| Ingestion | Codebase map, dependency graph | Optional | +| Tech spec | Living spec document | Review recommended | +| Plan | AAP / implementation plan | **Required** before generate | +| Generate | Branch, diff, build log | Review before publish | +| Validate | wise-validator result | Required for auto-publish policies | +| Publish | Pull request | **Required** before merge | + +Job state is snuggles-inventor authority; workstream/task linkage is State Hub. + +### 3. Extension platform + +Extensions delegate invention mechanics: + +| Extension class | Examples | +|-----------------|----------| +| **Ingestor** | Git checkout, monorepo scan, submodule-aware ingest | +| **Spec builder** | Tech spec templates, architecture diagrams, API contracts | +| **Planner** | AAP generator, rule-aware plan refinement | +| **Generator** | Multi-agent codegen, language-specific workers | +| **Forge** | Gitea, GitHub, GitLab PR and branch operations | +| **Policy** | Org rules (style, security, test coverage requirements) | + +Extensions call **llm-connect** for inference; they do not embed provider SDKs +as the only path. + +### 4. Environment and secret model (Blitzy-derived) + +Generation jobs declare **environment intent**, sand-boxer fulfills **runtime**: + +| Concept | Owner | +|---------|--------| +| Natural-language setup instructions | snuggles-inventor job config | +| `${VAR}` names in instructions | snuggles-inventor | +| Secret values | Resolved by sand-boxer / platform secret store — **never in LLM prompts** | +| UI login credentials for auth-gated apps | Secret refs for validation steps | + +Variables (non-sensitive) may appear in specs; secrets are referenced by name only. + +--- + +## What it is not + +| Concern | Owner | +|---------|--------| +| Sandbox provision, host SSH, compose lifecycle | **sand-boxer** | +| E2e tests, health checks, `e2e.yml` | **wise-validator** | +| Agent gateway, session tools, channels | **glas-harness** | +| When jobs are scheduled | `activity-core` | +| Task/workstream canonical state | `state-hub` | +| Model routing and API keys | `llm-connect` | +| General issue tracking | `issue-core` | + +snuggles-inventor produces **code change proposals**. It does not operate +production services or replace domain repo ownership. + +--- + +## Lineage and research inputs + +### Blitzy (primary commercial reference) + +Patterns to adopt (platform docs: https://docs.blitzy.com/): + +- Human-in-the-loop at plan, guide, and PR review stages +- Tech spec as foundation kept in sync with the repo +- Environment configuration separate from codegen logic +- Secrets encrypted and masked; never sent to AI models +- Multi-environment merge (base + project override) +- Validation signals before merge (build, tests, optional Computer Use) +- Prompt templates and golden rules as registered policy extensions + +**Blitzy Sandbox** (GitHub org) is demo content — not runtime infrastructure. +snuggles-inventor is not a Blitzy clone; it is Coulomb's **self-hosted invention +meta-framework** with the same separation discipline as sand-boxer. + +### sand-boxer research + +`sand-boxer/research/02-reference-frameworks.md` — Blitzy environment metadata +maps to sand-boxer profile `setup` blocks; snuggles-inventor supplies the text, +sand-boxer supplies the box. + +### Coulomb forge + +PR and branch operations integrate with org forge (Gitea remote, GitHub, etc.) via +forge extensions — not via sand-boxer. + +--- + +## Intended users + +- **Human operators (`adm`)** — approve plans, review PRs, configure environments +- **Engineering leads** — delegate large refactors without losing review gates +- **Deterministic automations (`atm`)** — activity-core triggered modernization jobs +- **LLM agents (`agt`)** — via glas-harness tools that start/snippet invent jobs +- **Domain repos** — targets of ingestion; do not embed codegen infrastructure +- **Extension authors** — ingestors, planners, forge adapters + +--- + +## Design principles + +- **Invention meta-framework, not monolith** — one job API; extensions per phase +- **Human gates by default** — no silent merge of large generated diffs +- **sand-boxer for environments** — never embed provisioners in invent pipeline +- **wise-validator for proof** — declarative validation, not inlined pytest hacks +- **Secrets never in prompts** — reference names only; Blitzy discipline +- **Spec before code** — tech spec and approved plan precede generation +- **PR-oriented output** — branches and PRs, not direct pushes to protected branches +- **Observable jobs** — every phase transition attributable (`adm` / `agt` / `atm`) +- **Registry-first reuse** — register invention capabilities in `registry/` +- **Evolution, not one-shot** — support refine, regenerate, and incremental jobs + +--- + +## sand-boxer consumption contract (preliminary) + +When a generation job needs a build environment: + +1. Resolve environment template (job-level or org base + override) +2. Call sand-boxer `create` with: + - `profile: profile.build` (or `profile.agent-dev`) + - `inputs.setup.instructions` — natural-language bootstrap text + - `inputs.setup.secret_refs` — names only + - `consumer: { harness: snuggles-inventor, actor: agt|atm, job_id }` +3. Run generation/build steps inside sandbox via glas-harness or invent worker +4. On job end or failure: sand-boxer `destroy` per job cleanup policy + +Generated file contents flow through git/PR APIs — never through sand-boxer. + +--- + +## wise-validator consumption contract (preliminary) + +After generation, when validation is required: + +1. `invent validate --job ` invokes wise-validator with repo ref at job branch +2. wise-validator requests its own sand-boxer profile (`profile.compose-e2e`) if needed +3. snuggles-inventor records pass/fail as job gate; does not parse `e2e.yml` itself + +--- + +## Near-term outcomes (preliminary) + +1. **This charter** — `INTENT.md` aligned with Coulomb sibling boundaries +2. **Job schema sketch** — phases, artifacts, approval gates +3. **sand-boxer integration doc** — build profile + setup metadata contract +4. **Minimal ingest + plan stub** — read repo, emit draft tech spec outline +5. **Forge extension stub** — branch + PR against Gitea remote +6. **Registry entry** — e.g. `capability.invention.codegen` +7. **State Hub job events** — phase transitions and PR links +8. **Policy extension hook** — org rules file format (successor to Blitzy rules) + +--- + +## Maturity target + +A mature snuggles-inventor is Coulomb's **default structured codegen path**: + +- Large refactors start with ingestion and spec, not ad hoc agent sessions +- Every generate phase runs in sand-boxer-backed environments with secret hygiene +- wise-validator gates merge for repos with `e2e/` contracts +- Humans approve plans and PRs; automations never bypass both gates silently +- glas-harness can drive jobs conversationally without owning the pipeline +- Domain repos stay thin — `INTENT.md`, code, tests — not embedded invent infra + +sand-boxer establishes the box. glas-harness runs the agent. wise-validator +proves it works. **snuggles-inventor invents what ships.** \ No newline at end of file