@jenga-ai/agent 1.3.0 → 3.0.0

package/skills/{do → j-do}/SKILL.md

@@ -1,21 +1,36 @@
 ---
-name: do
-description: Execute tasks from the scrum board. Reads from project/todo.md, resolves each entry to its full scrum board context, and drives the developer agent through implementation with the correct sender object and communication contract. Loops until all selected tasks are done or the user exits.
+name: j.do
+description: Polyfill alias of the do skill under a collision-safe directory name. Identical behavior to /do — Execute tasks from the scrum board. Reads from project/todo.md, resolves each entry to its full scrum board context, and drives the developer agent through implementation with the correct sender object and communication contract. Loops until all selected tasks are done or the user exits. Use when the bare /do form is shadowed by another tool's own built-in command of the same name.
 keywords:
   - do
   - execute
   - implement
   - work on
   - build
+  - j-do
+  - polyfill
 examples:
   - "implement the login feature"
   - "work on the API endpoint"
+  - "j-do"
 metadata: 
   prefered_agent: developer
 ---
 
 # Do — Execute Scrum Board Tasks
 
+This skill is a literal-directory-name duplicate of `skills/do/`. It exists so that `/j-do` (and `j.j-do`) give a guaranteed-unshadowed way to reach the same flow as `/do`, even if a host tool's own built-in command of the same name would otherwise shadow or override the bare `/do` alias (Claude Code's native skill resolution is a literal-string, directory-name-based match — see `docs/skill-authoring.md`'s "Invocation Convention").
+
+This file is generated/synced by `scripts/generate-j-alias.sh do` from `skills/do/SKILL.md` — do not hand-edit it; re-run the generator instead to pick up source changes.
+
+## `--trivial` Flag
+
+**Syntax:** `/do <id> --trivial` — a dispatch-time override, distinct from `/todo --trivial` (a creation-time flag documented in `skills/todo/SKILL.md`). Where `/todo --trivial` writes a brand-new task straight to `execution_scope: inline`, `/do <id> --trivial` overrides an **already-existing** task's `execution_scope` — whatever it currently is, including absent (legacy tasks with no execution-scope fields at all) — to `inline` at the moment it's dispatched. See `### 4.1.5. \`--trivial\` Dispatch-Time Override` below for the full mechanics.
+
+**No softer fallback tier — hard fallback to the full pipeline instead.** Unlike `light` scope (which sits between `inline` and `task`), `--trivial` always forces `inline` directly, with no intermediate tier to fall back to first. To compensate, a `--trivial`-forced run that fails `scripts/smoke-harness.sh` or shows detected scope creep mid-run automatically re-routes to the full `task` pipeline (worktree + developer + tester) via the same `#### Fallback to Full Task-Scope Pipeline` procedure the `light`-tier fallback uses — see `### 4.2`'s failure-handling branches and the shared Fallback subsection under `### 4.3`.
+
+**Human-only, same as `/todo --trivial`.** `--trivial` is invoked by a human typing `/do <id> --trivial` — it is never applied autonomously by `/jenga` or the scrum-master's own breakdown/dispatch passes.
+
 ## Instructions
 
 ### 0. Load threshold config
@@ -166,7 +181,7 @@ After acquiring the epic lock and before writing the bundle manifest, scan all o
 
       1. **Extract expected files** from the task's frontmatter field `scope_rationale` and from the task's `## Description` section. Use a best-effort prose heuristic: split the text on whitespace and punctuation, then retain any token that either (a) contains a `/` character or (b) matches the pattern `*.*` (a dot surrounded by non-dot characters on both sides, e.g. `SKILL.md`, `foo.json`). Collect all retained tokens into a set called `expected_files`. This is intentionally permissive — false positives (expected files that were never actually changed) are acceptable and produce no report.
 
-      2. **Compute unexpected files**: let `actual_files` = the array stored at `task_changed_files[<task_id>]` in the bundle manifest (from step c.1). Compute `unexpected = actual_files − expected_files` (set difference: files in `actual_files` that have no match in `expected_files`). Matching is case-sensitive and exact against the relative path or the basename of the path — a token like `SKILL.md` matches any actual file whose basename is `SKILL.md` (e.g. `skills/do/SKILL.md`).
+      2. **Compute unexpected files**: let `actual_files` = the array stored at `task_changed_files[<task_id>]` in the bundle manifest (from step c.1). Compute `unexpected = actual_files − expected_files` (set difference: files in `actual_files` that have no match in `expected_files`). Matching is case-sensitive and exact against the relative path or the basename of the path — a token like `SKILL.md` matches any actual file whose basename is `SKILL.md` (e.g. `skills/j-do/SKILL.md`).
 
       3. **If `unexpected` is non-empty**:
          a. Write a Markdown conflict report to `project/queue/conflict-<task_id>.md` with the following structure:
