constructorfabric · ainetx · Jun 20, 2026 · Jun 19, 2026 · Jun 19, 2026 · Jun 19, 2026
diff --git a/README.md b/README.md
@@ -67,7 +67,7 @@ When `cfs init` offers to install the Software Development Life Cycle (SDLC) kit
 cfs generate-agents
 ```
 
-`cfs init` creates the repository-local Studio setup directory, normally `.cf-studio/`. The repository footprint is intentionally small: generated Studio runtime files, the local `cfs` support files, and generated AI coding tool agent configuration files are gitignored by default. `cfs generate-agents` writes those tool integration files when needed, and they can be repaired or regenerated. Project configuration and any kit content you choose to track are the parts your organization reviews and evolves.
+`cfs init` creates the repository-local Studio setup directory, normally `.cf-studio/`. The repository footprint is intentionally small: generated Studio runtime files, the local `cfs` support files, and generated AI coding tool agent configuration files are gitignored by default. `cfs generate-agents` writes or refreshes those tool integration files when needed, and they can be repaired or regenerated. Project configuration, project rules under `config/rules/`, and any kit content you choose to track are the parts your organization reviews and evolves.
 
 If a repository already contains Constructor Studio setup files, you can usually skip the install and initialization steps. Open that repository in your AI coding tool and activate Studio in chat:
 

diff --git a/architecture/DESIGN.md b/architecture/DESIGN.md
@@ -460,7 +460,7 @@ Validation rules cannot be bypassed or weakened in STRICT mode. The deterministi
 - **Identifiers & Traceability**: [traceability.md](./specs/traceability.md) — ID formats, naming conventions, task markers, code traceability markers, validation
 - **CDSL**: [CDSL.md](./specs/CDSL.md) — behavioral specification language syntax
 - **Artifacts registry**: [artifacts-registry.md](./specs/artifacts-registry.md) — artifacts.toml structure and agent operations
-- **System prompts**: [sysprompts.md](./specs/sysprompts.md) — `{cf-studio-path}/config/sysprompts/` and `config/AGENTS.md` format
+- **Project rules and root navigation**: [sysprompts.md](./specs/sysprompts.md) — `{cf-studio-path}/config/rules/`, `config/AGENTS.md`, and root managed block format
 - **Workspace**: core architecture in [DESIGN.md §1.2](#multi-repo-workspace-federation); implementation details in [features/workspace.md](./features/workspace.md) — workspace config, source resolution, algorithms (`resolve-git-url`, `resolve-adapter-context`, `determine-target`, `infer-role`)
 
 **Core Entities**:
@@ -986,9 +986,9 @@ sequenceDiagram
     end
 ```
 
-**Description**: User initializes Studio in a project. The skill engine asks for install directory, agent selection, and kit tracking policy. It defines a **root system** (name and slug derived from the project directory name), creates core configs (`core.toml` with root system, pinned Studio metadata, and kit tracking policy; `artifacts.toml` with default autodetect rules), writes the managed `.gitignore` block, generates agent entry points, and sets up `{cf-studio-path}/config/AGENTS.md` with default WHEN rules. After core setup, the tool prompts `Install SDLC kit? [a]ccept [d]ecline`. If accepted, the kit is downloaded from GitHub. If the kit source contains canonical `.cf-studio-kit.toml` or legacy `manifest.toml`, the Kit Manager normalizes and validates the model, reads declared resources, prompts the user for destination paths or copy/register mode when required, copies or registers each resource, preserves template variables in kit files, and records effective install state in `core.toml` for runtime resolution. If no manifest-style input is present, files are copied to the default kit config directory. If declined, the user can install kits later via `cfs kit install`. Repeat `cfs init` repairs generated surfaces using the pinned metadata and does not upgrade implicitly.
+**Description**: User initializes Studio in a project. The skill engine asks for install directory, agent selection, and kit tracking policy. It defines a **root system** (name and slug derived from the project directory name), creates core configs (`core.toml` with root system, pinned Studio metadata, and kit tracking policy; `artifacts.toml` with default autodetect rules), writes the managed `.gitignore` block, generates agent entry points, and sets up `{cf-studio-path}/config/AGENTS.md` with project navigation rules that point at `{cf-studio-path}/config/rules/*.md` and selected project docs. After core setup, the tool may offer default kit installation. If a kit is accepted, it is downloaded or copied from the selected source. If the kit source contains canonical `.cf-studio-kit.toml` or legacy `manifest.toml`, the Kit Manager normalizes and validates the model, reads declared resources, prompts the user for destination paths or copy/register mode when required, copies or registers each resource, preserves template variables in kit files, and records effective install state in `core.toml` for runtime resolution. If no manifest-style input is present, files are copied to the default kit config directory. Repeat `cfs init` repairs generated surfaces using the pinned metadata and does not upgrade implicitly.
 
