Files

2026-06-22 21:42:30 +02:00

13 KiB

Raw Permalink Blame History

domain, repo, updated

domain	repo	updated
infotech	snuggles-inventor	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:

Ingest the codebase into a living technical specification
Plan via an Agent Action Plan (AAP) or equivalent with human review
Generate in isolated environments with secrets kept out of model context
Validate build and tests before merge
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:

What codebase are we changing? Ingestion, tech spec, dependency map.
What should be built? Prompts, rules, AAP / plan documents, human approval.
How is code produced? Multi-step generation, specialized agents, compile/runtime checks.
Where does generation run? By requesting sand-boxer build profiles — not by provisioning hosts.
Does it work? By invoking wise-validator (or delegating to CI) — not by owning e2e framework.
How does it land? PR creation, review workflow, merge/close/refine decisions.
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.

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:

# Conceptual CLI (v0)
invent ingest --repo <url|path>
invent plan --job <id>          # AAP / plan generation + human review gate
invent generate --job <id>      # runs in sand-boxer-backed env
invent validate --job <id>      # delegates to wise-validator
invent publish --job <id>       # open or update PR
invent status --job <id>

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:

Resolve environment template (job-level or org base + override)
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 }
Run generation/build steps inside sandbox via glas-harness or invent worker
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:

invent validate --job <id> invokes wise-validator with repo ref at job branch
wise-validator requests its own sand-boxer profile (profile.compose-e2e) if needed
snuggles-inventor records pass/fail as job gate; does not parse e2e.yml itself

Near-term outcomes (preliminary)

This charter — INTENT.md aligned with Coulomb sibling boundaries
Job schema sketch — phases, artifacts, approval gates
sand-boxer integration doc — build profile + setup metadata contract
Minimal ingest + plan stub — read repo, emit draft tech spec outline
Forge extension stub — branch + PR against Gitea remote
Registry entry — e.g. capability.invention.codegen
State Hub job events — phase transitions and PR links
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.

13 KiB Raw Permalink Blame History