@jenga-ai/agent 1.2.4 → 2.0.0

package/skills/do/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: do
+name: j: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.
 keywords:
   - do
@@ -16,6 +16,14 @@ metadata:
 
 # Do — Execute Scrum Board Tasks
 
+## `--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
@@ -318,9 +326,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 +388,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 +406,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 not `inline`** (or is absent / `task` / `story` / `epic`) **and `crucial_level` is not `locked`**, proceed to step 5 (invoke the developer agent) as normal.
+**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
+
+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:

package/skills/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/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/doc/assets/path-objectives.yaml`.
+
+## Target Resolution and Objective Rules
+
+`skills/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/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/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/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: doc
+name: j:doc
 description: Generate or update a documentation file by resolving a target path to a clear documentation objective before writing.
 metadata:
   prefered_agent: developer
@@ -12,6 +12,7 @@ keywords:
 examples:
   - "/doc"
   - "/doc docs/API.md"
+  - "/doc update: docs/API.md"
   - "generate documentation for the CLI"
   - "update the contributing guide"
 ---
@@ -25,6 +26,7 @@ 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.
 
@@ -32,6 +34,8 @@ examples:
 
 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.
 
+For extended usage guidance, provenance notes, and board-author tips, see `skills/doc/README.md`.
+
 ## Synthesis Context Contract
 
 After target resolution, all generation must operate on a synthesis context object. E24_S03 is responsible for producing the final implementation, but this story defines the field contract that downstream generation must consume.
@@ -47,6 +51,7 @@ board_items: []
 conflicts_resolved: []
 sources_used: []
 existing_intent: null
+last_update: null
 ```
 
 Required fields from E24_S03:
@@ -60,8 +65,9 @@ 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
 
@@ -70,12 +76,14 @@ If the shared collector from E24_S03 is not yet merged, construct a temporary co
 1. Read `default_target` from `skills/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
@@ -135,15 +143,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/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 +205,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 +242,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 +339,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/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/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.

package/skills/doc/scripts/resolve_last_update.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Resolve /doc last_update provenance from scrum board annotations."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+COMPLETED_STATUSES = {"Done", "Passed"}
+BOARD_DIRS = (
+    ("epic", Path("project/board/epics")),
+    ("story", Path("project/board/stories")),
+    ("task", Path("project/board/tasks")),
+)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Resolve the latest completed board date for a documentation target.",
+    )
+    parser.add_argument("target_path", help="Repo-relative documentation target path, e.g. README.md")
+    parser.add_argument(
+        "--root",
+        default=Path(__file__).resolve().parents[3],
+        type=Path,
+        help="Repository root containing project/board/",
+    )
+    return parser.parse_args()
+
+
+def parse_scalar(value: str) -> Any:
+    text = value.strip()
+    if text in {"", "null", "~"}:
+        return ""
+    if text.startswith("[") and text.endswith("]"):
+        inner = text[1:-1].strip()
+        if not inner:
+            return []
+        return [item.strip().strip("\"'") for item in inner.split(",") if item.strip()]
+    return text.strip("\"'")
+
+
+def parse_frontmatter(path: Path) -> dict[str, Any]:
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---\n"):
+        raise ValueError("missing opening frontmatter delimiter")
+    parts = text.split("\n---\n", 1)
+    if len(parts) != 2:
+        raise ValueError("missing closing frontmatter delimiter")
+
+    lines = parts[0].splitlines()[1:]
+    data: dict[str, Any] = {}
+    current_key: str | None = None
+
+    for line in lines:
+        if not line.strip():
+            continue
+        if line.startswith("  - "):
+            if current_key is None:
+                raise ValueError(f"orphaned list item: {line.strip()}")
+            existing = data.get(current_key, "")
+            if existing == "":
+                existing = []
+                data[current_key] = existing
+            if not isinstance(existing, list):
+                raise ValueError(f"frontmatter key {current_key!r} is not a list")
+            existing.append(line[4:].strip().strip("\"'"))
+            continue
+        if ":" not in line:
+            raise ValueError(f"invalid frontmatter line: {line}")
+        key, raw_value = line.split(":", 1)
+        key = key.strip()
+        value = parse_scalar(raw_value)
+        data[key] = value
+        current_key = key if value == "" else None
+
+    return data
+
+
+def iter_matches(root: Path, target_path: str):
+    for item_type, relative_dir in BOARD_DIRS:
+        board_dir = root / relative_dir
+        if not board_dir.exists():
+            continue
+        for path in sorted(board_dir.glob("*.md")):
+            try:
+                frontmatter = parse_frontmatter(path)
+            except Exception as exc:  # pragma: no cover - defensive degradation
+                print(f"warning: skipping {path}: {exc}", file=sys.stderr)
+                continue
+
+            if frontmatter.get("status") not in COMPLETED_STATUSES:
+                continue
+
+            docs = frontmatter.get("docs")
+            if not isinstance(docs, list) or target_path not in docs:
+                continue
+
+            completed_raw = str(frontmatter.get("date_completed", "")).strip()
+            if not completed_raw:
+                print(
+                    f"warning: skipping {path}: matching docs annotation without date_completed",
+                    file=sys.stderr,
+                )
+                continue
+
+            try:
+                completed_on = date.fromisoformat(completed_raw)
+            except ValueError:
+                print(
+                    f"warning: skipping {path}: invalid date_completed {completed_raw!r}",
+                    file=sys.stderr,
+                )
+                continue
+
+            yield {
+                "id": frontmatter.get("id") or path.stem,
+                "type": item_type,
+                "status": frontmatter.get("status"),
+                "date_completed": completed_on.isoformat(),
+                "path": path.relative_to(root).as_posix(),
+            }
+
+
+def main() -> int:
+    args = parse_args()
+    root = args.root.resolve()
+    matches = sorted(
+        iter_matches(root, args.target_path),
+        key=lambda item: (item["date_completed"], item["id"]),
+    )
+    last_update = matches[-1]["date_completed"] if matches else "unknown"
+    payload = {
+        "target_path": args.target_path,
+        "last_update": last_update,
+        "provenance_found": bool(matches),
+        "fallback": "unknown",
+        "matched_items": matches,
+    }
+    print(json.dumps(payload, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())