-**Root AGENTS.md / CLAUDE.md injection**: During initialization (and verified on every CLI invocation), the engine ensures the project root `AGENTS.md` and `CLAUDE.md` files contain the same managed block with only the configured adapter path:
+**Root AGENTS.md / CLAUDE.md injection**: During initialization and other explicit setup or repair flows, the engine ensures the project root `AGENTS.md` and `CLAUDE.md` files contain the same managed block with only the configured adapter path:
 
 ````markdown
 <!-- @cf:root-agents -->
@@ -998,9 +998,9 @@ cf-studio-path = ".bootstrap"
 <!-- /@cf:root-agents -->
 ````
 
-The block is inserted at the **beginning** of each file. If a file does not exist, it is created. The managed content is a TOML fence that declares only `cf-studio-path`, and the path reflects the actual install directory. Content between the `<!-- @cf:root-agents -->` and `<!-- /@cf:root-agents -->` comment markers is fully managed by Studio — it is overwritten on every check, so manual edits inside the block are discarded.
+The block is inserted at the **beginning** of each file. If a file does not exist, it is created. The managed content is a TOML fence that declares only `cf-studio-path`, and the path reflects the actual install directory. Content between the `<!-- @cf:root-agents -->` and `<!-- /@cf:root-agents -->` comment markers is fully managed by Studio, so manual edits inside the block are discarded when a setup or repair flow rewrites it.
 
-**Integrity invariant**: every Studio CLI command (not just `init`) verifies the root `AGENTS.md` and `CLAUDE.md` blocks exist and are correct before proceeding. If a block is missing or the path is stale (e.g., install directory changed), the engine silently re-injects it. This guarantees that root agent files always expose the current `cf-studio-path` without duplicating navigation rules.
+**Integrity invariant**: project-skill routing depends on the root managed block, but ordinary read-only commands do not silently rewrite root files. Repair of missing or stale root blocks belongs to explicit setup flows such as `init`, repeat `init` repair mode, `update`, and legacy migration.
 
 #### Artifact Validation
 
@@ -1459,5 +1459,5 @@ The following design domains do not require dedicated architecture sections. Eac
 | Identifiers & Traceability | [specs/traceability.md](./specs/traceability.md) | `cpt-studio-fr-core-traceability`, `cpt-studio-component-traceability-engine` |
 | CDSL | [specs/CDSL.md](./specs/CDSL.md) | `cpt-studio-fr-core-cdsl` |
 | Artifacts Registry | [specs/artifacts-registry.md](./specs/artifacts-registry.md) | `cpt-studio-fr-core-config`, `cpt-studio-component-config-manager` |
