diff --git a/.agents/PROTOCOL_RULES.md b/.agents/PROTOCOL_RULES.md index faf498e..614d886 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.0 | Updated: 2026-04-21 +> Version: 2.0.1 | Updated: 2026-06-01 > 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`. @@ -128,6 +128,7 @@ Consequences: - [ ] Commit(s) follow `[Agent] : ` convention - [ ] Version bumps applied to any rules file whose content changed - [ ] `active_sessions.md` row for this session removed (if registry is in use) +- [ ] Session-close state written on the feature branch before the PR is opened (when substrate uses pull requests — see §M-git-6) ``` Schema is immutable — no agent may add sections, tables, or free paragraphs. Timestamp must include HH:MM. The session close checklist is **part of the schema**; each box is self-verified by the agent before closing. Unchecked boxes signal incomplete close to the next agent. @@ -207,6 +208,16 @@ At the end of a non-trivial session, the agent **must** update every applicable **JOURNAL promotion — procedural, not heuristic.** At session close, the agent asks the user exactly one procedural question: *"Did this session produce a structurally significant delivery? If yes, promote to JOURNAL."* The user replies with one word. No background detection, no heuristic guessing — orchestration of agents operates on **explicit commands**, never on state inference. The criterion for a "yes" is the six-month test: *if a new contributor arriving in six months would still benefit from seeing this entry, it belongs in JOURNAL; otherwise it belongs only in the actor's personal `activity.log`*. +### Branch ordering rule *(v2.0.1+)* + +Session close is the **final operational step on the feature branch**. Complete all session-close artifacts — handoff, decisions, lessons, and JOURNAL updates — before opening or merging the pull request. + +**Why this order matters:** if session-close state is written on the default branch after merge, protected-branch settings may block the write or force a follow-up PR for state files only. This creates unnecessary review overhead and an audit gap where the handoff describes work that is not yet in the branch history. + +**Implementation rule:** the session-close checklist in `handoff.md` is complete (all boxes checked) when the pull request is **opened**, not after it merges. Agents must not mark the session closed and then create a separate follow-up PR to write state files. + +This rule is substrate-neutral. Git-specific enforcement and rationale live in the active substrate module (see `modules/git-substrate.md §M-git-6`). + **Verification step (mandatory before closing):** Before the final response of the session, the agent verifies that each *applicable* artifact carries today's date. The implementation is substrate-agnostic — shell grep, file tooling with date filtering, or a direct read-and-check — whichever is cheapest in the active environment. If an applicable artifact does not carry today's date, the update was skipped — fix before closing. diff --git a/.agents/modules/git-substrate.md b/.agents/modules/git-substrate.md index 414420d..c850482 100644 --- a/.agents/modules/git-substrate.md +++ b/.agents/modules/git-substrate.md @@ -1,6 +1,6 @@ # modules/git-substrate.md — Git / pull-request substrate rules -> Version: 1.1.0 | Updated: 2026-04-21 | Protocol: Lead Protocol v2.0.0+ +> Version: 1.2.0 | Updated: 2026-06-01 | Protocol: Lead Protocol v2.0.1+ > Scope: Opt-in module. Activate via `PROJECT_RULES.md §J8 Active modules: git-substrate`. > Applies to: repositories hosted on a git platform with pull-request support (GitHub, GitLab, Bitbucket, etc.). @@ -54,6 +54,18 @@ The `PROTOCOL_RULES §P3` commit convention (`[Agent] : `) applie The template ships a `.gitignore` that ignores `.agents/local/`. This is non-negotiable for git-substrate projects: committing per-pair state leaks personal context and creates spurious merge conflicts on every session. If a project using this module lacks the line `.agents/local/` in its `.gitignore`, treat the omission as a bug and fix it before any session close that would commit state. +## §M-git-6 — Session close ordering before PR merge *(v1.2.0+)* + +All session-close state must be committed on the **feature branch** before the pull request is opened. Writing operational state to the default branch after merge is not permitted. + +**Rationale:** the default branch is typically protected (all writes require a PR). State committed after merge requires a follow-up PR for files that carry no meaningful code diff, splitting the audit trail from the work it documents and creating noise in the review history. + +**Agent rule:** the session-close checklist in `handoff.md` must be fully checked before the PR is opened — not after. See PROTOCOL_RULES §P3 branch ordering rule for the substrate-neutral statement. + +**Reviewer signal:** if a PR modifies only project-layer state files (`JOURNAL.md`, `LESSONS.md`, `decisions.jsonl`) and the description explains it as a post-merge closeout, flag the PR. The correct fix is to reopen the feature branch with the state files included and re-merge. + +**Interaction with §M-git-1:** project-layer state files (`JOURNAL.md`, `LESSONS.md`, `decisions.jsonl`) normally allow direct commit without branching. §M-git-6 does not override that — it restricts **when** that direct commit may happen relative to PR lifecycle. When a PR is open for branched work, write your state to the feature branch before merge, not directly to the default branch after. + ## Optional tooling that ships with the template These files are included in the template as conveniences for projects whose substrate is `git+github` and that use common Python-ecosystem tooling. They are **opt-in** — deleting them breaks nothing in the kernel or in this module's rules: diff --git a/README.md b/README.md index bdcc248..bcd8514 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.3** +> Current version: **2.0.4** --- @@ -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.3 --depth 1 https://github.com/mmilanez/lead-protocol.git /tmp/lp +git clone --branch v2.0.4 --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.3 --depth 1 https://github.com/mmilanez/lead-protocol.git $env:TEMP\lp +git clone --branch v2.0.4 --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 @@ -238,6 +238,7 @@ Patch bumps (Z) never break anything. Minor bumps (Y) may introduce new features | Version | Highlights | |---|---| +| **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. | | **2.0.1** | Patch from first external consumer feedback. `migrate_to_v2.py --dry-run` now accepted; pristine `LESSONS.md` scaffold no longer false-positives the rerun-safety guard; `docs/MIGRATION-v2.md` Step 3 rewritten with agent-driven callout and `--agent` slug warning. No kernel or schema changes. |