@antoneeo/agentic-sdlc-skill 1.51.0 → 1.52.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.52.0] - 2026-11-01
+
+### What's new
+
+**A session that writes only documents no longer costs you a branch.** When you run several sessions with a coordinator, a session working only on design documents can work in the folder the others already use, instead of a worktree of its own. It writes only its own unit's files, runs no git command that changes the folder, and leaves index regeneration and its closure steps to the coordinator, so you no longer merge one branch per documents-only unit. A session that writes code still holds the code lease, or works in its own worktree.
+
+**Every file several sessions touch has one writer.** Each session adds only its own rows to the review log. Translation catalogs count as code, so in the shared folder only the session holding the code lease writes them. devPNT's store goes in the Shared section of a commit map.
+
+**The coordinator survives compaction and changes only when you say so.** After its context is compacted, the coordinator rereads the leases and the shared request record before acting, instead of trusting its summary. A session it starts does not become coordinator. To change coordinator, name the new session: it records your words, tells the previous coordinator, which stops, and sends you anything written in between.
+
+**Branches that add review rows merge without a conflict.** When two branches both add rows to the review log and your project has no merge rule for that file, merging them stops on a conflict you resolve by hand. The check the agent runs when it closes a piece of work now notices the missing rule and prints the exact line to add to `.gitattributes`, so the agent sees what to fix while it works, without anyone reading release notes. Nothing changes at session start, and the note never makes a check fail.
+
+#### What to do
+
+**1. Update (everyone).** The changes arrive only with the update.
+1. Run `npm install -g @antoneeo/agentic-sdlc-skill@latest`, then `agentic-sdlc-install-skill`.
+2. Close and reopen your agent sessions: the new version loads only at startup.
+
+To check: `npm ls -g @antoneeo/agentic-sdlc-skill` shows 1.52.0.
+
+### Changed
+- `coordination.md` (F-089): the checkout a runtime mounts is the one exception to «own worktree» under coordination — the code-writer lease holder, a documents-only part (its own unit's files under the docs root and its own review-log rows; no git command that changes the checkout, no `index` or `mark`) and the coordinator, which alone runs `index`, `review-map` and `mark` there; the switch/stash/reset bans hold. «Code» defined (translation catalogs included). §1 retitled «Shared files: one writer each»: review log, translation catalogs, an external tool's store tracked in git. Who coordinates: the named conversation keeps the role across compaction and rereads `leases.md` and the shared record; a session another starts never inherits it; a new owner entry changes it, with a handover window up to the previous coordinator's answer. `leases.md` opens with a `coordinator` line. Ruling r42.
+- `SKILL.md` Phase 4: the shared checkout, not the code-writer lease alone, is the exception to the own worktree; the bans hold there and only its coordinator runs `index`.
+- `templates.md`: `leases.md` opening line; a commit-map Shared example for devPNT's store.
+- The shared validator (F-090): `check` prints a `[note]` when the review log (`<docs>/audit/reviews/REVIEW_LOG.md`) has no `merge` attribute, naming the line to add to `.gitattributes` at the repository root (`git check-attr`, with personal and system attribute files ignored; a per-clone `.git/info/attributes` still counts). A deliberate non-union driver is respected. The exit code is unchanged, and session orientation still runs no git.
+- `ENFORCEMENT.md`: «A review log git would not merge cleanly -- `check` names it» (F-090).
+- `templates.md`: the `.gitattributes` stanza's note says `check` names a missing stanza; `coordination.md` §1: the coordinator adds it (F-090).
+
 ## [1.51.0] - 2026-10-31
 
 ### What's new

package/README.md

@@ -4,13 +4,15 @@
 
 <!-- whats-new:begin -->
 <!-- generated by scripts/whats_new.js from CHANGELOG.md: edit the CHANGELOG, then run node scripts/whats_new.js --write -->
-## What's new in 1.51.0
+## What's new in 1.52.0
 
-**Several sessions can work on one repository, one of them coordinating.** When you run several agent sessions on the same project at once and tell one of them that it coordinates the others, they follow shared rules. Each request record has a single writer, so its entries are never numbered twice. A resource only one session can use at a time, such as the development container or the test database, is taken and released through the coordinator, so one session no longer restarts what another is running against. An authorization you gave one session is not passed to another by message. A session that stops reports what it did, and the coordinator checks it before telling you the work is done. Before a commit that carries several sessions' work, the coordinator checks that every changed file is assigned to the right unit. If you name no coordinator, nothing changes.
+**A session that writes only documents no longer costs you a branch.** When you run several sessions with a coordinator, a session working only on design documents can work in the folder the others already use, instead of a worktree of its own. It writes only its own unit's files, runs no git command that changes the folder, and leaves index regeneration and its closure steps to the coordinator, so you no longer merge one branch per documents-only unit. A session that writes code still holds the code lease, or works in its own worktree.
 
-**Decisions taken on your behalf are labelled.** In the request record, a decision a session took under a delegation you gave it, and words you gave one session for work another session records, now carry their own heading. They are never read later as something you said yourself, and a delegated decision never overrides one of yours: a choice that would change it comes back to you as a question.
+**Every file several sessions touch has one writer.** Each session adds only its own rows to the review log. Translation catalogs count as code, so in the shared folder only the session holding the code lease writes them. devPNT's store goes in the Shared section of a commit map.
 
-**The reminder of what must not break also covers files written from the shell.** From 1.49.0 the agent is reminded of a unit's constraints before it edits a file; a file it writes through a shell command never triggered that reminder, so the agent now looks the constraints up itself.
+**The coordinator survives compaction and changes only when you say so.** After its context is compacted, the coordinator rereads the leases and the shared request record before acting, instead of trusting its summary. A session it starts does not become coordinator. To change coordinator, name the new session: it records your words, tells the previous coordinator, which stops, and sends you anything written in between.
+
+**Branches that add review rows merge without a conflict.** When two branches both add rows to the review log and your project has no merge rule for that file, merging them stops on a conflict you resolve by hand. The check the agent runs when it closes a piece of work now notices the missing rule and prints the exact line to add to `.gitattributes`, so the agent sees what to fix while it works, without anyone reading release notes. Nothing changes at session start, and the note never makes a check fail.
 
 #### What to do
 
@@ -18,17 +20,7 @@
 1. Run `npm install -g @antoneeo/agentic-sdlc-skill@latest`, then `agentic-sdlc-install-skill`.
 2. Close and reopen your agent sessions: the new version loads only at startup.
 
-To check: `npm ls -g @antoneeo/agentic-sdlc-skill` shows 1.51.0.
-
-**2. Coordinating several sessions (only if you run them in parallel).**
-- **This concerns you if** you run more than one agent session on the same repository at the same time.
-- **Why:** without a coordinator, sessions can write the same record at once, restart a container another session is using, or leave one commit nobody can split by unit.
-- **Steps:** tell the session you want as coordinator, in your own words, that it coordinates the others; it records your words, and the rules apply from then on. Each other session asks it before using a shared resource. Before committing several sessions' work together, it writes the commit map and runs `sdlc_check.py commit-map <map file>`.
-- **To check:** when a session takes a shared resource, `ai_docs/audit/leases.md` gains a `take` line naming it.
-
-| New file | Skill | Who reads it |
-|---|---|---|
-| `coordination.md` | agentic-sdlc | the agent, only while several sessions share a repository |
+To check: `npm ls -g @antoneeo/agentic-sdlc-skill` shows 1.52.0.
 
 Full history: [CHANGELOG](https://github.com/Antoneeo/agentic-sdlc-skill/blob/main/CHANGELOG.md)
 <!-- whats-new:end -->

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.51.0",
+  "version": "1.52.0",
   "description": "Documentation-First SDLC protocol with triage, Vision governance and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.51.0",
+  "version": "1.52.0",
   "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
   "keywords": [
     "claude-code",

package/skills/agentic-sdlc-skill/ENFORCEMENT.md

@@ -183,6 +183,16 @@ not see them, because the wired hook legitimately lives in the git-ignored
 mechanism (Gemini today) keeps the note -- read it as the manual-reads reminder; a
 `.codex/hooks.json` wired in a shape other than the documented one keeps it too.
 
+**A review log git would not merge cleanly -- `check` names it (F-090).** When the docs
+root holds `audit/reviews/REVIEW_LOG.md` and git reports no `merge` attribute for it (no
+committed `.gitattributes` line covers it: a project set up before the stanza, a custom
+docs root, a project below the repository root, a course project), `check` prints one
+`[note]` with the exact line to add at the repository root. Same contract as above:
+informational, never the exit code, never a `validate` warning. Personal attribute files
+(except the per-clone `.git/info/attributes`) are ignored, so the note matches what a
+teammate's clone does; a deliberate driver other
+than `union` is respected. Session orientation does not run it: it stays zero-execution.
+
 **Installing the package wires the hook machine-wide (F-042).** On Claude Code
 with Python, `npm i -g` (and every update) wires a SessionStart orient hook into
 the USER-level settings (`$CLAUDE_CONFIG_DIR/settings.json` when set, else

package/skills/agentic-sdlc-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentic-sdlc
-version: 1.51.0
+version: 1.52.0
 description: Documentation-First SDLC protocol with risk-proportional triage, Vision as a guide, a complete Standalone mode and optional symbiosis with devPNT. Use for features, significant bugs, refactors, audits and documented maintenance.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto
@@ -208,7 +208,7 @@ Hybrid L3:
 ### 4. Development and Testing
 
 - Implement only after the documentation gate required by the level; at L3 it ends with the owner's design approval (`review.md` §When a review is due). **Flip the ANALYSIS frontmatter `PLANNED` → `IN_PROGRESS` when implementation starts** — that flip is what `gate` and the handoff registry key on, and nothing else performs it.
-- Isolate the work: run an L3 change on its own branch. In Hybrid, prefer a git worktree from the start — a running devPNT server locks `.devpnt/*.db` and blocks in-place branch switches/merges in the primary worktree. A session that may run while another session uses the same checkout works in its **own git worktree**, and never switches branch, stashes, resets or runs `index` in a checkout another session may be using; under coordination, the code-writer lease is the one exception (`coordination.md` §2). Parallel work also shares ids: choose a new unit's id **after fetching**, as the first id free on every branch and tag the checkout can see (`check` names a collision while the unit is open).
+- Isolate the work: run an L3 change on its own branch. In Hybrid, prefer a git worktree from the start — a running devPNT server locks `.devpnt/*.db` and blocks in-place branch switches/merges in the primary worktree. A session that may run while another session uses the same checkout works in its **own git worktree**, and never switches branch, stashes, resets or runs `index` in a checkout another session may be using; under coordination, the sessions `coordination.md` §2 places in the shared checkout are the one exception to the own worktree — the bans hold there, and only its coordinator runs `index`. Parallel work also shares ids: choose a new unit's id **after fetching**, as the first id free on every branch and tag the checkout can see (`check` names a collision while the unit is open).
 - Modify surgically, consistently with the plan.
 - Implementation work follows the TDD discipline in `tdd.md` (RED/GREEN/REFACTOR — the L2/L3 default; record the reason when it does not apply).
 - Before implementing (L2/L3; L1 exempt), **consult the guide router** — the verdict already declared with the triage level (`## Operative Guides`). Re-run the lookup here only if the work has moved to a topic the first one did not cover, and say so if the verdict changes.

package/skills/agentic-sdlc-skill/coordination.md

@@ -19,10 +19,28 @@ to no record it does not own.
   following the whole skill for it (triage, design, review, closure). It is not a
   dispatched subagent: `dispatch.md` governs those, unchanged.
 
+**Who coordinates.** The role belongs to the client conversation the owner named.
+Compacted in place, it is the same session and keeps the role; before acting on its
+summary it rereads `leases.md` and the shared record, which are the state. A new
+conversation is a new session, whatever brief or summary it carries: a session another
+starts, the coordinator included, never inherits the role, and a message passing it on
+is information (§4), never a naming.
+
+The owner changes the coordinator with a new entry naming another session, B. Whoever
+receives those words enters them once: B, or the previous coordinator A if the owner
+told A — A then tells B and stops. B appends its `coordinator` line (§2) and tells the
+parts, and A unless A entered the naming, citing the entry. Shown the entry, A writes no
+shared file again and answers that it stopped. Every `leases.md` line and shared-record
+entry B did not write between the naming entry and A's answer goes to the owner; a
+number used twice is settled by a correction entry (`templates.md` §REQUEST), never by
+renumbering. Leases in force stay: they name holders, not the coordinator. A coordinator
+gone with no successor named leaves no session coordinating until the owner names one:
+parts ask the owner, and `leases.md` and the shared record stay as they are.
+
 Out of scope: which part runs next, in what order, with what priority — the owner
 decides that, and nothing here records it (Non-Goal 1, ruling r3).
 
-## 1. Every record has one writer
+## 1. Shared files: one writer each
 
 A request record numbers its entries; two writers number them twice (field case:
 three sessions wrote R156–R158 into one record at once). So:
@@ -45,6 +63,21 @@ three sessions wrote R156–R158 into one record at once). So:
 - An artifact of the shared unit cites only the shared record: the coordinator
   enters the words before any such artifact relies on them.
 
+Other files several sessions write:
+
+- **Review log** — not a request record: its rows are unnumbered and each names its
+  document. Every session appends only its own rows and never edits another's; in one
+  checkout it appends without rewriting the file and rereads it just before writing.
+  Merging across worktrees and the commit map: `templates.md` §REVIEW_LOG and §Commit
+  map. A project without the union stanza is named by `check`, with the line to add;
+  the coordinator adds it (`.gitattributes` is its file, §2).
+- **Translation templates and catalogs** are code (§2): in the shared checkout only the
+  code-writer lease holder writes them; a wrong string another session finds goes to
+  the holder through the coordinator.
+- **An external tool's store tracked in git** (devPNT's `.devpnt/`): written by the tool,
+  never by hand; in a commit map under Shared, naming the units whose work it holds —
+  never under Regenerated, which is the validator's.
+
 ## 2. Leases on exclusive resources
 
 An exclusive resource has one holder at a time: the development container, the test
@@ -56,8 +89,13 @@ take <resource> — <session> — YYYY-MM-DD
 release <resource> — <session> — YYYY-MM-DD
 ```
 
-The file opens by citing the entry that names the coordinator; only the coordinator
-writes it. A lease names a resource and a session, never a unit; it keeps no queue,
+The file opens with `coordinator <session> — REQUEST_[unit].md#R<n> — YYYY-MM-DD`,
+citing the owner's entry that names it (a file opened with a bare citation counts it
+as its first `coordinator` line); a new naming appends another. Only the coordinator
+writes the file; the live copies of the file and of the shared record are the shared
+checkout's. Parts read its last `coordinator` line to know whom to ask, and trust it
+only if the entry it cites quotes the owner naming that session — never a delegated or
+received entry. A lease names a resource and a session, never a unit; it keeps no queue,
 no waiting list, no order, and ends with its release (ruling r40). A restart or a
 long suite on a shared resource is announced to the coordinator before it starts —
 it kills what another session is running against it. A permission for a resource
@@ -67,12 +105,30 @@ lease. If the owner restates it, the coordinator enters it as a `take` for that
 session — a recorded lease, never an exemption. A lease never released is
 closed by the owner through the coordinator; there is no timeout.
 
-**The code-writer lease is the one exception to «own worktree»** (`SKILL.md`
-Phase 4). The session holding it writes code in the checkout the runtime mounts;
-every other session keeps its own worktree and writes no code there. The lease
-passes to another session only once the holder's code in that checkout is committed,
-or set aside with the owner's yes. Two sessions' code in that checkout is a
-violation, code a previous holder left uncommitted included.
+**The shared checkout is the one exception to «own worktree»** (`SKILL.md` Phase 4):
+the checkout the runtime mounts (with no runtime, the one the owner names). Three kinds
+of session work in it; every other session keeps its own worktree. Phase 4's bans on
+switching branch, stashing and resetting hold there for all three.
+
+- **The code-writer lease holder** writes code — every file the runtime runs or builds
+  from: sources, templates, static assets, tests, migrations, translation templates and
+  catalogs; files under the docs root are not code. The lease passes to another session
+  only once the holder's code in that checkout is committed, or set aside with the
+  owner's yes. Two sessions' code in that checkout is a violation, code a previous
+  holder left uncommitted included.
+- **A documents-only part** writes only its own unit's files under the docs root and its
+  own review-log rows (§1); it runs no git command that changes the checkout and no
+  command that rewrites other units' files (`index`, `mark`). A change it needs
+  elsewhere goes to the session that writes that file. Before writing any code it asks
+  the coordinator: it takes the code-writer lease, or the owner commits its documents
+  and its own worktree is cut from that commit.
+- **The coordinator** writes the shared files, and any file there that is neither code
+  nor under the docs root (root `README.md`, `CHANGELOG.md`, `.gitattributes`, CI
+  configuration — it runs `init` when needed); it alone runs `index`, `review-map` and
+  `mark` there, for the documents-only parts' closure steps too. There `review-map` sees
+  every session's files, so when a documents-only part closes, the coordinator writes
+  that unit's section of the commit map (§6) and the part's merge brief takes its file
+  table from it, and says so.
 
 ## 3. Decisions taken under delegation
 
@@ -111,6 +167,9 @@ Open points:
 Needs the owner:
 ```
 
+A documents-only part in the shared checkout lists under `Open points` the closure
+steps it left to the coordinator (§2).
+
 The coordinator checks each claim on the diff and the run output, never on the
 message (`review.md`, an unproven completion claim), then tells the owner what is
 done, what is left and what needs them.

package/skills/agentic-sdlc-skill/scripts/sdlc_core.py

@@ -1377,9 +1377,12 @@ def _open_units(root):
     return units
 
 
-def _git_out(root, *args, timeout=30):
+def _git_out(root, *args, timeout=30, env=None):
+    # `env` is merged into the inherited environment, never a replacement: a bare
+    # dict would drop PATH and fail silently on Windows.
     r = subprocess.run(["git", *args], cwd=str(root), capture_output=True, text=True,
-                       encoding="utf-8", errors="replace", timeout=timeout)
+                       encoding="utf-8", errors="replace", timeout=timeout,
+                       env={**os.environ, **env} if env else None)
     return r.stdout if r.returncode == 0 else None
 
 
@@ -2481,10 +2484,64 @@ def cmd_check(root, strict=False, hybrid=False, extra_validate=None, extra_secti
     failed = any(rc for _, rc in rcs)
     print(f"\ncheck: {'NOT CLEAN' if failed else 'CLEAN'} "
           f"({', '.join(f'{title} rc={rc}' for title, rc in rcs)})")
-    print_orient_hook_note(root)
+    print_check_notes(root)
     return 1 if failed else 0
 
 
+def _attr_pattern(path):
+    """A .gitattributes pattern matching exactly `path`. Order matters (probed):
+    a backslash, glob characters and a leading `#` or `!` (comment, negation)
+    are escaped first, then the result is C-quoted when it holds whitespace,
+    `"` or a backslash."""
+    p = re.sub(r"([\\\[*?])", r"\\\1", path)
+    if p.startswith(("#", "!")):
+        p = "\\" + p
+    if re.search(r'[\s"\\]', p):
+        p = '"' + p.replace("\\", "\\\\").replace('"', '\\"') + '"'
+    return p
+
+
+def review_log_union_note(root):
+    """F-090: the note for a review log git would not merge with union, or None.
+
+    Git itself is asked (`check-attr`), so patterns and nested files count;
+    personal and system attribute files do not, so the answer is the one a
+    teammate's clone gets. Only `unspecified` is a gap: `union` or any other
+    driver is a choice. Residual: `.git/info/attributes` is still read. Any
+    failure -- no git, not a work tree, timeout -- is no note: `check` never
+    breaks on it."""
+    try:
+        log = ai_path(root, "audit", "reviews", "REVIEW_LOG.md")
+        if not log.is_file():
+            return None
+        prefix = _git_out(root, "rev-parse", "--show-prefix", timeout=3)
+        if prefix is None:
+            return None
+        rel = log.resolve().relative_to(Path(root).resolve()).as_posix()
+        out = _git_out(root, "-c", "core.attributesFile=", "check-attr", "-z", "merge",
+                       "--", rel, timeout=3, env={"GIT_ATTR_NOSYSTEM": "1"})
+        if out is None:
+            return None
+        fields = out.split("\0")
+        if len(fields) < 3 or fields[2] != "unspecified":
+            return None
+        path = prefix.rstrip("\r\n") + rel  # a folder may begin with a space
+        return (f"[note] {path} has no merge attribute: two branches that both add review "
+                "rows conflict when merged. Fix: add this line to .gitattributes at the "
+                f"repository root: {_attr_pattern(path)} merge=union")
+    except Exception:
+        return None
+
+
+def print_check_notes(root):
+    """Every check-layer note, informational and never an exit code. The one
+    place an overlay that replaces `check` calls, so a new note cannot miss it."""
+    print_orient_hook_note(root)
+    note = review_log_union_note(root)
+    if note:
+        print(note)
+
+
 # --------------------------------------------------------------------- gate
 
 # --- UserPromptSubmit reminder hook (F-046) --------------------------------

package/skills/agentic-sdlc-skill/templates.md

@@ -571,7 +571,7 @@ Written only by the coordinating session (`coordination.md` §2); append-only.
 ```markdown
 # Leases
 
-Coordinator named in `REQUEST_[unit].md#R<n>`.
+coordinator coordinating session — REQUEST_[unit].md#R<n> — YYYY-MM-DD
 
 take dev-container — wave-6 session — YYYY-MM-DD
 release dev-container — wave-6 session — YYYY-MM-DD
@@ -592,6 +592,7 @@ committed. Each item is a list line whose first code span is the path.
 
 ## Shared
 - `ai_docs/audit/reviews/REVIEW_LOG.md` — F-001, F-002
+- `.devpnt/plans/plans.db` — F-001, F-002 (written by devPNT)
 
 ## Regenerated
 - `ai_docs/INDEX.md`
@@ -809,7 +810,7 @@ Concurrent reviews: `init` writes a `.gitattributes` stanza giving this file
 Rows are date-stamped and their order carries no meaning, so a union merge keeps
 both sides instead of asking a human to choose. It is defence in depth: without
 git, or without the stanza, the outcome is today's — one conflict you resolve by
-hand, never a lost row.
+hand, never a lost row. `check` names a missing stanza and the line to add (F-090).
 
 
 ## ai_docs/audit/HANDOFF_[feature].md — one open workstream, its own file