-| System Prompts | [specs/sysprompts.md](./specs/sysprompts.md) | `cpt-studio-fr-core-config`, `cpt-studio-fr-core-workflows` |
+| Project Rules and Root Navigation | [specs/sysprompts.md](./specs/sysprompts.md) | `cpt-studio-fr-core-config`, `cpt-studio-fr-core-workflows`, `cpt-studio-fr-core-init` |
 | Workspace (inline) | [DESIGN.md §1.2 Multi-Repo Workspace Federation](#multi-repo-workspace-federation) | `cpt-studio-fr-core-workspace`, `cpt-studio-fr-core-workspace-git-sources`, `cpt-studio-fr-core-workspace-cross-repo-editing`; algorithms: `cpt-studio-algo-workspace-resolve-git-url`, `cpt-studio-algo-workspace-resolve-adapter-context`, `cpt-studio-algo-workspace-determine-target`, `cpt-studio-algo-workspace-infer-role` |
diff --git a/architecture/features/agent-integration.md b/architecture/features/agent-integration.md
@@ -145,7 +145,7 @@ Without this feature, users would need to manually create and maintain agent-spe
 
 - [x] `p1` - **ID**: `cpt-studio-algo-agent-integration-discover-agents`
 
-1. [x] - `p1` - Define agent registry: windsurf, cursor, claude, copilot, openai. Detection uses Constructor Studio-specific generated files per agent (e.g. `.claude/skills/cf/SKILL.md`, `.windsurf/workflows/cf.md`, `.cursor/commands/cf.md`, `.github/.constructor-studio-installed` or legacy Studio-managed `copilot-instructions.md` for Copilot, `.codex/.constructor-studio-installed` or `.codex/agents/` with content or legacy `.agents/skills/cf/SKILL.md` for OpenAI) — not generic tool directories. The shared OpenAI fallback is valid only when no other agent's primary or legacy Studio marker is present. User-authored files are never overwritten, and legacy manifest skill files are removed only when they are provably generated copies or pure generated stubs. - `inst-define-registry`
+1. [x] - `p1` - Define agent registry: windsurf, cursor, claude, copilot, openai. Detection uses Constructor Studio-specific generated files per agent (e.g. `.claude/skills/cf/SKILL.md`, `.windsurf/workflows/cf.md`, `.cursor/commands/cf.md`, `.github/.constructor-studio-installed` or legacy Studio-managed `copilot-instructions.md` for Copilot, `.codex/.cf-installed` or `.codex/agents/` with content or legacy `.agents/skills/cf/SKILL.md` for OpenAI) — not generic tool directories. The shared OpenAI fallback is valid only when no other agent's primary or legacy Studio marker is present. User-authored files are never overwritten, and legacy manifest skill files are removed only when they are provably generated copies or pure generated stubs. - `inst-define-registry`
 2. - `p1` - **IF** `--agent` flag provided, filter to single agent - `inst-if-filter`
 3. - `p1` - **RETURN** list of agents to generate for - `inst-return-agents`
 4. [x] - `p1` - Resolve config/kits/ directory and registered kit dirs from core.toml for workflow/skill discovery - `inst-resolve-kits`

diff --git a/architecture/features/core-infra.md b/architecture/features/core-infra.md
@@ -328,7 +328,7 @@ Enables users to install Studio globally, initialize it in any project with sens
 3. [x] - `p1` - **IF** handler not found - `inst-if-no-handler`
    1. [x] - `p1` - **RETURN** error JSON: `{error: "Unknown command"}` (exit 1) - `inst-return-unknown`
 4. [x] - `p1` - Parse remaining arguments per handler's argument spec - `inst-parse-args`
-5. [x] - `p1` - Verify root AGENTS.md integrity (re-inject if missing/stale) - `inst-verify-agents`
+5. [x] - `p1` - Read root AGENTS.md managed metadata for routing without mutating root files during ordinary command dispatch - `inst-read-root-agents`
 6. [x] - `p1` - Execute handler with parsed arguments - `inst-execute-handler`
 7. [x] - `p1` - Serialize handler result to JSON on stdout - `inst-serialize-json`
 8. [x] - `p1` - **RETURN** exit code from handler (0=PASS, 1=error, 2=FAIL) - `inst-return-code`
@@ -384,7 +384,7 @@ Enables users to install Studio globally, initialize it in any project with sens
 2. [x] - `p1` - Add concrete `config/kits/<slug>/` ignore entries only for kits whose `tracking = ignored`; keep other kits tracked - `inst-ignore-kits-by-policy`
 3. [ ] - `p1` - Add only generator-owned agent paths and patterns, never broad parent directories such as `.github/`, `.claude/`, `.cursor/`, `.codex/`, or `.agents/` - `inst-ignore-agent-generated-only`
 4. [ ] - `p1` - Include safe shared skill patterns: `.agents/skills/cf/`, `.agents/skills/cf-*/`, and legacy Studio-owned `studio-*`, `cypilot-*`, `cf-constructor-*` skill dirs - `inst-ignore-shared-skills`
-5. [ ] - `p1` - Include safe Codex patterns: `.codex/agents/cf*.toml`, legacy Studio-owned Codex TOML names, and `.codex/.constructor-studio-installed` - `inst-ignore-codex-generated`
+5. [ ] - `p1` - Include safe Codex patterns: `.codex/agents/cf*.toml`, legacy Studio-owned Codex TOML names, and `.codex/.cf-installed` - `inst-ignore-codex-generated`
 6. [ ] - `p1` - Include safe Claude/Cursor/Copilot/Windsurf generated names with `cf*` patterns and install markers, plus legacy Studio-owned `studio-*`, `cypilot-*`, and `cf-constructor-*` names where generated by prior versions - `inst-ignore-tool-generated`
 7. [x] - `p1` - Write a warning comment that ignored entries are generated surfaces and may be regenerated or overwritten by `cfs init`, `cfs update`, or `cfs generate-agents`; include concrete ignored kit paths only when any kit has `tracking = ignored` - `inst-write-overwrite-warning`
 8. [ ] - `p1` - Replace the managed `.gitignore` block only when start/end markers are intact; on malformed, partial, or nested markers, return warning/error without overwriting user content - `inst-gitignore-marker-safety`
@@ -733,7 +733,11 @@ The command **MUST** also write the managed `.gitignore` footprint block. `.core
 
 - [x] `p1` - **ID**: `cpt-studio-dod-core-infra-agents-integrity`
 
-The system **MUST** verify the root `AGENTS.md` managed block on every CLI invocation (not just init). If the `<!-- @cf:root-agents -->` block is missing, stale, or the file does not exist, the system silently re-injects it with the correct block pointing to the `{cf-studio-path}/` directory.
+The system **MUST** treat the root `AGENTS.md` / `CLAUDE.md` managed block as
+setup metadata, not as a file that ordinary read-only commands silently repair.
+Project-skill routing reads the block on ordinary invocations. Explicit
+setup/repair flows such as `init`, repeat `init` repair mode, `update`, and
+legacy migration own block creation or refresh when it is missing or stale.
 
 **Implements**:
 - `cpt-studio-algo-core-infra-inject-root-agents`
@@ -876,6 +880,6 @@ See ADR-0020 (`architecture/ADR/0020-cpt-studio-adr-rebrand-and-mirror-override-
 - [x] `cfs update [VERSION|BRANCH]` downloads specified version/branch/SHA into cache
 - [x] Download failure produces actionable error message with HTTP status
 - [x] All commands output JSON to stdout and use exit codes 0/1/2
-- [x] Root `AGENTS.md` managed block is verified and re-injected on every CLI invocation
+- [x] Root `AGENTS.md` managed block is read during ordinary CLI routing and refreshed only by explicit setup or repair flows
 - [x] Background version check does not block command execution
 - [x] `{cf-studio-path}/config/AGENTS.md` is created with default WHEN rules for artifacts registry
diff --git a/architecture/researches/contracts-doc-gaps-2026-06.md b/architecture/researches/contracts-doc-gaps-2026-06.md
@@ -0,0 +1,75 @@
+# Contract/Doc Gaps Review — 2026-06
+
+<!-- toc -->
+
+- [Overview](#overview)
+- [Gap 1: Root Runtime Metadata Lifecycle Spec](#gap-1-root-runtime-metadata-lifecycle-spec)
+- [Gap 2: Generated Agent Output Contract Spec](#gap-2-generated-agent-output-contract-spec)
+- [Gap 3: Human vs JSON Output Contract Spec](#gap-3-human-vs-json-output-contract-spec)
+
+<!-- /toc -->
+
+## Overview
+
+This note captures architecture-level gaps that are materially exercised by
+contracts and `_e2e` tests but are still scattered across multiple docs instead
+of being specified once as authoritative behavior.
+
+## Gap 1: Root Runtime Metadata Lifecycle Spec
+
+Why it matters:
+
+- `_e2e` tests enforce that commands such as `info`, `agents`, and
+  `validate-toc` are read-only.
+- setup and migration flows explicitly rewrite root `AGENTS.md` and `CLAUDE.md`
+  managed blocks.
+- legacy migration and repair semantics already include dirty-file and backup
+  behavior.
+
+What is missing:
+
+- one dedicated spec for root managed block format, lifecycle, rewrite triggers,
+  dirty-file safety, migration from legacy markers, and read-only invariants
+
+Recommended home:
+
+- new spec under `architecture/specs/root-runtime-metadata.md`
+
+## Gap 2: Generated Agent Output Contract Spec
+
+Why it matters:
+
+- `generate-agents` and `agents` have a stable public contract across multiple
+  providers
+- canonical kit manifests now include `public`, `generated_targets`, and nested
+  `subagents`
+- `_e2e` covers partial-success reporting, provider-specific skip reasons,
+  generated path ownership, legacy cleanup, and `.gitignore` integration
+
+What is missing:
+
+- one authoritative spec for generated output locations, ownership model,
+  detection markers, provider capability matrix, partial-result schema, and
+  cleanup rules
+
+Recommended home:
+
+- new spec under `architecture/specs/generated-agent-outputs.md`
+
+## Gap 3: Human vs JSON Output Contract Spec
+
+Why it matters:
+
+- `_e2e` distinguishes human-mode summaries from machine JSON contracts
+- statuses such as `OK`, `FOUND`, `NOT_FOUND`, `PASS`, `WARN`, `FAIL`,
+  `PARTIAL`, and `CONFIG_ERROR` are externally observable
+- several commands guarantee read-only behavior in both modes
+
+What is missing:
+
+- one normalized status taxonomy and output-shape spec across JSON mode and
+  human mode, including when partial success is fatal vs non-fatal
+
+Recommended home:
+
+- new spec under `architecture/specs/output-contracts.md`
diff --git a/architecture/specs/artifacts-registry.md b/architecture/specs/artifacts-registry.md
@@ -1014,7 +1014,7 @@ extensions = [".ts"]
 **CLI**: `skills/studio/studio.clispec`
 
 **Related**:
-- `sysprompts.md` - Project system prompts (`{cf-studio-path}/config/sysprompts/` + `config/AGENTS.md`)
+- `sysprompts.md` - Project rules and root navigation (`{cf-studio-path}/config/rules/` + `config/AGENTS.md`)
 
 ---