docs: factory integration grill — decision record, ADRs, and chunk scope update

- Decision record covering 12 decisions from the factory integration grill
- ADR-0008 (factory boundary: this repo is a provider, not a factory instance)
- ADR-0009 (flat skill taxonomy with category metadata in frontmatter)
- ADR-0010 (role skills in .agents/skills/; core/agents/ for subagent definitions)
- Issue 0013 (LESSONS.md at repo root)
- Issue 0014 (docs/spec/ living spec layer + VISION.md refactor)
- ROADMAP Chunk 3 scope expanded: skills rebuild, new skills (session-handoff,
  governance-check, git-guardrails, write-adr), IaC/Gitea global optional
- Per-skill process: implementation guidance Sections 4-5 and skills index
  referenced as starting point before web research and grilling
- factory-research-gaps-conflicts.md marked superseded

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/ROADMAP.md

@@ -33,9 +33,9 @@ A parallel workstream (not a numbered chunk) that runs alongside the chunk seque
 |---|---|---|
 | ✅ 1 | Repo skeleton + `install.sh` — structure in place, Claude Code wired up | Nothing else can be built without the structure and install working |
 | ⏳ 2 | Core instructions — `coding.md`, `git.md` (incl. conventional commits), `testing.md`; communication rules in `providers/claude-code/CLAUDE.md` always-on section; retire `global.md`; migrate `docs/` to subdirectory-by-type naming | Instructions are the foundation everything else references; commit convention and doc naming must be in place before history accumulates |
-| ⏳ 3 | First skills — initial slash commands for day-to-day use; changelog tooling (follow-on to Chunk 2 conventional commits); catalogue existing skills incl. `zoom-out` which is installed but undocumented. **Infrastructure complete**: 12 skills deployed to `~/.agents/skills/` via `install.sh`; provider adapter pattern in place; remaining scope is content (changelog tooling, zoom-out docs, content index frontmatter) | Skills are the most immediately useful output; validates the full pipeline |
-| 4 | Workflows — formalize the workstream workflow (kick-off types → grill → artifact → issues → implement → QA → commit); feature, bug, architecture, improvement, feedback patterns | Higher-level patterns built on top of a working skills foundation; grill feedback intake design before starting |
-| 5 | Agents — role definitions (reviewer, architect, developer) | More abstract definitions; benefits from workflow patterns being established first |
+| ⏳ 3 | Skills library rebuild — all 12 existing skills are first-draft placeholders; Chunk 3 rebuilds each from scratch following the full SKILL.md authoring standard (version field, category metadata, constraints section, self-check, failure handling, trigger-test-first discipline). Process per skill: check `docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md` Section 4–5 (framework sourcing) and `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md` (pre-researched trigger descriptions and constraints for 34 target skills) → research/inspect open-source implementations → grill design → implement. New skills: session-handoff (cross-cutting), governance-check (cross-cutting), git-guardrails (cross-cutting), write-adr (factory). IaC skills (global optional, iac category) and Gitea skills (global optional, gitea category) — scope defined in Chunk 3 PRD. **Infrastructure complete**: 12 skills deployed to `~/.agents/skills/` via `install.sh`; provider adapter pattern in place; all existing skills treated as drafts pending rebuild | Skills are the most immediately useful output; the rebuild is necessary because existing skills predate the authoring standard and the factory research |
+| 4 | Workflows — formalize the workstream workflow (kick-off types → grill → artifact → issues → implement → QA → commit); feature, bug, architecture, improvement, feedback patterns. **Prerequisite:** WorkflowContext schema (what each skill in a chain receives and returns) must be designed before any workflow skill is written; `docs/spec/` must exist (implement-feature constraint: update spec in same PR as behavior change) | Higher-level patterns built on top of a working skills foundation; grill feedback intake design before starting |
+| 5 | Agents — role skills (Architect, Developer, Reviewer, Security, QA, Ops) in `.agents/skills/` with `category: roles`; `core/agents/` for provider-agnostic subagent definitions needing isolated execution context (`context: fork`), translated to `.claude/agents/` by adapter; cross-project orchestration agents as use case | Role skills benefit from workflow patterns being established first; subagent definitions require the skills library to be stable |
 | 6 | Sync + project init tooling — `sync.sh` and `init-project.sh` | Tooling only makes sense once there is content worth syncing and scaffolding |
 | 7 | Copilot provider — adapter for GitHub Copilot. **Provider adapter pattern established**: `install.sh` auto-discovers `providers/*/provider-manifest.sh`; Copilot adapter is a new `providers/copilot/provider-manifest.sh` declaring a symlink if needed | Second provider comes after the first is fully proven |
 
