@jenga-ai/agent 1.3.0 → 2.0.0

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())

package/skills/doc-sync/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: doc-sync
+name: j:doc-sync
 description: Compare the current state of a project with its documentation and update documentation to reflect changes. Accepts `update:`, `source:`, `exclude:`, and `minify:` arguments to control scope. Use when documentation may be out of date with implementation, or when the user asks to sync, refresh, update, or shrink docs.
 keywords:
   - doc-sync

package/skills/dooo/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: dooo
+name: j:dooo
 description: Parallel execution orchestrator. Calls /do to start implementations via sub-agents, then loops back to the board to identify and offer parallelisable tasks until the user selects "Done".
 keywords:
   - dooo

package/skills/error/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: error
+name: j:error
 description: Guided troubleshooting flow that gathers context about an error — where it occurs, what was attempted, what went wrong, and what was expected.
 keywords:
   - error

package/skills/evaluate/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: evaluate
+name: j:evaluate
 description: Analyzes example files against a target goal and produces a structured evaluation rapport.
 ---
 

package/skills/examplify/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: examplify
+name: j:examplify
 description: Explains concepts, features, use cases, and patterns based on provided context — a description, scenario, code snippet, or file. Use when the user wants to understand what something is, how it works, when to use it, or wants a concrete example.
 keywords:
   - examplify

package/skills/help/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: help
+name: j:help
 description: List all available skills with a short description of what each one does. Also use this skill when the user wants to know what commands or skills are available in the project.
 keywords:
   - help

package/skills/idea/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: idea
+name: j:idea
 description: Capture a loosely-defined idea to project/ideas.md — a lightweight, "maybe someday" log with no board or promotion overhead.
 keywords:
   - idea

package/skills/improve/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: improve
+name: j:improve
 description: A skill for analyzing a codebase and producing a structured improvement plan toward a defined goal.
 ---
 

package/skills/init/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: init
+name: j:init
 description: Initialize a new project with the standard directory structure, PROJECT_SUMMARY.md, workflow.json, git repo, and gitignore. Follows a defined ordered onboarding sequence. Use when setting up a new or empty project.
 keywords:
   - init

package/skills/init/assets/scope-thresholds_template.json

@@ -1,7 +1,7 @@
 {
-  "threshold_version": 1,
-  "inline_max_files": 1,
-  "inline_max_lines": 20,
+  "threshold_version": 2,
+  "inline_max_files": 3,
+  "inline_max_lines": 75,
   "story_max_files": 5,
   "bundle_lock_ttl_minutes": 30
 }