@jenga-ai/agent 1.1.0 → 1.2.0

package/skills/jenga/scripts/resolve-id.sh

@@ -0,0 +1,367 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# skills/jenga/scripts/resolve-id.sh
+#
+# Deterministic fuzzy-ID grammar parser and board-backed resolver for
+# `/jenga`'s interactive scope-selection flow (E45). Given the raw,
+# comma-separated ID string a user typed for `/jenga <ids>` (or IDs
+# translated back from picker selection numbers), this script parses each
+# comma-delimited segment per the exact grammar negotiated with the user,
+# then resolves the parsed candidate against the real board inventory
+# produced by `skills/jenga/scripts/board-scan.sh` (E45_S01_T01).
+#
+# This script NEVER re-scans the board independently — it invokes
+# board-scan.sh as a subprocess and reads its JSON stdout as the single
+# source of truth for what IDs actually exist. See board-scan.sh's own
+# header comment for its output schema.
+#
+# ---------------------------------------------------------------------------
+# GRAMMAR (final — negotiated with the user, do not reinterpret)
+# ---------------------------------------------------------------------------
+#   1. Strip whitespace, underscores, and punctuation from the input;
+#      uppercase it. Only [A-Z0-9] characters survive this step.
+#   2. Split each contiguous digit run into 2-digit chunks, left to right.
+#      A digit run whose length is not a multiple of 2 is REJECTED as
+#      invalid input (never silently truncated or padded).
+#   3. A chunk is TAGGED to a level (epic/story/task) when the digit run it
+#      came from is immediately adjacent — directly before or directly
+#      after, no separator survives step 1 — to a single E/S/T letter.
+#   4. Untagged chunks fill the remaining levels positionally, in
+#      epic -> story -> task order, left to right, skipping any level
+#      already claimed by an explicit tag.
+#   5. The parsed candidate (full or partial) is resolved against the board
+#      inventory. A partial ID that does not uniquely resolve (e.g. a story
+#      chunk with no epic tag, when multiple epics share that story number)
+#      is REJECTED and reports that disambiguation is required — never
+#      guessed across epics.
+#
+# Negotiated examples (must resolve exactly as documented):
+#   "E01s02"        -> E01_S02
+#   "e01 S04 t02"   -> E01_S04_T02
+#   "0103"          -> E01_S03   (two untagged chunks: epic=01, story=03)
+#
+# ---------------------------------------------------------------------------
+# USAGE
+# ---------------------------------------------------------------------------
+#   skills/jenga/scripts/resolve-id.sh "<comma-separated raw ID list>"
+#
+# Example:
+#   skills/jenga/scripts/resolve-id.sh "E01s02, e01 S04 t02, 0103"
+#
+# Each comma-delimited segment of the argument is parsed and resolved
+# independently. Whitespace around commas is insignificant (stripped by the
+# grammar itself in step 1, since spaces are whitespace).
+#
+# ---------------------------------------------------------------------------
+# OUTPUT SCHEMA
+# ---------------------------------------------------------------------------
+# stdout is a single JSON array, one object per input segment, in input
+# order. Nothing else is ever written to stdout.
+#
+#   {
+#     "input":       "E01s02",       // the raw segment exactly as given
+#     "status":      "resolved" | "rejected",
+#     "resolved_id": "E01_S02" | null,
+#     "reason":      null | "<human-readable rejection reason>"
+#   }
+#
+# Rejection reasons include (not exhaustive, always human-readable):
+#   - "empty input after stripping whitespace/underscores/punctuation"
+#   - "malformed digit run: '<run>' has odd length <n> (not a multiple of 2)"
+#   - "too many untagged chunks: <n> chunks but only <m> open level(s)"
+#   - "no ID chunks found in input"
+#   - "conflicting tags: level '<L>' tagged more than once"
+#   - "not found on board: <id-or-partial-description>"
+#   - "ambiguous partial ID '<partial>': matches <n> candidates
+#      (<id1>, <id2>, ...) - disambiguation required"
+#
+# ---------------------------------------------------------------------------
+# EXIT CODES
+# ---------------------------------------------------------------------------
+#   0   every segment resolved
+#   1   at least one segment was rejected (stdout is still valid JSON;
+#       callers should inspect each element's "status", not rely on the
+#       exit code alone to know WHICH segment failed)
+#   2   usage error (no argument given) or board-scan.sh / python3 failure
+#       — a real setup problem, not a per-segment parse failure
+#
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Unlike board-scan.sh, this script never reads project/board/ directly —
+# it only needs SCRIPT_DIR to locate and invoke board-scan.sh, which does
+# its own JENGA_PROJECT_DIR resolution internally. No project-root
+# resolution is needed here.
+BOARD_SCAN="$SCRIPT_DIR/board-scan.sh"
+
+if [ $# -lt 1 ] || [ -z "${1:-}" ]; then
+  echo 'Usage: resolve-id.sh "<comma-separated raw ID list>"' >&2
+  exit 2
+fi
+
+RAW_INPUT="$1"
+
+if [ ! -x "$BOARD_SCAN" ]; then
+  echo "Error: board-scan.sh not found or not executable at $BOARD_SCAN" >&2
+  exit 2
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "Error: python3 is required by resolve-id.sh" >&2
+  exit 2
+fi
+
+# Capture the board inventory ONCE for this whole run — every segment is
+# resolved against the same snapshot, and we never re-scan per segment.
+BOARD_JSON="$("$BOARD_SCAN")" || {
+  echo "Error: board-scan.sh failed" >&2
+  exit 2
+}
+
+# The parsing/resolution logic is written to a temp .py file rather than
+# piped in via `python3 -` because the board JSON is delivered on stdin —
+# `python3 -` would consume stdin itself as the script source, leaving
+# nothing for the script's own sys.stdin.read() to see.
+PY_SCRIPT="$(mktemp -t resolve-id-XXXXXX.py)"
+trap 'rm -f "$PY_SCRIPT"' EXIT
+
+cat > "$PY_SCRIPT" <<'PY'
+import json
+import re
+import sys
+
+raw_input = sys.argv[1]
+board_json = sys.stdin.read()
+
+try:
+    board = json.loads(board_json)
+except Exception as e:
+    print(f"Error: could not parse board-scan.sh output as JSON: {e}", file=sys.stderr)
+    sys.exit(2)
+
+LEVELS = ("epic", "story", "task")
+LEVEL_LETTER = {"epic": "E", "story": "S", "task": "T"}
+LETTER_LEVEL = {"E": "epic", "S": "story", "T": "task"}
+
+
+def strip_and_upper(segment):
+    """Grammar step 1: strip whitespace/underscores/punctuation, uppercase.
+    Only [A-Za-z0-9] survives."""
+    return re.sub(r"[^A-Za-z0-9]", "", segment).upper()
+
+
+def tokenize(cleaned):
+    """Split the cleaned string into an ordered list of
+    (kind, value) tokens where kind is 'digits' or 'letters', preserving
+    adjacency (walks left to right, alternating runs)."""
+    tokens = []
+    for m in re.finditer(r"[0-9]+|[A-Z]+", cleaned):
+        val = m.group(0)
+        kind = "digits" if val.isdigit() else "letters"
+        tokens.append((kind, val))
+    return tokens
+
+
+class RejectError(Exception):
+    def __init__(self, reason):
+        self.reason = reason
+
+
+def parse_segment(cleaned):
+    """Returns a dict {level: '01'} chunk map (2-digit strings) covering
+    only the levels present in this candidate. Raises RejectError on any
+    grammar violation."""
+    if not cleaned:
+        raise RejectError("empty input after stripping whitespace/underscores/punctuation")
+
+    tokens = tokenize(cleaned)
+
+    digit_positions = [i for i, (kind, _) in enumerate(tokens) if kind == "digits"]
+    if not digit_positions:
+        raise RejectError("no ID chunks found in input")
+
+    # Expand every digit run into its 2-digit chunks (grammar step 2),
+    # rejecting any run whose length isn't a multiple of 2. Each run keeps
+    # its own ordered list of chunk dicts: {"value": "01", "tag": None}.
+    runs = []  # list of {"token_pos": i, "chunks": [chunk_dict, ...]}
+    for pos in digit_positions:
+        run = tokens[pos][1]
+        if len(run) % 2 != 0:
+            raise RejectError(
+                f"malformed digit run: '{run}' has odd length {len(run)} "
+                "(not a multiple of 2)"
+            )
+        run_chunks = [{"value": run[i:i + 2], "tag": None} for i in range(0, len(run), 2)]
+        runs.append({"token_pos": pos, "chunks": run_chunks})
+
+    run_by_token_pos = {r["token_pos"]: r for r in runs}
+
+    # Tag assignment (grammar step 3), one pass over LETTER tokens. A tag
+    # letter run must be a SINGLE E/S/T letter — a multi-letter run, or a
+    # letter that isn't E/S/T, is not a valid tag and is ignored (treated
+    # as noise, not a rejection).
+    #
+    # Adjacency priority when a single tag letter sits BETWEEN two digit
+    # runs (e.g. "E01S02" — the 'S' is simultaneously "after 01" and
+    # "before 02"): the letter tags the FOLLOWING run's FIRST chunk, never
+    # the preceding run's last chunk. This is what makes the negotiated
+    # examples parse correctly — "E01s02" reads as E=epic(01), S=story(02),
+    # not as a conflict between the two adjacencies of the same 'S'. A
+    # trailing letter with NO digit run after it (a true suffix tag, e.g.
+    # "0102T" with nothing following the T) falls back to tagging the
+    # PRECEDING run's LAST chunk, since there is no following run to prefer.
+    for i, (kind, val) in enumerate(tokens):
+        if kind != "letters" or len(val) != 1 or val not in LETTER_LEVEL:
+            continue
+        level = LETTER_LEVEL[val]
+
+        target_chunk = None
+        if i + 1 < len(tokens) and tokens[i + 1][0] == "digits":
+            target_chunk = run_by_token_pos[i + 1]["chunks"][0]
+        elif i - 1 >= 0 and tokens[i - 1][0] == "digits":
+            target_chunk = run_by_token_pos[i - 1]["chunks"][-1]
+
+        if target_chunk is None:
+            continue
+
+        if target_chunk["tag"] is not None and target_chunk["tag"] != level:
+            raise RejectError(
+                f"conflicting tags around chunk '{target_chunk['value']}': "
+                f"adjacent to both {LEVEL_LETTER[target_chunk['tag']]} and {val}"
+            )
+        target_chunk["tag"] = level
+
+    chunks = [c for r in runs for c in r["chunks"]]
+
+    # Assign tagged chunks to their levels, rejecting duplicate tags for the
+    # same level (grammar step 3/4) — e.g. two separate digit runs both
+    # tagged 'E'.
+    result = {}
+    tagged_chunks = [c for c in chunks if c["tag"] is not None]
+    untagged_chunks = [c for c in chunks if c["tag"] is None]
+
+    for c in tagged_chunks:
+        level = c["tag"]
+        if level in result:
+            raise RejectError(
+                f"conflicting tags: level '{LEVEL_LETTER[level]}' tagged more than once"
+            )
+        result[level] = c["value"]
+
+    # Untagged chunks fill remaining levels positionally, epic -> story ->
+    # task, left to right, skipping levels already claimed by a tag.
+    open_levels = [lvl for lvl in LEVELS if lvl not in result]
+    if len(untagged_chunks) > len(open_levels):
+        raise RejectError(
+            f"too many untagged chunks: {len(untagged_chunks)} chunks but "
+            f"only {len(open_levels)} open level(s)"
+        )
+    for c, level in zip(untagged_chunks, open_levels):
+        result[level] = c["value"]
+
+    return result
+
+
+def candidate_id_fragments(level_map):
+    """Given {'epic': '01', 'story': '02'}, produce per-level ID fragments
+    ('epic': 'E01', 'story': 'S02', ...) used for board matching."""
+    return {lvl: f"{LEVEL_LETTER[lvl]}{val}" for lvl, val in level_map.items()}
+
+
+def item_levels(item_id):
+    """Split a board id like 'E01_S02_T03' into {'epic': 'E01', ...}."""
+    parts = item_id.split("_")
+    levels = {}
+    if len(parts) >= 1 and parts[0].startswith("E"):
+        levels["epic"] = parts[0]
+    if len(parts) >= 2 and parts[1].startswith("S"):
+        levels["story"] = parts[1]
+    if len(parts) >= 3 and parts[2].startswith("T"):
+        levels["task"] = parts[2]
+    return levels
+
+
+def resolve_against_board(level_map, board):
+    """Resolve a parsed level_map against the board inventory. Returns
+    (resolved_id, None) on unique success, or (None, reason) on failure.
+
+    The candidate's TYPE is the deepest level present in level_map (e.g.
+    {epic, story} targets a story, {epic, story, task} targets a task,
+    {story} alone still targets a story — just an under-specified one).
+    Restricting the match to items of exactly that `type` (the field
+    board-scan.sh already emits) is what keeps a story-level candidate
+    like "0103" (epic=01, story=03, no task) resolving to the STORY
+    'E01_S03' itself rather than colliding with every task underneath it —
+    without this restriction, a levels-only filter would also match
+    'E01_S03_T01', 'E01_S03_T02', etc., since they share the same
+    epic/story numbers.
+
+    For a genuinely partial candidate missing shallower levels (e.g. only
+    a story chunk with no epic tag), the same type-restricted filter
+    naturally requires uniqueness ACROSS epics, which is exactly the
+    disambiguation guarantee the grammar spec requires."""
+    if not level_map:
+        return None, "no ID chunks found in input"
+
+    frag = candidate_id_fragments(level_map)
+    deepest = max(level_map.keys(), key=LEVELS.index)
+
+    def matches(item):
+        if item.get("type") != deepest:
+            return False
+        levels = item_levels(item.get("id", ""))
+        for lvl, want in frag.items():
+            if levels.get(lvl) != want:
+                return False
+        return True
+
+    matches_list = [item for item in board if matches(item)]
+
+    partial_desc = ", ".join(f"{lvl}={v}" for lvl, v in frag.items())
+
+    if len(matches_list) == 1:
+        return matches_list[0]["id"], None
+    if len(matches_list) == 0:
+        return None, f"not found on board: {partial_desc}"
+
+    ids = sorted(m["id"] for m in matches_list)
+    preview = ", ".join(ids[:8]) + (", ..." if len(ids) > 8 else "")
+    return None, (
+        f"ambiguous partial ID '{partial_desc}': matches {len(matches_list)} "
+        f"candidates ({preview}) - disambiguation required"
+    )
+
+
+results = []
+any_rejected = False
+
+segments = raw_input.split(",") if raw_input.strip() != "" else []
+
+for raw_segment in segments:
+    entry = {"input": raw_segment, "status": None, "resolved_id": None, "reason": None}
+    try:
+        cleaned = strip_and_upper(raw_segment)
+        level_map = parse_segment(cleaned)
+        resolved_id, reason = resolve_against_board(level_map, board)
+        if resolved_id is not None:
+            entry["status"] = "resolved"
+            entry["resolved_id"] = resolved_id
+        else:
+            entry["status"] = "rejected"
+            entry["reason"] = reason
+            any_rejected = True
+    except RejectError as e:
+        entry["status"] = "rejected"
+        entry["reason"] = e.reason
+        any_rejected = True
+    results.append(entry)
+
+print(json.dumps(results, indent=2))
+sys.exit(1 if any_rejected else 0)
+PY
+
+python3 "$PY_SCRIPT" "$RAW_INPUT" <<< "$BOARD_JSON"
+exit $?

package/skills/jenga-permission-level/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: jenga-permission-level
+description: Report or switch the current session's 5-tier permission level (Locked/Guarded/Standard/Elevated/Unrestricted) without hand-editing settings.json.
+keywords:
+  - "permission level"
+  - "permission"
+  - "session level"
+  - "jenga permission level"
+examples:
+  - "what permission level am I at?"
+  - "switch to permission level 4"
+  - "set permission level to elevated"
+  - "lock down permissions"
+  - "unlock full permissions for this session"
+---
+
+# jenga-permission-level — Report or Switch Session Permission Level
+
+## Purpose
+
+`/jenga-permission-level [1-5]` reports or switches the current session's permission level:
+
+| Level | Name | Notes |
+|-------|------|-------|
+| 1 | Locked | |
+| 2 | Guarded | Conceptual default — always reported as `Default: 2`, no matter the current session level. |
+| 3 | Standard | |
+| 4 | Elevated | |
+| 5 | Unrestricted | |
+
+`defaultMode` stays `acceptEdits` at every level; only the `permissions` block changes. Levels are backed by template files at `templates/permission-levels/level-<n>-<name>.json`, e.g. `templates/permission-levels/level-4-elevated.json` (naming convention: `<name>` is the lowercase level name from the table above — Locked/Guarded/Standard/Elevated/Unrestricted). Those templates are owned by story E33_S01 and are the input the switch script (see below) copies from.
+
+---
+
+## Instructions
+
+### 1. No argument — report status
+
+Read `.jenga-permission-level.json` at the repo root. Treat a missing file, or a missing/unparseable `session_level` field, as `session_level: 2`.
+
+Run:
+
+```bash
+n=$(jq -r '.session_level // 2' .jenga-permission-level.json 2>/dev/null || echo 2)
+echo "Default: 2 / Session: $n"
+```
+
+Print exactly `Default: 2 / Session: <n>` (e.g. `Default: 2 / Session: 4`). Do not write any files in this path.
+
+### 2. Argument `<n>` provided — validate
+
+Before doing anything else, validate the argument:
+
+- It must match `^[1-5]$` (a single digit, 1 through 5).
+- If it does not match — including non-numeric input, decimals, negative numbers, `0`, or `6` and above — **stop immediately**, print a clear error (e.g. `Error: permission level must be an integer between 1 and 5, got '<input>'`), and make **no file changes**. Do not invoke the switch script.
+
+### 3. Argument `<n>` valid — delegate to the switch script
+
+Do not inline the copy/update logic here — per this repo's scripts-over-inline-logic convention, the switch is owned entirely by a dedicated script:
+
+```bash
+bash scripts/jenga-permission-level-switch.sh <n>
+```
+
+This script (created by a separate task, E33_S02_T02) is responsible for:
+- Copying `templates/permission-levels/level-<n>-<name>.json` over both `.claude/settings.json` and `.agents/settings.json` as a **whole-file overwrite** — not a merge of the `permissions` block alone. Two fields vary by level and are expected to change on a switch: `permissions.deny` and `autoMode.allow`. All 5 templates carry byte-identical `defaultMode`, `env`, `hooks`, and `permissions.allow`; that invariant is what keeps the overwrite safe. Two consequences follow: any top-level key present in a destination file but absent from the templates is **silently dropped** by a switch, and any future per-level difference in `defaultMode`/`env`/`hooks` would take effect without warning. Keep the templates in sync with root `settings.json` for everything except those two varying fields.
+- Creating or updating `.jenga-permission-level.json` at the repo root to `{"session_level": <n>}`.
+
+Relay the script's stdout to the user and honor its exit code:
+- Exit code `0` — report success, e.g. `Switched to level <n> (<name>).`
+- Non-zero exit code — report the script's error output verbatim and treat the switch as failed; do not claim success.
+
+If `scripts/jenga-permission-level-switch.sh` does not exist yet (e.g. E33_S02_T02 has not landed), report that clearly as a missing dependency rather than attempting to reimplement its logic inline.
+
+### Session End
+
+When this skill's session concludes, emit the following signal on its own line so the Jenga Router clears the active session:
+
+```
+[JENGA:SESSION_END:jenga-permission-level]
+```

package/skills/proceed/SKILL.md

@@ -23,7 +23,7 @@ metadata:
 
 3. **Determine the next action**:
    - If there are tasks in `Pending` or `In Progress` status that have not yet been assigned to the developer, identify them.
-   - If outstanding tasks are ready for implementation, write a session handoff to `project/queue/.session_handoff.json` with `"status": "planning_complete"` so that `on_session_end.sh` routes them to the developer queue.
+   - If outstanding tasks are ready for implementation, write a session handoff to `project/queue/handoffs/scrum-master-<session_id>-<task_id>.json` (per-session path — see `templates/SCRUM_BOARD_SCHEMA.md`'s `handoffs/` section; use the first task ID, or `batch` if several) with `"status": "planning_complete"` so that `on_session_end.sh` routes them to the developer queue.
    - If all tasks are complete, check for epic/story rollup and update board statuses accordingly.
 
 4. **Report** a clear summary to the user: what is done, what is in progress, what is next — and which agent will handle it.

package/skills/publish/SKILL.md

@@ -77,7 +77,7 @@ If config or env validation fails, the skill exits with code `4` and does not co
 | `/publish setup` | Prepare or refresh target configuration | `skills/publish/scripts/setup_wizard.sh` | Supported types: `mobile-ios`, `npm`, `npm-ci`, `droplet` |
 | `/publish deploy` | Run the full 11-step deploy orchestration | `skills/publish/scripts/publish_deploy.sh` | Dispatches to the adapter for the target's `type` (`mobile-ios`, `npm`, `npm-ci`, or `droplet`); `--dry-run` is honoured end-to-end |
 | `/publish history` | Read the canonical publish ledger | `skills/publish/scripts/show_history.sh` | Target-agnostic; filter by `--target <name>` |
-| `/publish release-notes` | Generate release notes without publishing | `skills/publish/scripts/generate_release_notes.sh` | Target-agnostic |
+| `/publish release-notes` | Merge new release notes into the standing `CHANGELOG.md` (or a standalone draft via `--output`) without publishing | `skills/publish/scripts/generate_release_notes.sh` | Target-agnostic |
 
 ## Quality Gate Policy
 
@@ -131,7 +131,7 @@ Example invocations:
 ### `/publish deploy`
 
 ```text
-/publish deploy [--target <name>] [--config <path>] [--yes] [--dry-run] [--minor | --major] [--release-notes <path>]
+/publish deploy [--target <name>] [--config <path>] [--yes] [--dry-run] [--minor | --major] [--notes-file <path>]
 ```
 
 Implementation: `bash skills/publish/scripts/publish_deploy.sh [flags...]`
@@ -142,12 +142,12 @@ Deploy flow:
 3. Validate target environment variables
 4. Print a best-effort scrum-board summary since the last publish tag
 5. Run pre-deploy gates
-6. Generate a release-note draft and review it unless `--yes` is set
+6. Update the standing `CHANGELOG.md`'s `[Unreleased]` section with new entries since the last publish tag (or use the caller-supplied file instead, when release notes are supplied via the bypass flag), and review it unless `--yes` is set
 7. Suggest and confirm the semver bump (`patch` by default in non-interactive mode unless `--minor` or `--major` is passed)
 8. Print final confirmation: `Deploy v<x.y.z> to <target>? [y/N]`
 9. Execute the adapter pipeline for the target's `type` (`ios_pipeline.sh` for `mobile-ios`, `npm_pipeline.sh` for `npm`, `npm_ci_pipeline.sh` for `npm-ci`, `droplet_pipeline.sh` for `droplet`)
 10. Run post-deploy gates and downgrade the ledger state to `partial` on failure
-11. Append the publish ledger entry, create the git tag (unless `--dry-run`), and print post-deploy manual steps
+11. Finalize `CHANGELOG.md` — stamp `[Unreleased]` to a versioned, dated entry and open a fresh empty `[Unreleased]` above it (skipped on `--dry-run`, and skipped when release notes were supplied via the bypass flag, since there is then no standing-file `[Unreleased]` section to finalize) — then append the publish ledger entry, create the git tag (unless `--dry-run`), and print post-deploy manual steps
 
 Non-interactive rule: when `--yes` is used, deploy must not auto-run setup after a failure. It exits `4` and surfaces the missing fields.
 
@@ -188,8 +188,11 @@ Implementation: `bash skills/publish/scripts/generate_release_notes.sh [--target
 
 Release-note rules:
 - The last publish tag is the highest semver tag on the current branch that also has a matching ledger entry in `project/logs/publish-history.json`.
-- If no prior ledger-backed tag exists, the draft includes `> First release — full history included`.
+- **Default target (no `--output`):** the repo-root `CHANGELOG.md` — created from `templates/CHANGELOG_TEMPLATE.md` first if it doesn't exist yet (backward-compat for projects scaffolded before this convention). New Features/Bug Fixes/Other/Completed-task entries since the last publish tag are appended under the existing `## [Unreleased]` heading's subsections; everything else in the file (prior versioned entries, manual edits) is preserved. Entries already present are deduped (matched by commit short-sha or task id), so re-running with no new commits produces zero diff.
+- **`--output <path>`:** writes a standalone, disposable draft to that path instead (the pre-E36 behavior) — `CHANGELOG.md` is not touched in this mode.
+- If no prior ledger-backed tag exists, a `--output` draft includes `> First release — full history included`; the standing `CHANGELOG.md` merge mode has no equivalent banner (it just merges full history into `[Unreleased]` like any other run).
 - Scrum-board enrichment is best-effort only; missing or unreadable board data never fails the command.
+- **`.publicignore` filtering:** when a repo-root `.publicignore` exists (the blocklist `/mirror-public` also reads), a candidate commit — or a completed task's associated commit(s), matched via the `task(E##_S##_T##):` commit-message convention — is dropped entirely when every changed file it touches is covered by that blocklist. A commit touching a mix of blocked and unblocked files is still logged normally; only full coverage excludes an entry. This exists because `CHANGELOG.md` itself is not blocklisted and ships to the public mirror, so an unfiltered entry referencing a private-only path (e.g. `project/board/`) would leak. Absent `.publicignore`, this is a strict no-op — unchanged from pre-E36_S02_T02 behavior. Matching reuses `skills/mirror-public/scripts/mirror.sh`'s `rsync --exclude-from` evaluation rather than a separate glob implementation, so a path classified "blocked" by `/mirror-public --dry-run` is classified "blocked" here too.
 
 ## Ledger & Tagging
 

package/skills/publish/assets/ci-contract.md

@@ -18,7 +18,7 @@ Every `/publish` invocation must perform these steps before command-specific wor
 | Select deploy target | `--target <name>` | `PUBLISH_TARGET` | Yes | Flag takes precedence over env var |
 | Skip confirmation prompts | `--yes` | `PUBLISH_YES` | Yes | Env var truthy values: `1`, `true`, `yes`, `on` |
 | Override config path | `--config <path>` | — | No | Defaults to `project/configs/publish.json` |
-| Reuse prepared release notes | `--release-notes <path>` | — | No | Reserved for later release-note flow |
+| Reuse prepared release notes | `--notes-file <path>` | — | No | Live: bypasses generation entirely and uses the supplied file directly, instead of the standing `CHANGELOG.md` flow |
 | Dry-run execution | `--dry-run` | `PUBLISH_DRY_RUN` | No | Prints allowlisted `xcodebuild` / `xcrun` commands without executing them |
 
 ## Required contract
@@ -58,7 +58,7 @@ These run only after the mandatory global gates succeed.
 These inputs remain optional in non-interactive mode:
 
 - `--config <path>` when the default config exists
-- `--release-notes <path>`
+- `--notes-file <path>`
 - `--from-tag` and `--to-ref` on `/publish release-notes`
 
 ## Exit codes

package/skills/publish/assets/ownership-matrix.md

@@ -8,7 +8,7 @@ The `/publish` skill is initiated by the operator running the CLI, but each acti
 | `/publish deploy --target staging` | Initiates | May run as part of test cycle | Never directly |
 | `/publish deploy --target production` | Initiates with explicit confirmation | Reviews ledger entry post-deploy | Reviews `/status` only |
 | `/publish history` | Reads for context | Reads for test baseline | Reads in `/status` review |
-| `/publish release-notes` | Generates and reviews draft | May read draft for test context | Reviews content for sprint summary |
+| `/publish release-notes` | Updates and reviews CHANGELOG.md `[Unreleased]` | May read CHANGELOG.md for test context | Reviews content for sprint summary |
 | Gate failure resolution | Owns rework | Validates rework | Escalates if blocked |
 | Ledger entry disputes | Never modifies | Never modifies | Flags as rapport; human resolves |
 

package/skills/publish/scripts/finalize_changelog.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/publish_common.sh"
+
+usage() {
+  cat <<'USAGE'
+Usage: finalize_changelog.sh <version> [<changelog_path>]
+
+Stamps the standing CHANGELOG.md's `## [Unreleased]` heading into a dated,
+versioned heading (`## [<version>] — <date>`) and inserts a fresh, empty
+`## [Unreleased]` section directly above it, matching
+templates/CHANGELOG_TEMPLATE.md's subsection structure
+(### Features / ### Bug Fixes / ### Other).
+
+<changelog_path> defaults to <repo-root>/CHANGELOG.md.
+
+This is a one-shot finalize step, meant to run once per confirmed deploy,
+after the semver bump is confirmed and before the release is recorded to
+the publish ledger. It does not merge or classify entries — that is
+generate_release_notes.sh's job, run earlier in the deploy pipeline.
+USAGE
+}
+
+[[ $# -ge 1 ]] || { usage >&2; exit 1; }
+VERSION_RAW="$1"
+CHANGELOG_PATH="${2:-$PUBLISH_REPO_ROOT/CHANGELOG.md}"
+
+VERSION="$(publish_normalize_version "$VERSION_RAW")" || {
+  echo "finalize_changelog.sh: invalid version '$VERSION_RAW'." >&2
+  exit 1
+}
+
+[[ -f "$CHANGELOG_PATH" ]] || {
+  echo "finalize_changelog.sh: changelog not found at '$CHANGELOG_PATH'." >&2
+  exit 1
+}
+
+TODAY="$(date -u +"%Y-%m-%d")"
+
+# ---------------------------------------------------------------------------
+# Plain indexed-array line editing, matching generate_release_notes.sh's
+# bash 3.2 convention (no mapfile/declare -A/local -n; the stock macOS
+# default shell lacks all three). Zero-element array expansions are guarded
+# with explicit count checks before use under `set -u`, same as that file.
+# ---------------------------------------------------------------------------
+
+CL_LINES=()
+
+_cl_load() {
+  CL_LINES=()
+  local line
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    CL_LINES+=("$line")
+  done < "$1"
+}
+
+_cl_save() {
+  if (( ${#CL_LINES[@]} > 0 )); then
+    printf '%s\n' "${CL_LINES[@]}" > "$1"
+  else
+    : > "$1"
+  fi
+}
+
+_cl_load "$CHANGELOG_PATH"
+
+UNRELEASED_INDEX=-1
+CL_LINE_COUNT=${#CL_LINES[@]}
+i=0
+while (( i < CL_LINE_COUNT )); do
+  if [[ "${CL_LINES[$i]}" == "## [Unreleased]" ]]; then
+    UNRELEASED_INDEX=$i
+    break
+  fi
+  i=$((i + 1))
+done
+
+if (( UNRELEASED_INDEX < 0 )); then
+  echo "finalize_changelog.sh: '## [Unreleased]' section not found in $CHANGELOG_PATH — nothing to finalize." >&2
+  exit 1
+fi
+
+# Stamp the located heading in place.
+CL_LINES[UNRELEASED_INDEX]="## [$VERSION] — $TODAY"
+
+BEFORE=()
+AFTER=()
+if (( UNRELEASED_INDEX > 0 )); then
+  BEFORE=("${CL_LINES[@]:0:UNRELEASED_INDEX}")
+fi
+AFTER=("${CL_LINES[@]:UNRELEASED_INDEX}")
+
+FRESH_UNRELEASED=(
+  "## [Unreleased]"
+  ""
+  "### Features"
+  ""
+  "### Bug Fixes"
+  ""
+  "### Other"
+  ""
+)
+
+CL_LINES=()
+if (( ${#BEFORE[@]} > 0 )); then
+  CL_LINES+=("${BEFORE[@]}")
+fi
+CL_LINES+=("${FRESH_UNRELEASED[@]}")
+CL_LINES+=("${AFTER[@]}")
+
+_cl_save "$CHANGELOG_PATH"
+
+printf '🏷️  CHANGELOG.md finalized: [Unreleased] stamped as [%s] — %s\n' "$VERSION" "$TODAY"