@@ -83,14 +83,17 @@ Items consciously not resolved — to be addressed in the relevant chunk PRD or
 | Formal CI gate for `/improve-codebase-architecture` | Chunk 6 grill |
 | Changelog tooling — which generator (git-cliff, conventional-changelog, etc.) and where it runs | Chunk 3 grill |
 | Content index frontmatter — replace inline `when:` hints in CLAUDE.md content index with a `when:` field in each instruction/skill file so the agent discovers load conditions from the file itself. Cover before implementing Chunk 3 skills. | Chunk 3 grill |
+| ~~Skill taxonomy — flat vs nested paths, category organisation~~ | ✅ Resolved — factory integration grill. Flat paths (Claude Code + agentskills.io standard enforce one-level-deep discovery). Categories via `metadata: category:` in SKILL.md frontmatter. See ADR-0009. |
+| ~~Factory boundary — which factory features belong here vs project repos~~ | ✅ Resolved — factory integration grill. This repo is a provider (ADR-0008). LESSONS.md and docs/spec/ are exceptions: added here because this repo also develops itself. IaC and Gitea skills are global optional. Role skills in .agents/skills/; core/agents/ for subagent definitions (ADR-0010). |
+| IaC and Gitea skill scope — which specific skills to include in the global optional set, and in what order | Chunk 3 PRD |
 | Agent behavior confirmation model — writes/edits/git currently require stating intent + approval before acting. Loosen to autonomy-first once skills and workflows are proven and automated agents replace direct interaction. | Phase 2 refinement (post Chunk 4) |
 | ~~CLAUDE.md always-on refinement — security floor (no credentials/auth URLs), scope discipline (no over-engineering), tool preference (Read/Edit over Bash); **plus instruction quality**: current rules are thin one-liners observed in practice to lose to RLHF-trained defaults (verbose responses, validating user positions); fix is specificity, counter-examples, and boundary framing — not accepting violations as expected. Needs its own grill session → PRD before implementation.~~ | ✅ Resolved — Governance workstream Phase 1. `core/instructions/governance.md` loaded via `@import` covers hard prohibitions, data classification, HITL, sycophancy resistance, and deterministic execution preference. Instruction quality principle documented in `CONTEXT.md`. |
 
 ## Housekeeping reminders
 
-- **AI coding factory research** — `docs/research/ai-coding-factory/` contains exploration notes (principles, challenges, implementation guidance, skills index, session log). Gap and conflict analysis complete: `docs/notes/factory-research-gaps-conflicts.md`. Next step: `/grill-me` session with that note as input. Central question to resolve first: *what is the boundary between this global config repo and the factory pattern — which factory features belong here, which belong in project repos?* Once that's settled, the dependent decisions follow (skill taxonomy, LESSONS.md, convention placement). Output: decision record → ADR + updated chunk scope for 2, 3, and 4.
+- **AI coding factory integration** — grill complete. Decision record: `docs/notes/factory-integration-decisions.md`. ADRs: 0008 (factory boundary), 0009 (flat taxonomy), 0010 (role skills vs subagents). Follow-on issues: 0013 (LESSONS.md), 0014 (docs/spec/ + VISION.md refactor). Chunk 3 scope substantially expanded — skills rebuild, new skills, IaC/Gitea skills. See updated chunk table above.
 
-- **`.gitkeep` files** — placeholder files exist in `core/agents/`, `core/workflows/`, `core/prompts/`, `docs/ard/`, `docs/bug/`, `docs/notes/`. Remove each when the first real file is added to that directory. Each `.gitkeep` names the chunk that will populate it.
+- **`.gitkeep` files** — placeholder files exist in `core/agents/`, `core/workflows/`, `core/prompts/`, `docs/ard/`, `docs/bug/`. Remove each when the first real file is added to that directory. Each `.gitkeep` names the chunk that will populate it. (`docs/notes/.gitkeep` already removed — directory has real content.)
 - **Skills pipeline verified** — `install.sh` deploys 12 skills to `~/.agents/skills/` and creates `~/.claude/skills/ → ~/.agents/skills/` symlink adapter. Tested idempotent. `skills-lock.json` removed (was a manual artifact). If `~/.claude/skills/` exists as a real directory on a machine being migrated, remove it manually and re-run install.
 - **Chunk 2 behavioral tests** — 8 manual scenarios in `tests/test-instructions-and-docs.sh` (MANUAL TEST PLAN section) are pending verification. Must run in a fresh Claude session before Chunk 2 is fully verified. See instruction quality finding in `CONTEXT.md` for why these cannot be skipped.
 - **Governance Phase 1 behavioral tests** — manual test plan in `tests/test-governance-layer.sh` (MANUAL TEST PLAN section) is pending verification. Must run in a fresh Claude session before marking governance Phase 1 fully verified.

