diff --git a/AGENTS.md b/AGENTS.md index 8d531fa..ff4b7a3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,6 @@ Read CONTEXT.md at the start of every session in this repo. Read these on demand: - `docs/VISION.md` — purpose, goals, and long-term Management Application vision -- `docs/spec/overview.md` — current deployed state; what works today - `docs/spec/architecture.md` — current directory structure, install pipeline, provider model - `docs/adr/` — architectural decisions; read before answering design questions or proposing structural changes - `docs/ai-constitution.md` — full governance evidence base; read when a governance decision needs justification diff --git a/CONTEXT.md b/CONTEXT.md index b6fd27a..d474996 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -14,7 +14,7 @@ description: Domain language and decisions for the global AI development config `core/instructions/.md` files are plain markdown — no frontmatter, no schema. The agent decides when to read each file based on task context and the content index label in `providers/claude-code/CLAUDE.md`. Frontmatter is deferred until there is evidence that agents are loading the wrong files in practice. ### Repo/gitea as source of truth -All project state, decisions, context, and working conventions live in this repo or Gitea. External memory systems should not be used for this project — they create a split-brain risk where cached state diverges from the repo. At the start of every session, read `CLAUDE.md`, `CONTEXT.md`, `docs/VISION.md`, and `docs/spec/overview.md`. Everything needed to orient is here. +All project state, decisions, context, and working conventions live in this repo or Gitea. External memory systems should not be used for this project — they create a split-brain risk where cached state diverges from the repo. At the start of every session, read `CLAUDE.md`, `CONTEXT.md`, and `docs/VISION.md`. Everything needed to orient is here. Before answering any design or architecture question, check for existing decisions: `docs/adr/` (hard architectural decisions). diff --git a/core/instructions/governance.md b/core/instructions/governance.md index 890a2c0..721e297 100644 --- a/core/instructions/governance.md +++ b/core/instructions/governance.md @@ -70,7 +70,7 @@ When asked to perform a well-defined, repeatable task — file processing, deplo ## What This File Does Not Govern -Human process decisions are outside agent scope: oversight checkpoints, human approval gates, post-mortems, regulatory notifications, IP licence scanning, and sustainability measurement. These are defined in `docs/ai-constitution.md` and executed by humans following `docs/HUMANS.md`. +Human process decisions are outside agent scope: oversight checkpoints, human approval gates, post-mortems, regulatory notifications, IP licence scanning, and sustainability measurement. These are defined in `docs/ai-constitution.md` and executed by humans following `docs/wiki/HUMANS.md`. The deterministic enforcement layer — pre-commit hooks, CI gates, scanner configuration, audit logging infrastructure, and AI agent permission scoping — is specified in `docs/research/governance_principles/CONTROLS.md` and implemented by humans. Agent instructions alone cannot enforce what deterministic tooling must enforce. diff --git a/docs/notes/factory-integration-decisions.md b/docs/notes/factory-integration-decisions.md index 50f1d05..d88852b 100644 --- a/docs/notes/factory-integration-decisions.md +++ b/docs/notes/factory-integration-decisions.md @@ -92,7 +92,6 @@ Evals require a runner to be meaningful. Chunk 3 ships skills without evals; the Both this repo and project repos get `docs/spec/`. The distinction from VISION.md: - `docs/VISION.md` — goals, intent, long-term roadmap (stable) -- `docs/spec/overview.md` — current deployed state, what works today (updated with each chunk) - `docs/spec/architecture.md` — current directory structure, install behavior, provider model as-deployed VISION.md is refactored in issue 0014 to goals/intent only; architecture content moves to `docs/spec/`. The `implement-feature` skill constraint: update `docs/spec/` in the same PR as any behavior change. diff --git a/docs/notes/factory-research-gaps-conflicts.md b/docs/notes/factory-research-gaps-conflicts.md index 9a61fb5..05f8147 100644 --- a/docs/notes/factory-research-gaps-conflicts.md +++ b/docs/notes/factory-research-gaps-conflicts.md @@ -49,7 +49,7 @@ Factory treats `LESSONS.md` as a required committed file — the mechanism for l ### 3.2 `docs/spec/` living spec layer -Factory requires `docs/spec/overview.md` and `docs/spec/architecture.md` — a spec that is updated in the same PR as any behaviour change. The current docs structure has no equivalent layer; workflow artifacts go in `docs/prd/`, `docs/ard/`, etc. Adding `docs/spec/` is additive (not conflicting), but it changes the docs convention and needs to be decided before Chunk 4 (workflows) defines workflow artifacts. +Factory requires `docs/spec/architecture.md` — a spec that is updated in the same PR as any behaviour change. The current docs structure has no equivalent layer; workflow artifacts go in `docs/prd/`, `docs/ard/`, etc. Adding `docs/spec/` is additive (not conflicting), but it changes the docs convention and needs to be decided before Chunk 4 (workflows) defines workflow artifacts. ### 3.3 Session handoff skill (impacts Chunk 3) diff --git a/docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md b/docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md index 9064a25..417b5f1 100644 --- a/docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md +++ b/docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md @@ -419,7 +419,7 @@ Goal: A working factory skeleton that a real task can be run through end-to-end. 1. Commit `AGENTS.md` — merge existing governance content; validate against principles doc 2. Generate `CONTEXT.md` — manually populate shared vocabulary (10–15 domain terms to start) -3. Create `docs/spec/overview.md` and `docs/spec/architecture.md` — initial living spec, even if sparse +3. Create `docs/spec/architecture.md` — initial living spec, even if sparse 4. Create `docs/adr/` with an `adr-template.md` 5. Implement Phase 1 skill set (7 files): - `roles/architect`, `roles/developer`, `roles/reviewer` diff --git a/docs/spec/architecture.md b/docs/spec/architecture.md index 81a65e8..8fbeb3b 100644 --- a/docs/spec/architecture.md +++ b/docs/spec/architecture.md @@ -1,79 +1,45 @@ # Architecture -Current deployed architecture. Updated in the same PR as any structural change. - ## Layered model ``` this repo (global defaults) - ├── install.sh → ~/.agents/skills/ (canonical skills location) - ├── install.sh → ~/.claude/skills/ (symlink → ~/.agents/skills/, Claude Code adapter) - └── install.sh → ~/.claude/ (Claude Code config + content) + └── scripts/install.sh → ~/.claude/ (Claude Code config + content) project repo (local overrides) └── .claude/settings.json, CLAUDE.md (overrides global) ``` -Projects consume from this repo by pulling updates via `sync.sh` (Chunk 6). Until then, install is a one-time manual step. - -## Directory structure - -``` -ai-development/ -├── AGENTS.md # Provider-agnostic always-on rules for this repo; imported by repo CLAUDE.md -├── CONTEXT.md # Domain language, principles, glossary; auto-loaded at session start -├── docs/ # Workflow artifacts and issues (prd/, ard/, bug/, notes/, adr/, issues/, spec/) + research/ (raw research audit trail) -├── .agents/ # Agent Skills standard location (provider-agnostic) -│ ├── skills/ # SKILL.md files — canonical source, deployed to ~/.agents/skills/ -│ └── evals/ # eval.yaml files for skills not yet in a plugin (cross-cutting/, implement/) -├── .claude-plugin/ # Marketplace manifest (both Claude Code and Copilot CLI read here) -│ └── marketplace.json # Declares all installable plugins in this repo -├── .github/plugin/ -│ └── marketplace.json # Mirror of .claude-plugin/marketplace.json for Copilot CLI canonical path -├── plugins/ # Installable plugin units (each is a self-contained deployable) -│ └── kyberforge/ # Marketplace management toolkit (create-plugin, marketplace-architect, write-skill, write-eval) -├── core/ # Provider-agnostic source of truth -│ ├── AGENTS.md # Global always-on rules (Communication + Behavior); deployed to ~/.agents/AGENTS.md -│ ├── instructions/ # AI behavior definitions (plain markdown) -│ ├── agents/ # Agent role definitions -│ ├── workflows/ # Workflow definitions -│ └── prompts/ # Reusable prompt templates -├── providers/ # Provider-specific adapters -│ ├── claude-code/ # CLAUDE.md (thin adapter), settings.json, provider-manifest.sh -│ └── copilot/ # copilot-instructions.md, hooks, agents adapter -└── scripts/ - ├── deploy-manifest.sh # Source→target mappings; sourced by install.sh and sync.sh - ├── install.sh # Deploys to ~/.agents/skills/, ~/.claude/, etc. - ├── sync.sh # Pulls updates into an existing project - └── init-project.sh # Bootstraps a new or existing project -``` ## Content deployment model -`install.sh` is a **deployer**, not a composer. It does not concatenate content into a single file. Instead: +`scripts/install.sh` is a **deployer**, not a composer. It sources `scripts/deploy-manifest.sh` and deploys three categories: -- `.agents/skills/` → `~/.agents/skills/` — canonical skills location; each skill dir is replaced individually (parent not wiped, user-added skills preserved) -- `core/AGENTS.md` → `~/.agents/AGENTS.md` — global always-on rules (Communication + Behavior); imported by `~/.claude/CLAUDE.md` via `@~/.agents/AGENTS.md` -- Provider adapters declared in `providers/*/provider-manifest.sh` — symlinks from the provider's skill path to `~/.agents/skills/`; e.g. Claude Code gets `~/.claude/skills/ → ~/.agents/skills/` because it reads `~/.claude/skills/` natively. Providers that read `~/.agents/skills/` directly need no adapter. -- `core/` → `~/.claude/core/` — workflows, prompts, agent definitions; agent reads on demand -- `providers/claude-code/settings.json` → `~/.claude/settings.json` -- `providers/claude-code/CLAUDE.md` → `~/.claude/CLAUDE.md` — thin adapter: imports `~/.agents/AGENTS.md` and `governance.md`; no original content +- **Files** (`DEPLOY_FILES`): `providers/claude-code/CLAUDE.md` → `~/.claude/CLAUDE.md`; `providers/claude-code/settings.json` → `~/.claude/settings.json`; `core/AGENTS.md` → `~/.agents/AGENTS.md` +- **Executables** (`DEPLOY_EXECUTABLES`): `providers/claude-code/statusline-command.sh` → `~/.claude/statusline-command.sh` (with `+x`) +- **Directories** (`DEPLOY_DIRS`): `core/` → `~/.claude/core/` (destination fully replaced on each deploy) + +Skills are **not** deployed by `install.sh`. They are distributed as plugins and installed separately via `claude plugin install @holocron`. `~/.claude/CLAUDE.md` is a thin adapter, not a content source. It imports `~/.agents/AGENTS.md` (always-on rules) and `governance.md` (always-on governance), then lists the content index. All always-on content lives in `AGENTS.md` files so other providers can import the same source without duplication. +## Plugin model + +Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`. Each plugin has a `plugin.json` manifest and is installed independently via `claude plugin install`. + ## Governance layer `core/instructions/governance.md` is the always-on governance instruction file. Unlike the on-demand instruction files in the content index, governance.md is loaded into every Claude session via `@import` in `providers/claude-code/CLAUDE.md`. This is a technical guarantee, not a behavioural instruction — `@import` causes Claude Code to expand and load the file at launch, before any interaction begins. The governance layer has two phases: -- **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language. -- **Phase 2** (Chunk 6): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`. +- **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/wiki/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language. +- **Phase 2** (planned): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`. ## AGENTS.md pattern This repo uses two `AGENTS.md` files as the provider-agnostic source of always-on rules (ADR-0012): -- **Repo-level `AGENTS.md`** — instructions for agents working inside this repo (structure, key rules, chunk workflow). Imported by repo `CLAUDE.md` via `@AGENTS.md`. +- **Repo-level `AGENTS.md`** — instructions for agents working inside this repo (structure, key rules). Imported by repo `CLAUDE.md` via `@AGENTS.md`. - **Global `core/AGENTS.md`** — Communication and Behavior rules that apply across all projects. Deployed to `~/.agents/AGENTS.md`; imported by `~/.claude/CLAUDE.md` via `@~/.agents/AGENTS.md`. Both `CLAUDE.md` files are thin adapters: they import from their respective `AGENTS.md` and add only Claude Code-specific syntax (`@import`, content index paths). They carry no original always-on content. @@ -84,8 +50,6 @@ This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for `core/` is never tool-specific. `providers/` is never shared. When adding a new provider, write an adapter in `providers//` that translates core content into the tool's expected format and location. The core content itself does not change. -Skills are the strongest shared primitive — the `SKILL.md` format and [Agent Skills open standard](https://agentskills.io) are cross-provider. Providers that don't read `~/.agents/skills/` natively declare a symlink adapter in `providers//provider-manifest.sh`; `install.sh` discovers and wires these up automatically. - ## Architectural decisions Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. See the index there for rationale on choices like the pull distribution model, copy-not-symlink coupling, and the two-tier CLAUDE.md structure. diff --git a/docs/spec/overview.md b/docs/spec/overview.md deleted file mode 100644 index 1495d8c..0000000 --- a/docs/spec/overview.md +++ /dev/null @@ -1,69 +0,0 @@ -# Overview - -Current deployed state of this repo — what you get if you run `install.sh` today. Updated at the close of each chunk and in the same PR as any behavior change. - -*Last updated: 2026-06-27 (kyberforge plugin — agent-author skill)* - -## What is deployed - -### Plugins -1 plugin registered in the marketplace (`holocron` marketplace, `.claude-plugin/marketplace.json`): - -- **`kyberforge`** — marketplace management toolkit and skill/agent factory. Contains `skill-author` (create/improve SKILL.md files), `skill-audit` (validate skills against agentskills.io spec), and `agent-author` (create/improve Claude Code + Copilot CLI agent definition files at plugin, project, or user scope) skills. Install: `claude plugin install kyberforge@holocron`. Source: `plugins/kyberforge/`. Research doc: `plugins/kyberforge/docs/plugin-marketplace-architecture.md`. - -### Skills -13 skills deployed directly to `~/.agents/skills/` via `install.sh`. Available as slash commands in Claude Code via `~/.claude/skills/ → ~/.agents/skills/` symlink. Factory and marketplace skills (`write-eval`, `write-skill`, `create-plugin`, `marketplace-architect`) have moved to the `kyberforge` plugin and are only available after plugin install. - -**Factory bootstrap (now in kyberforge plugin):** -- `write-eval` — produces `eval.yaml` test files for skills. Hand-written (bootstrap). Eval at `plugins/kyberforge/tests/evals/write-eval/eval.yaml`. -- `write-skill` — authors new SKILL.md files and converts placeholders to canonical format. Hand-written (bootstrap). Eval at `plugins/kyberforge/tests/evals/write-skill/eval.yaml`. Invokes `write-eval` as part of its own process. -- `write-docs` — produces technical documentation derived from code and spec; never invents behaviour. **First factory-authored skill** (SKILL.md produced via `write-skill`, eval via `write-eval`). Eval at `.agents/evals/implement/write-docs/eval.yaml`. Sources: anthropics/skills `doc-coauthoring`, mattpocock/skills `write-a-skill`, bmad-code-org/BMAD-METHOD `bmad-advanced-elicitation`. - -Current skills (direct): `caveman`, `diagnose`, `gitleaks`, `grill-me`, `grill-with-docs`, `improve-codebase-architecture`, `prototype`, `tdd`, `to-issues`, `to-prd`, `triage`, `write-docs`, `zoom-out`. - -**Chunk 3 target:** 42 skills across 9 categories. PRD: `docs/prd/chunk-3-skills-library.md`. Canonical build reference: `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md` (delete once all skills exist). Skills stored flat (`skill-name/SKILL.md`) per ADR-0009; category in `metadata.category` frontmatter. Categories: design, factory, implement, test, review, deploy, operate, cross-cutting, iac (2 skills only — docker-compose + iac-security-review). Role skills (6) deferred to Chunk 5. Gitea skills moved to `providers/gitea/` provider adapter. - -**Skill implementation workflow:** each skill follows the per-skill process in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016). Sub-agents handle source discovery, source review, and conflict checking; synthesis grill and HITL test are human steps. Bootstrap: write-eval (hand-written) → write-skill (hand-written) → write-docs (first factory-authored) → all others via factory. - -### Claude Code configuration -- `~/.claude/CLAUDE.md` — thin adapter; imports `~/.agents/AGENTS.md` (Communication + Behavior) and `governance.md`; content index pointers only -- `~/.agents/AGENTS.md` — global always-on rules (Communication + Behavior); provider-agnostic source of truth -- `~/.claude/core/instructions/` — coding, git, testing, governance instruction files -- `~/.claude/settings.json` — Claude Code settings - -### Governance layer -`core/instructions/governance.md` loads into every Claude Code session via `@import` in `~/.claude/CLAUDE.md`. Covers: hard prohibitions on secrets and data, data classification tiers, HITL requirements, sycophancy resistance, deterministic execution preference. - -## What works end-to-end - -- `install.sh` runs idempotently — safe to re-run after changes -- Provider adapter pattern: `providers/*/provider-manifest.sh` auto-discovered by `install.sh` -- Governance rules take effect at session start without any manual loading step -- Skills available as slash commands immediately after install - -## What is not yet deployed - -- `sync.sh` — pulls updates into existing projects (Chunk 6) -- `init-project.sh` — bootstraps a new project (Chunk 6) -- Copilot provider adapter (Chunk 7) -- Formal CI/pre-commit enforcement of governance rules (Chunk 6) -- `init-project.sh` scaffolding (Chunk 6) — will seed `.pre-commit-config.yaml` for new projects - -## Recent changes - -- 2026-06-27 — `agent-author` skill added to kyberforge plugin. Creates and improves agent definition files for both Claude Code (`.md`) and GitHub Copilot CLI (`.agent.md`) from a single root directory input via `new-agent.sh`. Supports plugin, project, and user scope — scope auto-detected from root (`plugin.json` presence). File-by-file no-op scaffold; routing on file existence (neither → create, any exists → improve). `agents/sources.md` for provenance at plugin scope. No companion `agent-audit` skill (deferred, tracked in issue #11). ADR-0015 documents the dual-provider single-root scaffold decision. - -- 2026-06-20 — kyberforge plugin created and registered in `holocron` marketplace. Consolidates `create-plugin`, `marketplace-architect`, `write-skill`, and `write-eval` skills (previously in `.agents/skills/`) plus their evals, bundled scripts, references, and the plugin-marketplace-architecture research doc into a single installable plugin at `plugins/kyberforge/`. Plugin template (`templates/plugin/`) bundled into `plugins/kyberforge/skills/create-plugin/assets/plugin-template/` and removed from repo root. Evals moved from `.agents/evals/marketplace/` and `.agents/evals/factory/write-eval/` into `plugins/kyberforge/tests/evals/`. These four skills are no longer available as standalone slash commands — install the plugin to use them. - -- 2026-06-20 — Gitleaks secret scanning added via pre-commit framework. `.gitleaks.toml` in repo root is the base config extending gitleaks defaults and adds path allowlist for `docs/research/` (high-entropy terminal captures). `gitleaks` skill added (`cross-cutting`) covering full lifecycle: install, update, tune allowlist, scan modes, resolve real findings. Supports both modern repos (pre-commit-based) and legacy repos (shell hook-based setup). Key lesson: v8.24.2 uses `[allowlist]` (singular); v8.25.0+ uses `[[allowlists]]` — wrong syntax silently does nothing. - -- 2026-05-18 — Issue 0018 phase 1 refactor complete: `write-skill` redesigned from scratch. New files added to skill directory: `SKILL-TEMPLATE.md` (authoritative 6-section template with XML blocks, human-usable), `META-TEMPLATE.md` (provenance schema with inline-commented YAML), `CATEGORIES.md` (self-contained category table), `META.md` (write-skill's own provenance). SKILL.md rewritten: 6 sections replacing 8 (Role and When/When not dropped — not in agentskills.io spec); frontmatter reduced to 3 fields (`name`, `description`, `metadata.category`); provenance fields (`version`, `updated`, `when`, `source`, `references`) moved to META.md (progressive disclosure — not loaded at startup). `docs/notes/skill-implementation-workflow.md` updated to reference SKILL-TEMPLATE.md as the authoritative template. - -- 2026-05-17 — Issue 0018 phase 2 complete: `write-docs` skill written and deployed. First skill produced end-to-end by the factory (SKILL.md via `write-skill`, eval via `write-eval`). Category: implement. Key decisions: file-approval gate before reading (user names files or approves proposals); gap check before drafting (user fills what code doesn't explain); stage skipping allowed with logged reason; full revised section shown before confirmation gate; surgical edits only with per-round delta summary; Reader Testing via scoped sub-agent (doc + questions only, no source files); summary/overview sections written last. Sources: anthropics/skills doc-coauthoring (Reader Testing stage, surgical-edit constraint), mattpocock/skills write-a-skill (trigger pattern), bmad-code-org/BMAD-METHOD bmad-advanced-elicitation (confirmation gate). Open follow-up: documentation convention (file/folder/content structure, global vs repo-specific) — not yet defined. -- 2026-05-17 — Issue 0018 phase 1 complete: `write-skill` bootstrap skill written and deployed. Hand-written (factory bootstrap). Self-authored — no upstream content adopted; agentskills.io best-practices and optimizing-descriptions docs cited as references. Speckit excluded (AGPL-3.0). Key decisions: new-skill + placeholder-conversion scope only (upgrades → `upgrade-skill`); trigger description tested against 3 cases before body written; `write-eval` invoked as step 7 in process; HITL prompt as step 8. Eval at `.agents/evals/factory/write-skill/eval.yaml`. -- 2026-05-17 — Issue 0017 complete: `write-eval` bootstrap skill written and deployed. Two sections schema (`trigger_tests` + `output_tests`), provider-agnostic string assertions, show-plan-then-merge-on-rerun behaviour, conflict flagging (B model). Sources: agentskills/agentskills, darkrishabh/agent-skills-eval, bmad-code-org/BMAD-METHOD, mattpocock/skills. Hand-written eval at `.agents/evals/factory/write-eval/eval.yaml`. -- 2026-05-17 — Issue 0016 complete: skill implementation workflow grill completed. `docs/notes/skill-implementation-workflow.md` written. All issues 0017–0028 updated with specific acceptance criteria. Key conventions: sub-agents prescribed at each research/writing step; conflict check against constitution + factory principles before synthesis grill; `when:` and `references:` fields added to authoring standard; write-docs moved to issue 0018 phase 2 (first factory-authored skill). -- 2026-05-17 — Issue 0015 complete: AGENTS.md refactor implemented. Two AGENTS.md files created (`AGENTS.md` at repo root, `core/AGENTS.md` deployed to `~/.agents/AGENTS.md`). Both CLAUDE.md files slimmed to thin adapters. `deploy-manifest.sh` updated. `docs/spec/architecture.md` updated with new structure. ADR-0012 in effect. -- 2026-05-17 — Chunk 3 issues created (0015–0028): AGENTS.md refactor prerequisite, skill workflow grill, bootstrap skills (write-eval, write-skill), factory/design/implement/test/review/deploy/operate/IaC/cross-cutting skill groups, chunk closure; all HITL; acceptance criteria for 0017–0028 to be refined after issue 0016 grill session -- 2026-05-17 — behavioral tests fully resolved: `CONTEXT.md` now always-loaded via `@import` in repo `CLAUDE.md`; standing rule added to check `docs/adr/` before answering design questions; communication/behavior and secrets rules tightened; Chunk 2 and Governance Phase 1 ✅ complete -- 2026-05-17 — added `LESSONS.md` (issue 0013) and `docs/spec/` (issue 0014); refactored `docs/VISION.md` to goals/intent only