@@ -318,9 +333,40 @@ Before invoking the developer, check whether this task was manually scoped by a
       ```
       Then proceed to step 4.2.
 
+### 4.1.5. `--trivial` Dispatch-Time Override
+
+After override validation (step 4.1) and before branching on `execution_scope` in step 4.2, check whether this invocation was `/do <id> --trivial`.
+
+1. **Detect the flag.** If the task was invoked as `/do <id>` with no `--trivial` flag, skip this entire section and proceed directly to `### 4.2`.
+
+2. **If `--trivial` is present**, read the task's current `execution_scope` from frontmatter. Treat an absent value as `task`, per the epic's backward-compatibility rule (a task that omits `execution_scope` is treated as `execution_scope: task`). Call this the **prior tier** — this covers both tasks nobody flagged as trivial at creation (an already-assigned `story`/`task`/`light` tier) and legacy tasks with no `execution_scope` set at all.
+
+3. **Overwrite `execution_scope` to `inline`** in the task's frontmatter, unconditionally — `--trivial` always forces `inline`, never a softer "lightest safe tier."
+
+4. **Record the override for audit**, reusing the existing `jenga_assigned` / `override_justification` pairing already defined in `templates/SCRUM_BOARD_SCHEMA.md` for exactly this situation ("scope overridden by a human"), rather than inventing a new field:
+   - Set `jenga_assigned: false` (if not already `false`).
+   - Set (or append to, if already present) `override_justification`:
+     ```
+     override_justification: "/do --trivial dispatch-time override on <date>: execution_scope forced from '<prior_tier>' to 'inline' by human operator."
+     ```
+   - Also set (or append to) `scope_rationale`, mirroring the phrasing convention `skills/todo/scripts/add_trivial_task.sh` already uses for the creation-time flag, so both audit fields agree on the prior tier:
+     ```
+     scope_rationale: "forced inline via /do --trivial (dispatch-time override); prior execution_scope was '<prior_tier>'"
+     ```
+   - Emit a non-fatal log line (styled like 4.2's `AUTO-CORRECTION` message):
+     ```
+     TRIVIAL OVERRIDE [<task_id>]: execution_scope forced from "<prior_tier>" to "inline" via --trivial dispatch-time override.
+     ```
+
+5. **Set an in-session marker** (this dispatch is a `--trivial`-forced run) — this does not need to be persisted to frontmatter; it only needs to survive for the remainder of this `/do` invocation. This marker is distinct from an organically-assigned `execution_scope: inline` task (one the scrum-master or `/jenga` assigned `inline` to directly, with no `--trivial` involved) because its failure handling differs — see `### 4.2`'s failure-handling steps below. Do not confuse a `--trivial`-forced run with an organic `inline` task when applying those steps.
+
+6. **Proceed to `### 4.2. Inline Execution Path`** with `execution_scope` now `inline`. Everything else about inline execution (implementation, smoke test invocation, commit convention) is identical between an organic `inline` task and a `--trivial`-forced one — only the two failure-handling branches in `### 4.2` differ, per the marker set in step 5 above.
+
+**Precedence with the locked-task dispatch guard.** If `crucial_level: locked` (checked by `### 4.2`'s locked-task dispatch guard, which always runs and always wins), `--trivial` is redundant but harmless — the task was already going to be forced `inline`. The locked-task guard's own audit fields take precedence for that correction; do not double-write conflicting `override_justification` text. A `locked` task's fallback behavior remains "halt and report," never the `--trivial` fallback below, regardless of whether `--trivial` was also passed.
+
 ### 4.2. Inline Execution Path (execution_scope: inline)
 
-After resolving the task context (step 4) and passing override validation (step 4.1), read `execution_scope` from the task frontmatter.
+After resolving the task context (step 4), passing override validation (step 4.1), and applying the `--trivial` dispatch-time override if present (step 4.1.5), read `execution_scope` from the task frontmatter.
 
 **Locked-task dispatch guard (defense-in-depth).** Before branching on `execution_scope` below, read `crucial_level` from the task frontmatter (per `templates/SCRUM_BOARD_SCHEMA.md`'s Crucial Flag Fields). If `crucial_level: locked`:
 
@@ -349,12 +395,14 @@ After resolving the task context (step 4) and passing override validation (step
      WARNING [<task_id>]: scripts/smoke-harness.sh not found. Smoke test skipped (stub pass).
      ```
 4. **If the smoke test exits non-zero**:
-   - Write `status: Failed` to the task's frontmatter.
-   - Emit:
-     ```
-     INLINE TASK FAILED [<task_id>]: smoke test returned non-zero exit code. Task marked Failed. Halting.
-     ```
-   - Do not commit. Do not proceed to the next task.
+   - **If this is a `--trivial`-forced run** (marker set in step 4.1.5 — and `crucial_level` is not `locked`, which never falls back, per 4.1.5's precedence note): do NOT write `status: Failed`. `--trivial` always forces `inline` with no softer "lightest safe tier" to fall back to first, so a smoke-harness failure here goes straight to the shared `#### Fallback to Full Task-Scope Pipeline` procedure below (origin: `trivial`). Do not proceed with the remaining inline steps below — the Fallback procedure takes over from here.
+   - **Otherwise** (an organically-assigned `inline` task, `--trivial` not involved): behavior is unchanged from before —
+     - Write `status: Failed` to the task's frontmatter.
+     - Emit:
+       ```
+       INLINE TASK FAILED [<task_id>]: smoke test returned non-zero exit code. Task marked Failed. Halting.
+       ```
+     - Do not commit. Do not proceed to the next task.
 5. **If the smoke test passes**:
    - Commit the changes using the standard commit convention (`task(<task_id>): <short description>`) via `/commit` in inline mode (E32_S04_T03).
    - Run the **Intent-vs-Diff Check** (see `### 5.1. Intent-vs-Diff Check` below) for this task.
@@ -365,9 +413,58 @@ After resolving the task context (step 4) and passing override validation (step
 7. `inline` tasks always have `needs_docs: false` — skip plan and summary documentation for the implemented task.
 8. Continue to `### 6. Verify documentation`, then `### 7. After successful completion`.
 
-If the implementation cannot be completed inline (scope is larger than anticipated), abort and re-route to the normal developer path (step 5) — unless `crucial_level: locked`, in which case do not re-route; re-attempt inline or halt and report, per the locked-task dispatch guard above.
+If the implementation cannot be completed inline (scope is larger than anticipated — detected scope creep mid-run):
+- **If this is a `--trivial`-forced run** (and `crucial_level` is not `locked`): invoke the shared `#### Fallback to Full Task-Scope Pipeline` procedure below (origin: `trivial`) — the same procedure the smoke-harness-failure branch above uses, not a second bespoke re-route.
+- **Otherwise** (an organically-assigned `inline` task): abort and re-route to the normal developer path (step 5), unchanged from before.
+- **Regardless of `--trivial`**, if `crucial_level: locked`, do not re-route via either path above; re-attempt inline or halt and report, per the locked-task dispatch guard above.
+
+**If `execution_scope` is `light`** (and `crucial_level` is not `locked` — the locked-task dispatch guard above already ran and takes precedence over any scope check), proceed to `### 4.3. Light Execution Path` below instead of step 5.
+
+**If `execution_scope` is not `inline` and not `light`** (or is absent / `task` / `story` / `epic`) **and `crucial_level` is not `locked`**, proceed to step 5 (invoke the developer agent) as normal.
+
+### 4.3. Light Execution Path (execution_scope: light)
+
+After resolving the task context (step 4), passing override validation (step 4.1), and applying the `--trivial` dispatch-time override if present (step 4.1.5 — note `--trivial` always forces `inline`, so a `light`-scoped task only reaches this section if `--trivial` was *not* passed), if `execution_scope: light` and `crucial_level` is not `locked` (per the locked-task dispatch guard in 4.2, which runs first and always wins), route the task through this path instead of the full `task`-scope pipeline in step 5.
+
+`light` sits between `inline` and `task`: unlike `inline`, it spawns a real developer subagent (so it can handle small branching logic that inline's main-session execution isn't suited for); unlike `task`, it does not create a dedicated worktree and does not invoke the tester as a separate step.
+
+1. **Spawn a developer subagent** (Agent tool, `subagent_type: "developer"`) with the same sender object and context payload as step 5 would use, but with an explicit instruction added to the dispatch prompt: **do not create a worktree** — implement directly against the current checkout (the session's existing working tree), not an isolated `.claude/worktrees/<slug>` copy. This is the one concrete difference from the step-5 `task` path: everything else about how the subagent implements the task (reading the task file, following acceptance criteria, following repo conventions) is unchanged.
+
+2. **After the developer subagent reports implementation complete**, run the smoke test harness using the same invocation convention as `### 4.2. Inline Execution Path`:
+   - Run `bash scripts/smoke-harness.sh <changed_file>...`, passing the paths the subagent changed. With no arguments the harness infers them from `git diff --name-only HEAD`. It exits `0` on pass and `1` on failure.
+   - If `scripts/smoke-harness.sh` does not exist, log a warning and treat the result as a pass:
+     ```
+     WARNING [<task_id>]: scripts/smoke-harness.sh not found. Smoke test skipped (stub pass).
+     ```
+
+3. **If the smoke test passes**:
+   - The developer subagent self-verifies the implementation against the task's acceptance criteria. No tester subagent is invoked for a `light`-scoped task — this is a deliberate, documented exception to "the tester is the sole status-writer" (`agents/tester.md`), mirroring the same exception already established for `inline` scope in step 5 of `### 4.2`. Since no tester runs, the developer/orchestrator is the one who writes the terminal status for a `light`-scoped task.
+   - Commit the changes using the standard commit convention (`task(<task_id>): <short description>`) via `/commit`.
+   - Run the **Intent-vs-Diff Check** (see `### 5.1. Intent-vs-Diff Check` below) for this task.
+   - Write `status: Passed` and `date_completed: <today>` to the task's frontmatter if self-verification passes.
+   - Remove the task from `project/todo.md`.
+   - Continue to `### 6. Verify documentation`, then `### 7. After successful completion`.
+
+4. **If the smoke test fails (non-zero exit)**: do NOT write `status: Failed` and do NOT halt. Instead, invoke `#### Fallback to Full Task-Scope Pipeline` below (origin: `light`).
+
+#### Fallback to Full Task-Scope Pipeline
 
-**If `execution_scope` is not `inline`** (or is absent / `task` / `story` / `epic`) **and `crucial_level` is not `locked`**, proceed to step 5 (invoke the developer agent) as normal.
+This is a self-contained, reusable procedure with two current callers — `### 4.2`'s `--trivial`-forced inline failure branches (origin: `trivial`) and `### 4.3`'s `light`-scope smoke-harness failure (origin: `light`) — given a task that was attempted under a reduced-overhead execution scope and failed its smoke-harness check (or, for `trivial`, showed detected scope creep mid-run), do the following. The only thing that varies by caller is the notice text in step 5; steps 1–4 and 6 are identical regardless of origin.
+
+1. **Do not mark the task `Failed`.** A smoke-harness failure (or detected scope creep) under a reduced-overhead scope means the scope was too small for the task, not that the task itself is unworkable — the correct response is to retry under full isolation, not to reject the work.
+2. **Create a worktree** for the task, named `<E##_S##_T##-short-slug>` per standard Worktree Management conventions, if one does not already exist for this task. (A task dispatched under `light` scope, or forced `inline` via `--trivial`, never had one — both premises skip worktree creation — so this step always creates a fresh worktree in that case.)
+3. **Spawn a developer subagent** in that worktree and have it pick up from the current state of the code (the changes already made by the reduced-overhead attempt are still present in the working tree / already committed, if any commit occurred — the subagent continues from there rather than starting over).
+4. **Invoke the tester agent** per the normal `### 5. Invoke the developer agent` flow's contract — full sender object, commit SHAs, worktree path. The tester is responsible for the terminal status write, exactly as in the standard `task`-scope pipeline.
+5. **Emit a clear, non-fatal fallback notice** to the user/orchestrator, using the message matching the caller's origin:
+   - origin `light`:
+     ```
+     LIGHT SCOPE FALLBACK [<task_id>]: smoke test failed; re-routing to full task-scope pipeline (worktree + developer + tester).
+     ```
+   - origin `trivial`:
+     ```
+     TRIVIAL OVERRIDE FALLBACK [<task_id>]: smoke test failed (or scope creep detected); re-routing to full task-scope pipeline (worktree + developer + tester).
+     ```
+6. Resume normal `task`-scope processing (steps 6–8 below) once the tester returns a verdict.
 
 ### 5. Invoke the developer agent
 Pass the following to the developer agent:
@@ -395,7 +492,7 @@ After the developer agent returns (or after inline execution completes), run the
 
 2. Run `git diff --name-only HEAD~1` to retrieve the list of changed file names (relative paths, one per line).
 
-3. Read the prompt template from `skills/do/assets/intent-vs-diff-prompt.md`. Extract the prompt block (the content between the triple backticks under `## Prompt`).
+3. Read the prompt template from `skills/j-do/assets/intent-vs-diff-prompt.md`. Extract the prompt block (the content between the triple backticks under `## Prompt`).
 
 4. Substitute the placeholders:
    - `{description}` — full text of the task's `## Description` section
@@ -417,7 +514,7 @@ After the developer agent returns (or after inline execution completes), run the
 
 **This check is non-blocking.** It does not change the task's Passed/Failed outcome. It only writes `divergence_flag: true` and emits a warning for human review. Execution continues regardless of the check result.
 
-**Prompt calibration:** The prompt in `skills/do/assets/intent-vs-diff-prompt.md` is tuned to flag only files with zero plausible connection to the stated task. Test files, documentation files, lock files, and clearly implied files are excluded from flagging. See the `## False-Positive Tuning Rationale` section in the prompt template for full details.
+**Prompt calibration:** The prompt in `skills/j-do/assets/intent-vs-diff-prompt.md` is tuned to flag only files with zero plausible connection to the stated task. Test files, documentation files, lock files, and clearly implied files are excluded from flagging. See the `## False-Positive Tuning Rationale` section in the prompt template for full details.
 
 ### 6. Verify documentation
 After the developer completes the task, confirm the following documentation was written:

package/skills/j-doc/README.md

@@ -0,0 +1,155 @@
+# `/doc` Authoring and Usage Guide
+
+`/doc` generates or regenerates a complete Markdown document for a resolved target path. The skill owns the entire target file: it resolves the documentation objective first, gathers evidence, reads any existing target for still-valid maintainer intent, then writes a full replacement document.
+
+## Basic Usage
+
+### Default target
+
+```text
+/doc
+```
+
+When no target is provided, `/doc` resolves the default target from `skills/j-doc/assets/path-objectives.yaml`. Today that default is `README.md`.
+
+Expected flow:
+1. Resolve `README.md`
+2. Match the `project overview` objective
+3. Gather project evidence
+4. Regenerate the full `README.md`
+
+### Custom target
+
+Canonical custom-target form:
+
+```text
+/doc docs/API.md
+```
+
+Accepted convenience form:
+
+```text
+/doc update: docs/API.md
+```
+
+Both forms resolve `docs/API.md`, then apply the matching rule from `skills/j-doc/assets/path-objectives.yaml`.
+
+## Target Resolution and Objective Rules
+
+`skills/j-doc/assets/path-objectives.yaml` is the source of truth for:
+- the default target
+- known target paths
+- each path's documentation objective
+- required and optional sections for known targets
+
+Known targets bypass ambiguity. Unknown targets must stop for clarification.
+
+## Evidence Sources and Precedence
+
+`/doc` builds a synthesis context before writing. When sources disagree, use this precedence order:
+1. explicit user instruction
+2. scrum-board context
+3. codebase evidence
+4. git history
+
+The synthesis context contract currently includes:
+- `target_path`
+- `objective`
+- `project_name`
+- `project_description`
+- `features`
+- `getting_started`
+- `board_items`
+- `conflicts_resolved`
+- `sources_used`
+- `existing_intent`
+
+Use stronger sources to break ties. Do not let weaker evidence overwrite explicit user direction.
+
+## `last_update` Provenance
+
+`last_update` is the documentation provenance field described by Epic E24's provenance work. It is intended to capture the most recent completed board item that materially updated the target document.
+
+### Expected source of truth
+
+The provenance lookup relies on scrum-board `docs: [...]` annotations that point at repo-relative documentation targets such as:
+- `README.md`
+- `docs/API.md`
+
+Board authors should add `docs` annotations to stories or tasks whenever implementation work changes a specific document or should be reflected in that document later.
+
+### How provenance is expected to resolve
+
+1. Look for completed board items whose `docs` list includes the target path exactly.
+2. Prefer the most recent qualifying item.
+3. Use that item as the basis for the document's `last_update` value.
+
+### Fallback behavior
+
+If provenance cannot be resolved, `/doc` should follow the fallback defined by E24_S05:
+- omit `last_update`, or
+- mark it as `unknown`
+
+Typical failure modes:
+- the relevant board item never declared `docs: [...]`
+- the target path in the board item does not exactly match the generated path
+- the board item exists but is not yet in a completed/passed state
+
+## Ambiguity Gate
+
+If the resolved target path is not present in `skills/j-doc/assets/path-objectives.yaml`, `/doc` must not guess.
+
+It should stop and ask exactly:
+
+```text
+What should <target_path> document? Please describe the objective.
+```
+
+### Example
+
+```text
+/doc update: docs/UNKNOWN.md
+```
+
+Expected behavior:
+- do not generate a file yet
+- do not invent a target objective
+- ask the user what `docs/UNKNOWN.md` is meant to document
+
+Once the user clarifies the objective, surface the resolved contract and continue.
+
+## Target-Specific Notes
+
+### `README.md`
+Use `/doc` with no arguments when you want to regenerate the project overview. The generated file should center on:
+- project description
+- getting started steps
+- examples only when they are strongly supported by evidence
+
+### `docs/API.md`
+Use `/doc docs/API.md` (or `/doc update: docs/API.md`) when you want an API reference document. The generated file should remain grounded in known interfaces, endpoints, parameters, return values, and errors.
+
+## Tips for Board Authors
+
+Add `docs` annotations when board work affects documentation scope or provenance. Good examples:
+
+```yaml
+docs:
+  - README.md
+  - docs/API.md
+```
+
+Use annotations when:
+- a task introduces or changes user-visible behavior that belongs in README
+- a story adds or changes an endpoint, command, interface, or workflow doc
+- you want `/doc` provenance to trace the work back to the board reliably
+
+Avoid annotations when the work has no documentation impact.
+
+## Maintainer Checklist
+
+Before relying on `/doc`, confirm that:
+1. the target path exists in `skills/j-doc/assets/path-objectives.yaml`, or you are prepared to answer the ambiguity prompt
+2. relevant board items include accurate `docs: [...]` annotations
+3. higher-priority evidence sources are up to date
+4. any existing target file content that should survive regeneration is genuinely still valid

package/skills/{doc → j-doc}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: doc
-description: Generate or update a documentation file by resolving a target path to a clear documentation objective before writing.
+name: j.doc
+description: Polyfill alias of the doc skill under a collision-safe directory name. Identical behavior to /doc — Generate or update a documentation file by resolving a target path to a clear documentation objective before writing. Use when the bare /doc form is shadowed by another tool's own built-in command of the same name.
 metadata:
   prefered_agent: developer
 keywords:
@@ -9,15 +9,23 @@ keywords:
   - write docs
   - generate docs
   - update docs
+  - j-doc
+  - polyfill
 examples:
   - "/doc"
   - "/doc docs/API.md"
+  - "/doc update: docs/API.md"
   - "generate documentation for the CLI"
   - "update the contributing guide"
+  - "j-doc"
 ---
 
 # Doc — Documentation Synthesis and Regeneration
 
+This skill is a literal-directory-name duplicate of `skills/doc/`. It exists so that `/j-doc` (and `j.j-doc`) give a guaranteed-unshadowed way to reach the same flow as `/doc`, even if a host tool's own built-in command of the same name would otherwise shadow or override the bare `/doc` alias (Claude Code's native skill resolution is a literal-string, directory-name-based match — see `docs/skill-authoring.md`'s "Invocation Convention").
+
+This file is generated/synced by `scripts/generate-j-alias.sh doc` from `skills/doc/SKILL.md` — do not hand-edit it; re-run the generator instead to pick up source changes.
+
 ## Input Format
 
 ```text
@@ -25,12 +33,15 @@ examples:
 ```
 
 - If `target-path` is omitted, default to `README.md`.
+- If the remainder starts with `update:`, strip that prefix, then trim again before resolving the target path.
 - If `target-path` is provided, use it exactly as written after `/doc`.
 - Do not guess additional arguments or rewrite the requested path.
 
 ## Reference Asset
 
-Load `skills/doc/assets/path-objectives.yaml` before resolving the documentation objective. Treat it as the source of truth for the `default_target`, known target paths, and their structural requirements.
+Load `skills/j-doc/assets/path-objectives.yaml` before resolving the documentation objective. Treat it as the source of truth for the `default_target`, known target paths, and their structural requirements.
+
+For extended usage guidance, provenance notes, and board-author tips, see `skills/j-doc/README.md`.
 
 ## Synthesis Context Contract
 
@@ -47,6 +58,7 @@ board_items: []
 conflicts_resolved: []
 sources_used: []
 existing_intent: null
+last_update: null
 ```
 
 Required fields from E24_S03:
@@ -60,27 +72,30 @@ Required fields from E24_S03:
 - `conflicts_resolved`
 - `sources_used`
 - `existing_intent`
+- `last_update`
 
-If the shared collector from E24_S03 is not yet merged, construct a temporary context with the same field names so later steps remain compatible.
+If the shared collector from E24_S03 is not yet merged, construct a temporary context with the same field names so later steps remain compatible. `last_update` is resolved during the provenance step below.
 
 ## Instructions
 
 ### 1. Parse the target path
 
-1. Read `default_target` from `skills/doc/assets/path-objectives.yaml`. If it is missing, fall back to `README.md`.
+1. Read `default_target` from `skills/j-doc/assets/path-objectives.yaml`. If it is missing, fall back to `README.md`.
 2. Remove the `/doc` command token from the invocation.
 3. Trim the remaining text.
-4. If nothing remains, set `target_path` to `default_target`.
-5. Otherwise, set `target_path` to the trimmed remainder.
+4. If the trimmed remainder starts with the exact prefix `update:`, remove that prefix and trim the remainder again.
+5. If nothing remains, set `target_path` to `default_target`.
+6. Otherwise, set `target_path` to the trimmed remainder.
 
 Examples:
 - `/doc` → `target_path = README.md`
 - `/doc docs/API.md` → `target_path = docs/API.md`
+- `/doc update: docs/API.md` → `target_path = docs/API.md`
 - `/doc docs/CLI.md` → `target_path = docs/CLI.md`
 
 ### 2. Resolve the objective from the rule table
 
-1. Read `skills/doc/assets/path-objectives.yaml`.
+1. Read `skills/j-doc/assets/path-objectives.yaml`.
 2. Find an entry whose `path` exactly matches `target_path`.
 3. If a match exists, set:
    - `objective` to the entry's `objective`
@@ -105,7 +120,7 @@ If the matched rule includes section guidance, carry it forward as constraints f
 
 ### 4. Ambiguity gate for unknown targets
 
-If `target_path` is not present in `skills/doc/assets/path-objectives.yaml`:
+If `target_path` is not present in `skills/j-doc/assets/path-objectives.yaml`:
 
 - Ask the user exactly: `What should <target_path> document? Please describe the objective.`
 - Do **not** guess the objective.
@@ -135,15 +150,37 @@ If `target_path` is not present in `skills/doc/assets/path-objectives.yaml`:
 
 If the target file does not exist, keep `existing_intent = null`.
 
-### 7. Generate a complete replacement file
+### 7. Resolve `last_update` provenance before writing
+
+1. Run `python3 skills/j-doc/scripts/resolve_last_update.py <target_path>` from the repository root.
+2. The resolver must scan `project/board/epics/`, `project/board/stories/`, and `project/board/tasks/`.
+3. Treat a board item as provenance only when all of the following are true:
+   - `status` is exactly `Done` or `Passed`
+   - `docs` is a YAML list that contains `target_path` as an exact repo-relative string match
+   - `date_completed` is present and parses as `YYYY-MM-DD`
+4. If multiple board items match, select the most recent `date_completed` and store it in `synthesis_context.last_update`.
+5. If no matching provenance is found, set `synthesis_context.last_update = "unknown"`. This is the required fallback because it keeps the frontmatter shape stable while making the missing provenance explicit.
+6. Ignore board items in any other status, items missing `docs`, and items whose `docs` entry uses a non-matching path form.
+
+### 8. Generate a complete replacement file
 
 1. Build a **full file string** from the synthesis context and the resolved target objective.
-2. Treat the generated output as the entire authoritative file.
-3. Do **not** patch a single section, append new text to the end, or leave untouched legacy sections in place.
-4. Keep the output valid Markdown.
-5. When writing, replace the old file contents in one operation.
+2. Start the file with YAML frontmatter for provenance, even when provenance could not be resolved:
+
+```yaml
+---
+last_update: <YYYY-MM-DD or unknown>
+---
+```
+
+3. Use the resolved `synthesis_context.last_update` value in that frontmatter. Emit `unknown` verbatim when no completed board item provides provenance.
+4. This fallback is mandatory: do not omit the `last_update` key when provenance is missing.
+5. Treat the generated output as the entire authoritative file.
+6. Do **not** patch a single section, append new text to the end, or leave untouched legacy sections in place.
+7. Keep the output valid Markdown.
+8. When writing, replace the old file contents in one operation.
 
-### 8. Generate `README.md` for the project-overview objective
+### 9. Generate `README.md` for the project-overview objective
 
 When `target_path = README.md`, generate the full document around the resolved project-overview contract.
 
@@ -175,7 +212,7 @@ When `target_path = README.md`, generate the full document around the resolved p
 - Preserve useful setup warnings from `existing_intent` when they are still valid.
 - Output valid Markdown lists or numbered steps.
 
-### 9. Conditionally include a README Examples section
+### 10. Conditionally include a README Examples section
 
 Only add `## Examples` to `README.md` when the synthesis context supports a grounded project-type inference.
 
@@ -212,7 +249,7 @@ Choose the strongest evidenced type in this priority order when multiple types a
 - Do **not** include placeholder examples, pseudo-commands, or guessed endpoints.
 - If you cannot produce two grounded examples, omit the section instead of improvising.
 
-### 10. Generate non-README targets from the rule table
+### 11. Generate non-README targets from the rule table
 
 For every known non-README target, the path-to-objective rule table determines the file structure. Generate a full document that satisfies the matched rule.
 
@@ -309,6 +346,6 @@ Rules:
 - Summarize each entry from commit subjects and, when needed, nearby commit context.
 - Keep newest entries first.
 
-### 11. Continue using the resolved objective
+### 12. Continue using the resolved objective
 
 After the target path and objective are resolved, use them as the contract for all subsequent `/doc` work. Known paths must bypass the ambiguity gate, and all later decisions about evidence gathering, scope, regeneration, and structure must honor the surfaced `target_path` and `objective` instead of inferring a different goal.

package/skills/j-doc/authoring-notes.md

@@ -0,0 +1,72 @@
+# `/doc` authoring notes
+
+## `last_update` provenance
+
+`/doc` writes a `last_update` frontmatter field at the top of generated documentation files. That value is derived from completed scrum-board items that explicitly declare they affected the target document.
+
+The resolver is `skills/j-doc/scripts/resolve_last_update.py`. It scans:
+
+- `project/board/epics/`
+- `project/board/stories/`
+- `project/board/tasks/`
+
+A board item counts as provenance only when all of the following are true:
+
+1. `status` is `Done` or `Passed`
+2. `docs` is a YAML list
+3. The `docs` list contains the target file path as an exact repo-relative match (for example `README.md` or `docs/API.md`)
+4. `date_completed` exists and parses as `YYYY-MM-DD`
+
+If multiple board items match, `/doc` uses the most recent `date_completed` as `last_update`.
+
+## Required board annotations
+
+For provenance to work, the scrum-board item that changed a documentation file must carry a matching `docs: [...]` annotation in its YAML frontmatter.
+
+Examples:
+
+```yaml
+docs:
+  - README.md
+  - docs/API.md
+```
+
+Use repo-relative paths only. The resolver does not normalize absolute paths or `./`-prefixed variants.
+
+## Fallback behavior
+
+When `/doc` cannot determine provenance, it still emits valid YAML frontmatter and sets:
+
+```yaml
+last_update: unknown
+```
+
+This fallback is intentional. It keeps the frontmatter shape stable while making the missing provenance explicit to both humans and downstream tooling.
+
+## Failure modes and assumptions
+
+### Board item completed without `docs` annotations
+
+If a task, story, or epic reached `Done`/`Passed` but omitted the target file from `docs`, `/doc` cannot attribute that item to the document. The resolver will ignore it and may fall back to `unknown`.
+
+### Target path mismatch
+
+Matching is exact and repo-relative. These examples do **not** match `README.md`:
+
+- `/Users/sam/.../README.md`
+- `./README.md`
+- `docs/../README.md`
+
+Authors should record the canonical repo-relative path that `/doc` was invoked with.
+
+### Item not in a completed status
+
+Items in statuses such as `Pending`, `In Progress`, `Blocked`, or `Failed` do not count as provenance even if they include the right `docs` annotation. Only completed work is eligible.
+
+### Missing or invalid `date_completed`
+
+A matching board item without a valid `date_completed` cannot contribute a `last_update` value. The resolver skips it and logs a warning to stderr.
+
+### Malformed legacy board files
+
+Some older board artifacts may not follow the current YAML-frontmatter schema. The resolver skips unparseable files instead of failing the whole `/doc` run. This is a degradation path, not successful provenance.