docs/adr/0008-factory-boundary.md

@@ -0,0 +1,7 @@
+# This repo is a provider of factory tooling, not a factory instance
+
+This repo ships skills, governance, and conventions to project repos — it does not itself adopt the full factory structure (LESSONS.md, docs/spec/, eval infrastructure, references/) as if it were a software project using the factory. Conflating the two layers would mix config-delivery concerns with application concerns, make the repo harder to upgrade (changes to the factory shape would break all consumers simultaneously), and obscure what is a global primitive vs. what is project-specific.
+
+Exception: artefacts also needed while building *this repo itself* are added here in addition to being scaffolded for project repos. LESSONS.md and docs/spec/ qualify — this repo undergoes active development and benefits from the same feedback and spec hygiene it ships to others. This exception is bounded: it applies only when the artefact genuinely serves the repo's own development, not to import the full factory shape by default.
+
+Orchestration agents (cross-project automation) are a natural future extension at Chunk 5, not a reason to change the provider boundary now.

docs/adr/0009-flat-skill-taxonomy.md

@@ -0,0 +1,7 @@
+# Flat skill directories with category metadata, not nested paths
+
+Skills are stored as flat directories directly under `.agents/skills/` (`grill-me/SKILL.md`, not `design/grill-me/SKILL.md`). Category organisation is expressed via `metadata: category:` in each SKILL.md frontmatter rather than directory nesting.
+
+Nested paths were evaluated and rejected for three reasons. First, Claude Code discovers skills exactly one level deep under `~/.claude/skills/` — a skill at `~/.claude/skills/design/grill-me/SKILL.md` is invisible to the tool. Second, the agentskills.io open standard specifies that the `name` field must match the parent directory name, implying a flat structure at the skills root; no nested discovery is defined in the spec. Third, `install.sh` iterates `for skill_dir in .agents/skills/*/` — one level only; nested paths would require a traversal rewrite before a single nested skill could be deployed.
+
+Category metadata achieves the same organisational goals: the Management App can group skills by category, a generated README can cluster them, and the category is machine-readable for tooling — all without path changes, pipeline changes, or deviation from the open standard. If Claude Code adds nested discovery in a future release, paths can be restructured then with evidence rather than speculatively now.

docs/adr/0010-role-skills-vs-subagents.md

@@ -0,0 +1,7 @@
+# Role skills in .agents/skills/, core/agents/ reserved for subagent definitions
+
+Role skills (Architect, Developer, Reviewer, Security, QA, Ops) live in `.agents/skills/` with `category: roles`. They are ordinary skills that activate a cognitive mode in the current conversation — loaded on trigger, follow the standard SKILL.md authoring format, and use the same deployment pipeline as every other skill. Placing them in a separate `core/agents/` directory would require a distinct deployment path, a distinct provider adapter, and a distinct discovery mechanism for no functional gain.
+
+`core/agents/` is reserved for a distinct content type: provider-agnostic subagent definitions that run in isolated execution contexts (`context: fork` in Claude Code terms). These are skills or agents that need a fresh context window, a dedicated system prompt, and no access to the parent conversation history. The Claude Code adapter translates `core/agents/` definitions to `.claude/agents/`. This is structurally different from a role skill that loads inline — the isolation boundary is the defining characteristic, not the cognitive mode.
+
+The factory research conflates these two into a single `roles/` skill category. The distinction matters here because Claude Code's subagent execution model is meaningfully different from skill activation, and the provider adapter pattern requires them to be in separate source locations to translate correctly.

docs/issues/0013-lessons-md.md

