From ba8dd3f2f0a295c21b2ecd6d982941e6a6d71b9c Mon Sep 17 00:00:00 2001 From: Leonardo Buares Date: Wed, 17 Jun 2026 19:55:42 -0300 Subject: [PATCH 1/2] =?UTF-8?q?feat:=20add=20first-run=20setup=20interview?= =?UTF-8?q?=20gate=20(PROTOCOL=5FRULES=20=C2=A7P10)=20(#21)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/CORE_RULES.md | 8 ++++- .agents/PROTOCOL_RULES.md | 58 +++++++++++++++++++++++++++++++++++- .agents/modules/meta-repo.md | 3 +- .lead-protocol-source | 4 +++ AGENTS.md | 1 + CLAUDE.md | 1 + README.md | 9 ++++-- 7 files changed, 78 insertions(+), 6 deletions(-) create mode 100644 .lead-protocol-source diff --git a/.agents/CORE_RULES.md b/.agents/CORE_RULES.md index 6d37b28..5dcffd0 100644 --- a/.agents/CORE_RULES.md +++ b/.agents/CORE_RULES.md @@ -1,6 +1,6 @@ # CORE_RULES.md — Rules index and essential contracts -> Version: 1.5.0 | Updated: 2026-04-21 | Protocol: Lead Protocol v2.0.0 +> Version: 1.6.0 | Updated: 2026-06-17 | Protocol: Lead Protocol v2.1.0 This file is the first thing every agent reads. It is deliberately short: just the index into `PROTOCOL_RULES.md`, the essential contracts an agent must obey at every session start, and the precedence rule. It never duplicates the kernel — only points at it. @@ -19,6 +19,8 @@ Read, in order: Listing (not reading) of `.agents/checkpoints/` is enough on boot; individual checkpoints load on demand when relevant. `PROTOCOL_RULES.md` itself is consulted on demand — not in the baseline — per `§P-Access`. +After step 2, if `PROJECT_RULES.md` is still pristine (see *First-run setup is a hard boot gate* below), run the `§P10` setup gate before proceeding to step 3. + --- ## Essential contracts @@ -61,6 +63,10 @@ Agents never edit `.agents/AGENTS_MAP.md` autonomously. They *propose* additions Every non-trivial session closes by self-verifying the checklist in `handoff.md`. One item is a **procedural question** to the user: *"Did this session produce a structurally significant delivery? If yes, promote to JOURNAL."* No heuristic, no auto-detection. Detail: `PROTOCOL_RULES.md §P3 — Session close ritual`. +### First-run setup is a hard boot gate + +If `PROJECT_RULES.md` is absent or still pristine (the `§J1` Name or the `§J8` substrate/modules still contain a `[...]` placeholder), the agent must run the first-run setup interview and write the answers before doing any other requested work, even work the user asked for first. The user may reply `later` to defer once; the gate re-fires next session. Non-interactive environments (CI, Codespaces, devcontainers) skip with a warning. A repo-root `.lead-protocol-source` sentinel disables the gate for the framework's own source repo. The gate self-clears once Name and `§J8` are real. Detail: `PROTOCOL_RULES.md §P10`. + --- ## Precedence diff --git a/.agents/PROTOCOL_RULES.md b/.agents/PROTOCOL_RULES.md index 614d886..73a1d7c 100644 --- a/.agents/PROTOCOL_RULES.md +++ b/.agents/PROTOCOL_RULES.md @@ -1,6 +1,6 @@ # PROTOCOL_RULES.md — Lead Protocol framework rules (generic) -> Version: 2.0.1 | Updated: 2026-06-01 +> Version: 2.1.0 | Updated: 2026-06-17 > Scope: Substrate-agnostic kernel. Opt-in modules live in `modules/` and are activated via `PROJECT_RULES.md §J8`. > This file contains no project-specific content — that lives in `PROJECT_RULES.md`. @@ -464,3 +464,59 @@ Agents read active modules after `PROJECT_RULES.md` and before `AGENTS_MAP.md` / - When a module cites a kernel anchor, use the fully qualified form `PROTOCOL_RULES §Px` to mark the module→kernel crossing explicitly. - A module may depend on another module only if it declares the dependency in its header. - Module CI/tooling (if any) must include a top-of-file comment identifying the module it enforces, so consumer repos that do not list the module know not to copy the tooling. + +## §P10 — First-run setup interview *(v2.1.0+)* + +Lead Protocol ships `PROJECT_RULES.md` as a pristine template: `[Project Name]`, bracketed `[e.g., ...]` examples, and an unconfigured `§J8`. Whether a project was scaffolded by copying the release files or by the bundled CLI, the template is identical and must be configured before the protocol can operate correctly, because without a real `§J8 Active modules` the agent cannot even finish its baseline boot (step 3 loads the modules named there). Consumers frequently skip this step and let agents run against the raw template. This section makes configuration a hard, self-clearing boot gate. + +### Pristine detection + +After reading `PROJECT_RULES.md` (baseline boot step 2), the project is **unconfigured** when ANY of these holds: + +- `PROJECT_RULES.md` is absent. +- The `§J1` **Name** value still contains a `[...]` placeholder (for example, `[Project Name]`). +- The `§J8` **Active substrate** or **Active modules** value still contains a `[...]` placeholder. + +Detection is purely textual (a `[` inside the field value), the same signal the bundled CLI already uses. There is no separate marker file; the filled fields are the marker. + +### Framework-source carve-out + +If a sentinel file named `.lead-protocol-source` exists at the repository root, the gate is disabled. This marks the Lead Protocol framework's own development and distribution source, whose scaffold is pristine by design and must stay that way to ship. The sentinel lives outside `.agents/`, so it never travels to a consumer project through either install path. + +### The gate (interactive environments) + +When a project is unconfigured and not carved out, the agent MUST, before performing any other requested work: + +1. Pause the user's request and state that the project is not yet configured. +2. Run the setup interview (below). +3. Write the answers into `PROJECT_RULES.md`. +4. Resume the user's original request. + +The user may defer exactly once by replying `later` or `skip`. The agent then performs the requested work but operates under an explicit "project unconfigured" caveat, and the gate re-fires at the start of every subsequent session. Deferral is never persisted: there is no "don't ask again". This mirrors the `§P3` AGENTS_MAP fallback, where an unresolved state recurs as a social signal rather than being silently suppressed. + +### Non-interactive environments + +If the environment is non-interactive (any of `CI`, `GITHUB_ACTIONS`, `CODESPACES`, `DEVCONTAINER` is set, or no interactive input channel exists, the same signals `§P3` uses for `` ephemeral detection), the agent skips the interview, emits a single warning that `PROJECT_RULES.md` is unconfigured, proceeds with the task, and persists no configured state. The next interactive session is gated normally. + +### Interview content + +The interview gathers the minimum needed for identity and operation. Soft fields are defaulted with a `refine later` note rather than asked: + +| # | Question | Writes to | +|---|---|---| +| 1 | Project name | `§J1` Name and the document title line | +| 2 | Type and one-line purpose | `§J1` Type, Purpose | +| 3 | Primary stack | `§J1` Stack | +| 4 | Substrate (`git+github` / `git` / `local` / `cloud-sync` / `other`) | `§J8` Active substrate; auto-derives `§J8` Active modules (`git` or `git+github` gives `git-substrate`; otherwise `none`) and a default branch convention | +| 5 | Primary language for source and docs | `§J4` (source/docs row). AI operational files stay EN-US regardless, per `§P5` | +| 6 | Which agents operate here | `§J2` table (defaults: the current agent as lead, Humans as reviewer) | + +After the interview the agent: + +- Fills every bracketed field it has an answer for. Sets soft or unsupplied fields (`§J3` tone, `§J5` extra checks, `§J1` Consumers) to sensible defaults annotated ``. It never leaves a `[...]` placeholder in Name or `§J8`. +- Stamps the `> Updated:` header with today's date. +- Proposes any new agent-signature rows for `AGENTS_MAP.md` to the user for confirmation, but does NOT write `AGENTS_MAP.md` itself (`§P3`: AGENTS_MAP is maintainer-managed). + +### Idempotency + +Once Name and `§J8` carry real values, pristine detection returns false and the gate never fires again. No flag, no marker, nothing to drift. diff --git a/.agents/modules/meta-repo.md b/.agents/modules/meta-repo.md index a962eb8..3c5def3 100644 --- a/.agents/modules/meta-repo.md +++ b/.agents/modules/meta-repo.md @@ -1,6 +1,6 @@ # modules/meta-repo.md — Meta-repo rules (IDE ↔ template lifecycle) -> Version: 1.1.0 | Updated: 2026-04-21 | Protocol: Lead Protocol v2.0.0+ +> Version: 1.1.1 | Updated: 2026-06-17 | Protocol: Lead Protocol v2.0.0+ > Scope: Opt-in module. Activate via `PROJECT_RULES.md §J8 Active modules: meta-repo`. > Applies to: **meta-repos** — repositories that develop the Lead Protocol itself and contain both a root `.agents/` directory and a `template/` directory. Consumer repos almost never list this module. @@ -35,6 +35,7 @@ Templates distributed with the Lead Protocol ship state files populated with pla | File | Pristine indicator | |---|---| +| `PROJECT_RULES.md` | `[Project Name]` in `§J1` Name, or `[...]` in `§J8` substrate/modules. Triggers the `PROTOCOL_RULES §P10` first-run setup interview | | `handoff.md` | Literal `YYYY-MM-DD` or `[Your Agent Signature]` placeholders | | `decisions.jsonl` | Empty file | | `JOURNAL.md` | Only the header + the "*(No entries yet — …)*" placeholder | diff --git a/.lead-protocol-source b/.lead-protocol-source new file mode 100644 index 0000000..0454877 --- /dev/null +++ b/.lead-protocol-source @@ -0,0 +1,4 @@ +This file marks the Lead Protocol framework's own source and distribution repository. +Its presence disables the PROTOCOL_RULES.md §P10 first-run setup gate, because the +scaffold in this repo is pristine by design and must ship that way. Consumer projects +never contain this file: it lives outside .agents/, so neither install path copies it. diff --git a/AGENTS.md b/AGENTS.md index d11bd69..0271aec 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,7 @@ Before taking any action, read the rules and the current state in this order: 1. `.agents/CORE_RULES.md` — index + essential contracts 2. `.agents/PROJECT_RULES.md` — identify the scopes listed in `§J8 Active modules` +2a. **Setup gate:** if `.agents/PROJECT_RULES.md` is missing or still pristine (`§J1` Name or `§J8` substrate/modules still contain `[...]` placeholders) and no repo-root `.lead-protocol-source` sentinel exists, run the first-run setup interview defined in `.agents/PROTOCOL_RULES.md §P10` and write the answers before serving any request, even if the user asked for something else first. Reply `later` defers once; non-interactive environments skip with a warning. 3. For each scope listed in `§J8 Active modules` (in declaration order): `.agents/modules/.md` 4. `.agents/AGENTS_MAP.md` — tool-signature → agent-slug map; resolve your own `` slug here (needed to form the per-pair handoff path) 5. `.agents/sessions/active_sessions.md` — concurrent-session awareness diff --git a/CLAUDE.md b/CLAUDE.md index 85f35e0..77dd692 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,6 +8,7 @@ At the start of every session, you MUST silently read the following files in ord 1. `.agents/CORE_RULES.md` — index of operations and essential contracts 2. `.agents/PROJECT_RULES.md` — business context; read `§J8 Active modules` first +2a. **Setup gate:** if `.agents/PROJECT_RULES.md` is missing or still pristine (the `§J1` Name or `§J8` substrate/modules still contain `[...]` placeholders) AND no `.lead-protocol-source` sentinel exists at the repo root, you MUST run the first-run setup interview defined in `.agents/PROTOCOL_RULES.md §P10` and write the answers before continuing the boot or serving any request, even if the user asked for something else first. The user may reply `later` to defer once. In non-interactive environments, skip with a warning. 3. For each scope listed in `§J8 Active modules` (in declaration order): `.agents/modules/.md` 4. `.agents/AGENTS_MAP.md` — tool-signature → agent-slug map (needed to resolve your own `` slug) 5. `.agents/sessions/active_sessions.md` — concurrent-session awareness diff --git a/README.md b/README.md index bcd8514..b3e891e 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ When one AI session ends, it writes down what it did, what's left, and why it made the calls it made. The next session — even a different tool, even days later — reads that and picks up where the last one stopped. Nothing forgotten, nothing re-explained. -> Current version: **2.0.4** +> Current version: **2.1.0** --- @@ -117,7 +117,7 @@ cp -R /tmp/lp/.agents your-project/.agents cp /tmp/lp/CLAUDE.md your-project/CLAUDE.md cp /tmp/lp/AGENTS.md your-project/AGENTS.md -# Set your project's identity +# Set your project's identity (optional: on first run your agent will interview you and fill this in) $EDITOR your-project/.agents/PROJECT_RULES.md # Verify the scaffold state @@ -137,7 +137,7 @@ Copy-Item -Recurse $env:TEMP\lp\.agents your-project\.agents Copy-Item $env:TEMP\lp\CLAUDE.md your-project\CLAUDE.md Copy-Item $env:TEMP\lp\AGENTS.md your-project\AGENTS.md -# Set your project's identity +# Set your project's identity (optional: on first run your agent will interview you and fill this in) code your-project\.agents\PROJECT_RULES.md # Verify the scaffold state @@ -209,6 +209,8 @@ Every compliant agent reads, in order: `PROTOCOL_RULES.md` itself is read **on demand**, not in the baseline — `CORE_RULES.md` points agents there when needed. This keeps baseline cost bounded. See `PROTOCOL_RULES.md §P-Access` for the full load contract. +**First run:** if `PROJECT_RULES.md` is still the pristine template, the agent does not silently proceed. It runs a short setup interview, fills in your project identity, and only then handles your request. See `PROTOCOL_RULES.md §P10`. You can still configure the file by hand instead. + Pointer files `CLAUDE.md` and `AGENTS.md` at the project root exist so each vendor-specific agent tool discovers `.agents/` without custom configuration. --- @@ -238,6 +240,7 @@ Patch bumps (Z) never break anything. Minor bumps (Y) may introduce new features | Version | Highlights | |---|---| +| **2.1.0** | **First-run setup interview (kernel 2.1.0).** New `PROTOCOL_RULES §P10`: when a project still runs the pristine `PROJECT_RULES.md` template, any compliant agent runs a short setup interview on boot and writes the project identity before serving requests, instead of silently operating against the template. Hard gate with a one-time `later` defer; skipped in non-interactive environments; self-clears once configured. A repo-root `.lead-protocol-source` sentinel exempts the framework's own source repo. | | **2.0.4** | **Branch ordering rule (kernel 2.0.1).** Adds an explicit rule (PROTOCOL_RULES §P3) requiring session-close state to be committed on the feature branch before the PR is opened, not written to the default branch after merge. Adds §M-git-6 to `git-substrate.md` with git-specific enforcement and a reviewer signal for post-merge closeout PRs. Adds one checklist item to the handoff schema. Fixes #2. | | **2.0.3** | Security patch: `migrate_to_v2.py` now validates `--actor` / `--agent` values against path traversal (rejects `..`, `/`, `\`, absolute paths, drive letters). README Quick Start updated to current release with PowerShell copy block added. `SECURITY.md` and `CONTRIBUTING.md` scope corrected (CLI/MCP are roadmap, not shipped). CI workflow permissions hardened. No kernel or schema changes. | | **2.0.2** | Documentation and release infrastructure fixes. README version references corrected. No kernel or schema changes. | From fb8603fed6a85abf24f241871ff9e6572770324c Mon Sep 17 00:00:00 2001 From: Leonardo Buares Date: Wed, 17 Jun 2026 20:08:15 -0300 Subject: [PATCH 2/2] docs(readme): bump quick-start clone tags to v2.1.0 (#21) --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b3e891e..077f00e 100644 --- a/README.md +++ b/README.md @@ -110,7 +110,7 @@ Lead Protocol fills the operational-state slot in the broader agent stack: ```bash # Clone the latest stable release # Check https://github.com/mmilanez/lead-protocol/releases for the current version number -git clone --branch v2.0.4 --depth 1 https://github.com/mmilanez/lead-protocol.git /tmp/lp +git clone --branch v2.1.0 --depth 1 https://github.com/mmilanez/lead-protocol.git /tmp/lp # Copy the scaffold into your project cp -R /tmp/lp/.agents your-project/.agents @@ -130,7 +130,7 @@ python .agents/scripts/validate_state.py ```powershell # Clone the latest stable release # Check https://github.com/mmilanez/lead-protocol/releases for the current version number -git clone --branch v2.0.4 --depth 1 https://github.com/mmilanez/lead-protocol.git $env:TEMP\lp +git clone --branch v2.1.0 --depth 1 https://github.com/mmilanez/lead-protocol.git $env:TEMP\lp # Copy the scaffold into your project Copy-Item -Recurse $env:TEMP\lp\.agents your-project\.agents