@@ -0,0 +1,32 @@
+# 0013 — LESSONS.md for this repo
+
+## What to build
+
+Create `LESSONS.md` at the repo root. This file is the long-loop feedback mechanism for this repo — patterns noticed during active development get written here, and repeated patterns graduate to standing rules.
+
+**File structure:**
+
+```markdown
+# Lessons
+
+Patterns observed during development of this repo. Three or more entries on the same pattern → promote to CONTEXT.md (or the relevant instruction file) as a standing rule.
+
+## [date] [short title]
+[observation — what happened, what was learned, what should change]
+```
+
+**Graduation rule:** When three or more entries cover the same pattern, the human reviews and promotes the pattern to the appropriate standing location: CONTEXT.md for domain-level principles, `core/instructions/coding.md` for coding conventions, `core/instructions/git.md` for git conventions, or `core/instructions/testing.md` for testing conventions. The graduated entries are marked `[graduated → target file]` rather than deleted (audit trail).
+
+**Who writes to it:** The session-handoff skill (Chunk 3) prompts LESSONS.md extraction before closing a session. The human may also write directly.
+
+**What belongs here:** Non-obvious observations — a rule that was misapplied, a pattern that caused friction, a decision that turned out wrong in practice. Not summaries of what was built (that's git history) or planned changes (that's issues).
+
+## Acceptance criteria
+
+- [ ] `LESSONS.md` exists at repo root with the structure above
+- [ ] Graduation rule is documented in the file header
+- [ ] CONTEXT.md docs convention is updated to reference LESSONS.md as an artifact type
+
+## Blocked by
+
+None.

docs/issues/0014-docs-spec.md

@@ -0,0 +1,45 @@
+# 0014 — docs/spec/ and VISION.md refactor
+
+## What to build
+
+Introduce `docs/spec/` as the living spec layer for this repo, and refactor `docs/VISION.md` to goals and intent only.
+
+**The distinction:**
+- `docs/VISION.md` — purpose, goals, non-goals, long-term roadmap. Stable. Describes what the repo is for and where it is going.
+- `docs/spec/overview.md` — current deployed state. What is working today. Updated in the same PR as any behavior change.
+- `docs/spec/architecture.md` — current directory structure, install behavior, provider model, deployment pipeline, as-deployed. Replaces the architecture section of VISION.md.
+
+**1. Refactor VISION.md**
+
+Remove the Architecture section (directory structure diagram, content deployment model, governance layer description, provider model, this repo's own CLAUDE.md description, architectural decisions pointer). These describe current state, not intent. Move this content to `docs/spec/architecture.md`.
+
+Keep in VISION.md: Purpose, Goals, Non-Goals, V1 Definition, Long-term Management Application vision.
+
+**2. Create docs/spec/overview.md**
+
+Current state snapshot: what chunks are complete, what is deployed, what works end-to-end. This is the "what does this repo do right now" document. Updated at the close of each chunk.
+
+**3. Create docs/spec/architecture.md**
+
+Current architecture: directory structure, install pipeline, provider adapter model, content deployment model, governance layer, CLAUDE.md two-tier model. Sourced from the VISION.md architecture section but written as current state, not design intent. Keep diagrams and tables.
+
+**4. Update CONTEXT.md docs convention**
+
+Add `docs/spec/<slug>.md` to the docs naming convention. Describe when spec files are updated (same PR as any behavior change).
+
+**5. Update CLAUDE.md key documents section**
+
+Add `docs/spec/` to the list of documents to read at session start, alongside CONTEXT.md, VISION.md.
+
+## Acceptance criteria
+
+- [ ] `docs/spec/overview.md` exists with current state of the repo
+- [ ] `docs/spec/architecture.md` exists with current architecture content (sourced from VISION.md architecture section)
+- [ ] `docs/VISION.md` contains only Purpose, Goals, Non-Goals, V1 Definition, and Management Application vision
+- [ ] No content is lost — everything from the removed VISION.md sections appears in spec files
+- [ ] CONTEXT.md docs convention references `docs/spec/`
+- [ ] CLAUDE.md key documents section references `docs/spec/`
+
+## Blocked by
+
+None.

docs/notes/factory-integration-decisions.md

@@ -0,0 +1,152 @@
+# Exploration Note: AI Coding Factory Integration — Decision Record
+
+**Date:** 2026-05-17
+**Status:** Decisions locked. Follow-on issues: 0013, 0014. ADRs: 0008, 0009, 0010.
+**Input:** `docs/notes/factory-research-gaps-conflicts.md`, `docs/research/ai-coding-factory/`
+
+---
+
+## Central question resolved
+
+**Is this repo building the factory pattern for others, or is it itself structured as a factory?**
+
+Decision: **Model A — provider.** This repo ships skills, governance, and conventions to project repos. Factory artefacts that are project-specific (LESSONS.md, docs/spec/, references/, evals) belong in project repos, scaffolded by `init-project.sh` (Chunk 6). Exception: artefacts that are also needed while building *this repo itself* are added here too (LESSONS.md, docs/spec/). See ADR-0008.
+
+A future orchestration layer (cross-project automation agents) is a natural Chunk 5 extension — it does not change the provider boundary.
+
+---
+
+## Decisions
+
+### 1. Coding conventions stay in coding.md
+
+CONTEXT.md is for domain vocabulary (≤200 lines, always loaded). `core/instructions/coding.md` carries coding conventions, loaded on demand. The factory's "conventions in CONTEXT.md" principle applies to project repos where CONTEXT.md is the primary shared artefact, not to this provider repo where the CLAUDE.md content index handles selective loading.
+
+Project repos can override with their own `coding.md` at `.claude/core/instructions/coding.md`.
+
+### 2. Flat skill taxonomy with category metadata
+
+Nested skill paths (`design/grill-me/SKILL.md`) are not supported by Claude Code or the agentskills.io standard — both expect skills exactly one level deep under the skills root. See ADR-0009.
+
+Categories are expressed via `metadata: category:` in SKILL.md frontmatter. Defined categories:
+
+| Category | Scope |
+|---|---|
+| `design` | grill-me, grill-with-docs, to-prd, prototype, architecture-review |
+| `plan` | to-issues, triage |
+| `implement` | tdd, diagnose, implement-feature, refactor, write-docs |
+| `test` | write-tests, generate-test-data, review-test-coverage |
+| `review` | improve-codebase-architecture, code-review, security-review, pr-description, changelog-entry |
+| `deploy` | write-ci-pipeline, write-deployment-config, write-ai-review-workflow, deployment-checklist |
+| `operate` | write-runbook, incident-diagnosis, post-mortem, inspect-deployment |
+| `iac` | write-ansible-role, write-terraform-module, write-k8s-manifest, write-docker-compose, proxmox-vm-spec, iac-security-review, write-molecule-test — **global optional** |
+| `gitea` | setup-gitea-mcp, post-pr-review, create-issue — **global optional** |
+| `cross-cutting` | zoom-out, caveman, session-handoff, governance-check, git-guardrails, git-commit-message |
+| `factory` | write-a-skill, write-adr, write-workflow, write-eval, validate-skill, upgrade-skill, write-issue-spec |
+| `roles` | architect, developer, reviewer, security, qa, ops — **Chunk 5** |
+
+### 3. SKILL.md authoring standard (full)
+
+All skills — new and rebuilt — must follow this standard:
+
+**Frontmatter required fields:**
+- `name:` — matches directory name
+- `description:` — trigger-tested before writing the body (explicit, implicit, negative cases)
+- `metadata: category:` — from the category table above
+- `metadata: version:` — semantic version; increment on meaningful changes
+
+**Body required sections:**
+- Constraints (highest-ROI element — prevents overengineering)
+- Self-check at the end (skill-specific correctness criteria)
+- Failure handling
+
+**Process discipline:**
+- Write and validate the description field *before* writing the body
+- Before researching: check `docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md` Section 4 (framework analysis) and Section 5 (framework file mapping) to identify which open-source references apply to this skill and how to combine/adapt them; also check `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md` for pre-researched trigger descriptions and constraints for 34 target skills
+- Research and inspect the identified open-source implementations
+- Grill each skill design before implementing
+
+**Additional:**
+- `allowed-tools:` for production-touching or scoped skills
+- `disable-model-invocation: true` for side-effectful skills (deploy, commit, post)
+- Body ≤500 lines; move reference material to `references/` subdirectory
+
+### 4. Governance file naming unchanged
+
+`core/instructions/governance.md` is kept. The factory's `AGENTS.md` convention applies to project repos with a single root-level governance file. This provider repo uses the on-demand instruction file convention (`coding.md`, `git.md`, `testing.md`, `governance.md`).
+
+### 5. LESSONS.md — two-layer split
+
+- **This repo:** `LESSONS.md` at repo root, created in issue 0013. Captures lessons learned while building the config itself.
+- **Project repos:** `LESSONS.md` scaffolded by `init-project.sh` (Chunk 6 template).
+- **Session-handoff skill:** writes to whichever LESSONS.md is in scope before closing a session.
+- **Graduation threshold:** three or more entries covering the same pattern → promote to CONTEXT.md (or `coding.md`, `git.md`, `testing.md` if domain-specific) as a standing rule.
+
+### 6. Evals consciously deferred to Chunk 6
+
+Evals require a runner to be meaningful. Chunk 3 ships skills without evals; the debt is documented, not hidden. Chunk 6 delivers: eval runner (promptfoo, version-pinned), eval format, backfill of all existing skills, evals-as-acceptance-criteria for future skills.
+
+### 7. docs/spec/ — living spec layer
+
+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.
+
+Project repos: `docs/spec/` scaffolded by `init-project.sh` (Chunk 6 template).
+
+### 8. Skills rebuild in Chunk 3
+
+The 12 existing skills are first-draft placeholders. Chunk 3 rebuilds each from scratch: research open-source references → grill design → implement following the full authoring standard. This is a rebuild, not an extension.
+
+### 9. Role skills in .agents/skills/, core/agents/ for subagents
+
+See ADR-0010. Role skills (Architect, Developer, Reviewer, Security, QA, Ops) are skills with `category: roles` — they load into the main conversation to activate a cognitive mode. `core/agents/` is reserved for provider-agnostic subagent definitions that run in isolated execution contexts (`context: fork`), translated to `.claude/agents/` by the Claude Code adapter.
+
+### 10. Model routing via per-skill frontmatter
+
+The `model:` frontmatter field expresses model routing per skill. Guiding principle (from factory research): match capability to task — do not use frontier models for tasks a smaller model handles adequately.
+
+| Task type | Model tier |
+|---|---|
+| Formatting, classification, commit messages | Lightweight (Haiku) |
+| Most coding and review | Standard (Sonnet) |
+| Adversarial and complex (architecture review, security, incident diagnosis) | Flagship (Opus) |
+
+### 11. IaC and Gitea skills: global optional
+
+IaC skills (category: `iac`) and Gitea integration skills (category: `gitea`) live in this global config repo, installed by default. They are optional — relevant only when the project uses IaC or Gitea. Foundational subset defined in Chunk 3 PRD.
+
+### 12. References directory: project repos only
+
+`references/stack-versions.md` and infrastructure context files belong in project repos. No equivalent needed in this provider repo. Scaffolded by `init-project.sh` (Chunk 6 template).
+
+---
+
+## What is already aligned (not re-litigated)
+
+- `.agents/skills/` as canonical skill path (ADR-0004)
+- SKILL.md format with YAML frontmatter (agentskills.io standard)
+- CONTEXT.md ≤200 lines
+- Pull-based distribution (ADR-0001)
+- governance.md via `@import` always-on
+- No third-party skills without reading them (OWASP AST01 / governance.md)
+- ADRs in `docs/adr/` for hard-to-reverse decisions
+- Conventional commits
+- Progressive disclosure (names at startup, bodies on demand)
+- HITL before irreversible actions
+
+---
+
+## Chunk scope impact
+
+| Chunk | Change |
+|---|---|
+| **2 follow-on** | Add issues 0013 (LESSONS.md) and 0014 (docs/spec/ + VISION.md refactor) |
+| **3** | Scope substantially expanded — see ROADMAP.md |
+| **4** | WorkflowContext schema is a design prerequisite; docs/spec/ must exist before workflows reference it |
+| **5** | Role skills in `.agents/skills/` (category: roles); `core/agents/` for subagent definitions |
+| **6** | Eval runner, backfill, project LESSONS.md template, project docs/spec/ template, references/ template |

docs/notes/factory-research-gaps-conflicts.md

@@ -1,7 +1,7 @@
 # Exploration Note: AI Coding Factory Research — Gaps and Conflicts with Current Roadmap
 
-**Date:** 2026-05-16  
-**Status:** Pre-grill input. Not authoritative — decisions come from the grill session.  
+**Date:** 2026-05-16
+**Status:** Superseded — grill complete. Decisions in `docs/notes/factory-integration-decisions.md`. ADRs: 0008, 0009, 0010. Issues: 0013, 0014.
 **Context:** Before starting Chunk 4 (workflows), the roadmap requires grilling the AI coding factory research against the existing repo. This note identifies where the research diverges from the current vision/roadmap/ADRs to frame that session.
 
 ---