@jenga-ai/agent 3.1.1 → 3.4.0

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

@@ -28,7 +28,7 @@ examples:
 | 4 | Elevated | |
 | 5 | Unrestricted | |
 
-`defaultMode` stays `acceptEdits` at every level; only the `permissions` block changes. Levels are backed by template files at `templates/permission-levels/level-<n>-<name>.json`, e.g. `templates/permission-levels/level-4-elevated.json` (naming convention: `<name>` is the lowercase level name from the table above — Locked/Guarded/Standard/Elevated/Unrestricted). Those templates are owned by story E33_S01 and are the input the switch script (see below) copies from.
+`defaultMode` stays `acceptEdits` at every level; only the `permissions` block changes. Levels are backed by template files at `$([ -f templates/permission-levels/level-<n>-<name>.json ] && echo templates/permission-levels/level-<n>-<name>.json || echo node_modules/@jenga-ai/agent/templates/permission-levels/level-<n>-<name>.json)`, e.g. `$([ -f templates/permission-levels/level-4-elevated.json ] && echo templates/permission-levels/level-4-elevated.json || echo node_modules/@jenga-ai/agent/templates/permission-levels/level-4-elevated.json)` (naming convention: `<name>` is the lowercase level name from the table above — Locked/Guarded/Standard/Elevated/Unrestricted). Those templates are owned by story E33_S01 and are the input the switch script (see below) copies from.
 
 ---
 
@@ -59,18 +59,18 @@ Before doing anything else, validate the argument:
 Do not inline the copy/update logic here — per this repo's scripts-over-inline-logic convention, the switch is owned entirely by a dedicated script:
 
 ```bash
-bash scripts/jenga-permission-level-switch.sh <n>
+bash "$([ -f scripts/jenga-permission-level-switch.sh ] && echo scripts/jenga-permission-level-switch.sh || echo node_modules/@jenga-ai/agent/scripts/jenga-permission-level-switch.sh)" <n>
 ```
 
 This script (created by a separate task, E33_S02_T02) is responsible for:
-- Copying `templates/permission-levels/level-<n>-<name>.json` over both `.claude/settings.json` and `.agents/settings.json` as a **whole-file overwrite** — not a merge of the `permissions` block alone. Two fields vary by level and are expected to change on a switch: `permissions.deny` and `autoMode.allow`. All 5 templates carry byte-identical `defaultMode`, `env`, `hooks`, and `permissions.allow`; that invariant is what keeps the overwrite safe. Two consequences follow: any top-level key present in a destination file but absent from the templates is **silently dropped** by a switch, and any future per-level difference in `defaultMode`/`env`/`hooks` would take effect without warning. Keep the templates in sync with root `settings.json` for everything except those two varying fields.
+- Copying `$([ -f templates/permission-levels/level-<n>-<name>.json ] && echo templates/permission-levels/level-<n>-<name>.json || echo node_modules/@jenga-ai/agent/templates/permission-levels/level-<n>-<name>.json)` over both `.claude/settings.json` and `.agents/settings.json` as a **whole-file overwrite** — not a merge of the `permissions` block alone. Two fields vary by level and are expected to change on a switch: `permissions.deny` and `autoMode.allow`. All 5 templates carry byte-identical `defaultMode`, `env`, `hooks`, and `permissions.allow`; that invariant is what keeps the overwrite safe. Two consequences follow: any top-level key present in a destination file but absent from the templates is **silently dropped** by a switch, and any future per-level difference in `defaultMode`/`env`/`hooks` would take effect without warning. Keep the templates in sync with root `settings.json` for everything except those two varying fields.
 - Creating or updating `.jenga-permission-level.json` at the repo root to `{"session_level": <n>}`.
 
 Relay the script's stdout to the user and honor its exit code:
 - Exit code `0` — report success, e.g. `Switched to level <n> (<name>).`
 - Non-zero exit code — report the script's error output verbatim and treat the switch as failed; do not claim success.
 
-If `scripts/jenga-permission-level-switch.sh` does not exist yet (e.g. E33_S02_T02 has not landed), report that clearly as a missing dependency rather than attempting to reimplement its logic inline.
+If neither `scripts/jenga-permission-level-switch.sh` nor `node_modules/@jenga-ai/agent/scripts/jenga-permission-level-switch.sh` exists yet (e.g. E33_S02_T02 has not landed), report that clearly as a missing dependency rather than attempting to reimplement its logic inline.
 
 ### Session End
 

package/templates/KNOWLEDGE_GRAPH_STUB_SCHEMA_TEMPLATE.md

@@ -0,0 +1,128 @@
+# Knowledge Graph — Coarse Graph STUB Schema
+
+> **STUB — this is not E20_S01's schema.**
+>
+> This file defines a minimal, intentionally throwaway coarse-graph node/edge schema so that
+> **E20_S08** ("Interactive Architecture Elicitation — Uncharted Integration") can be prototyped
+> without waiting on **E20_S01** (the epic's real, eventual node/edge schema and JSON Schema
+> publication under `project/knowledge-graph/graph.json`). E20_S01 has no committed landing
+> schedule; this stub exists purely to unblock E20_S08's other tasks in the meantime.
+>
+> **This schema will be replaced wholesale once E20_S01 lands.** Nothing that depends on this file
+> should assume field stability, forward compatibility, or migration support — when E20_S01's real
+> schema is published, this file should be deleted (or reduced to a pointer at the real schema) and
+> every consumer of it re-pointed. Do not extend this stub with new fields expecting them to survive
+> the swap; keep it minimal.
+
+---
+
+## Node Schema
+
+| Field         | Type                | Required | Description                                                                 |
+|---------------|---------------------|----------|-------------------------------------------------------------------------------|
+| `id`          | string              | yes      | Unique node identifier within the coarse graph.                              |
+| `type`        | string              | yes      | Node kind (e.g. `service`, `module`, `function`, `data-type`). Free-text in the stub — E20_S01 may formalize an enum. |
+| `label`       | string              | yes      | Short human-readable name for the node.                                      |
+| `description` | string              | yes      | Free-text description of what the node represents.                          |
+| `source`      | `human` \| `ast`    | yes      | Provenance of this node — see **Provenance Field** below.                    |
+| `status`      | `active` \| `superseded` | no  | Present only once a conflict has been resolved against this node — see **Evidence-Wins Conflict Rule** below. Absence means `active`. |
+| `superseded_by` | string (node `id`) | no    | Required when `status: superseded`. Points at the node that superseded this one. |
+
+## Edge Schema
+
+| Field         | Type   | Required | Description                                             |
+|---------------|--------|----------|----------------------------------------------------------|
+| `id`          | string | yes      | Unique edge identifier within the coarse graph.          |
+| `from`        | string | yes      | Source node `id`.                                        |
+| `to`          | string | yes      | Target node `id`.                                        |
+| `type`        | string | yes      | Edge kind (e.g. `depends-on`, `calls`, `flows-to`). Free-text in the stub. |
+| `description` | string | yes      | Free-text description of the relationship.                |
+
+---
+
+## Provenance Field — `source: human | ast`
+
+Every stub node declares how it came to exist:
+
+- **`human`** — written by a human-in-the-loop conversational elicitation session (the flow E20_S08
+  is building: propose understanding, ask the user to confirm or correct, write the resulting node).
+  This is a **coarse** node: it reflects a person's understanding of the code, not mechanical
+  extraction.
+- **`ast`** — written by an automated, AST-derived extraction pipeline. This is a **fine-grained**
+  node: it reflects what the code mechanically, verifiably does. No such pipeline exists yet as of
+  this stub (it is scoped to E20_S02's prospective AST-diff maintenance work); the `ast` value is
+  defined here so the conflict rule below has both sides of the conflict to refer to from day one.
+
+There is no third value. A node's `source` is fixed at creation time and is not itself mutated by
+conflict resolution — conflict resolution only ever adds `status`/`superseded_by` to a `human` node
+(see below); it never rewrites a node's `source`.
+
+## Evidence-Wins Conflict Rule
+
+**Trigger:** a `human`-sourced coarse node and a (future) `ast`-sourced fine node both describe the
+same underlying code, and they disagree — e.g. a human described a module's purpose one way during
+elicitation, and a later AST-derived extraction of the same code area produces a materially
+different description or classification.
+
+**Rule:** the AST-derived (`source: ast`) entry takes precedence as the authoritative description.
+The human-authored (`source: human`) entry is **not deleted**. Instead:
+
+1. The human node's `status` field is set to `superseded`.
+2. The human node's `superseded_by` field is set to the `id` of the AST-derived node that
+   superseded it.
+3. The AST-derived node is written normally (`source: ast`, no `status` field — it is the new
+   active, authoritative entry for that piece of code).
+
+This preserves the human node as a retained, annotated rationale/history layer rather than silently
+discarding a person's prior understanding — useful for later review of *why* a human once believed
+something different, and for detecting elicitation sessions that were confidently wrong.
+
+**Worked example:**
+
+Before conflict resolution — a human-authored coarse node:
+
+```json
+{
+  "id": "node-042",
+  "type": "module",
+  "label": "billing-worker",
+  "description": "Background job that retries failed charges.",
+  "source": "human"
+}
+```
+
+After a later AST-derived extraction disagrees (the module actually reconciles ledger entries, it
+does not retry charges) and the conflict is resolved:
+
+```json
+{
+  "id": "node-042",
+  "type": "module",
+  "label": "billing-worker",
+  "description": "Background job that retries failed charges.",
+  "source": "human",
+  "status": "superseded",
+  "superseded_by": "node-091"
+}
+```
+
+```json
+{
+  "id": "node-091",
+  "type": "module",
+  "label": "billing-worker",
+  "description": "Background job that reconciles ledger entries against the payment provider.",
+  "source": "ast"
+}
+```
+
+`node-042` remains in the graph, readable, and traceable to what replaced it — it is superseded, not
+gone.
+
+---
+
+## Relationship to `[ARCH]` Board Tagging
+
+Board items generated by the E20_S08 elicitation flow that populate this stub schema are tagged
+`[ARCH]` (see `templates/SCRUM_BOARD_SCHEMA.md`'s "Board Item Tag Conventions" section) rather than
+`[SPIKE]` — this is durable architectural-inventory record-keeping, not bounded research.

package/templates/SCRUM_BOARD_SCHEMA.md

@@ -105,7 +105,9 @@ date_started:
 date_completed:
 dates_previously_completed:  # comma-separated list, e.g. 2026-01-15, 2026-03-22
 reopened_on:                 # comma-separated list, e.g. 2026-02-01, 2026-04-10
-reopened_reason:             # comma-separated list, e.g. "Scope expanded", "Bug found post-release"
+reopened_reason:             # YAML list, one entry per reopen cycle; see Reopen Tracking Fields
+  - "Scope expanded"
+  - "Bug found post-release"
 docs: []                     # optional list of repo-relative documentation paths, e.g. ["README.md", "docs/API.md"]
 epic_scope_approval: false     # set to true by the human operator only when any task in this epic has execution_scope: epic
 provenance:                  # optional; only valid value is `backfilled` (epic reverse-engineered from pre-existing code by `/uncharted onboard`). Omit for normally-authored epics.
@@ -139,7 +141,9 @@ date_started:
 date_completed:
 dates_previously_completed:  # comma-separated list, e.g. 2026-01-15, 2026-03-22
 reopened_on:                 # comma-separated list, e.g. 2026-02-01, 2026-04-10
-reopened_reason:             # comma-separated list, e.g. "Scope expanded", "Bug found post-release"
+reopened_reason:             # YAML list, one entry per reopen cycle; see Reopen Tracking Fields
+  - "Scope expanded"
+  - "Bug found post-release"
 docs: []                     # optional list of repo-relative documentation paths, e.g. ["README.md", "docs/API.md"]
 crucial_level:                # optional; advisory | gated | locked; absence means no elevated caution
 crucial_set_by:                # required when crucial_level is set; user | scrum-master | <agent>-escalation
@@ -177,7 +181,9 @@ date_started:
 date_completed:
 dates_previously_completed:  # comma-separated list, e.g. 2026-01-15, 2026-03-22
 reopened_on:                 # comma-separated list, e.g. 2026-02-01, 2026-04-10
-reopened_reason:             # comma-separated list, e.g. "Scope expanded", "Bug found post-release"
+reopened_reason:             # YAML list, one entry per reopen cycle; see Reopen Tracking Fields
+  - "Scope expanded"
+  - "Bug found post-release"
 assigned_to: developer | tester | scrum-master
 docs: []                     # optional list of repo-relative documentation paths, e.g. ["README.md", "docs/API.md"]
 execution_scope: task          # task | story | epic | inline | light; omit for legacy tasks (defaults to task)
@@ -209,7 +215,7 @@ crucial_declined_note:           # required when crucial_declined: true; free-te
 
 ### Runtime-written task fields
 
-These four fields are **not authored by hand**. They are appended to a task's frontmatter after execution and are absent from any task that has not yet run. They are listed here so that tooling — in particular `scripts/validate-board.sh` — recognises them as valid rather than unknown.
+These five fields are **not authored by hand**. They are appended to a task's frontmatter after execution and are absent from any task that has not yet run. They are listed here so that tooling — in particular `scripts/validate-board.sh` — recognises them as valid rather than unknown.
 
 | Field | Written by | Meaning |
 |---|---|---|
@@ -217,8 +223,9 @@ These four fields are **not authored by hand**. They are appended to a task's fr
 | `actual_lines_delta` | `/close-story` | Net line delta for the task, from the same extraction |
 | `scope_divergence_flag` | `/close-story` | Set when actual diff stats exceed the thresholds that justified the assigned `execution_scope` |
 | `divergence_flag` | `/do` | Set to `true` by the intent-vs-diff check when a `needs_docs: false` task touched unregistered files |
+| `date_deployed_prod` | `scripts/mark-deployed.sh` | ISO 8601 date (e.g. `2026-09-12`) written in the same locked write window a ticket is set to `status: Deployed to Prod`. Never written on a `Deployed to Stage`-only write. |
 
-All four are advisory and non-blocking — they record evidence for later review and never change a task's Passed/Failed outcome.
+All five are advisory and non-blocking — they record evidence for later review and never change a task's Passed/Failed outcome. `date_deployed_prod` is allow-listed in `scripts/validate-board.sh`'s `ALLOWED_KEYS` for `epic`, `story`, and `task` (a new `DEPLOY_KEYS` group), even though in practice only tasks (and occasionally stories) are expected to ever carry it — `mark-deployed.sh` only ever writes it to a task/story board file, never to an epic.
 
 > `task_changed_files` is **not** a frontmatter field despite the similar name. It lives in the bundle manifest at `project/queue/bundle-<E##_S##>.json`, keyed by task ID.
 
@@ -228,7 +235,12 @@ All four are advisory and non-blocking — they record evidence for later review
 
 ## Reopen Tracking Fields
 
-**`dates_previously_completed`, `reopened_on`, `reopened_reason`** — These fields are **only populated when a previously completed item is being reopened and modified**. Leave them blank on first-run items. Each value is a comma-separated list to support multiple reopen cycles.
+**`dates_previously_completed`, `reopened_on`, `reopened_reason`** — These fields are **only populated when a previously completed item is being reopened and modified**. Leave them blank on first-run items. All three support multiple reopen cycles, but they are **not written the same way**:
+
+- `dates_previously_completed` and `reopened_on` hold a plain comma-separated string, e.g. `reopened_on: 2026-02-01, 2026-04-10`. Bare dates need no quoting, so this parses fine.
+- `reopened_reason` **must be a YAML list** (a block sequence, one `- "reason"` per line). It cannot be comma-separated, because reopen reasons are free text that routinely contains colons and commas and therefore has to be quoted — and a run of comma-separated quoted strings (`reopened_reason: "A", "B"`) is not valid YAML. This schema previously documented exactly that invalid form, and every board file that followed it became unparseable: the board parser skipped those files silently, so the board under-reported itself with no error surfaced anywhere. 14 files were repaired on 2026-09-13; do not reintroduce the comma-separated form here.
+
+Note the resulting asymmetry is deliberate and load-bearing, not an oversight: the first two fields stay strings because migrating them would churn every existing file for no parsing benefit.
 
 ## Planning Fields
 

package/templates/playbook-types.json

@@ -0,0 +1,8 @@
+{
+  "_comment": "Canonical playbook output-type vocabulary for Epic E53's Playbooks v2 StepObject/output_types contract (E53_S03_T02). Extend this vocabulary by adding entries to the 'types' array below -- NEVER by code changes; skills/jenga/scripts/load-playbooks.sh references this file by name in its own header contract (see that script's 'TYPE REGISTRY' section). Governed by the Scrum Master: registry additions/changes route through the normal board-item process rather than an ungoverned edit to this file -- see docs/skill-authoring.md's 'Playbook Type Registry Governance' section for the full policy.",
+  "types": [
+    "text",
+    "id_list",
+    "file_list"
+  ]
+}

package/skills/jenga/playbooks/brainstorm-to-mirror.json

@@ -1,22 +0,0 @@
-{
-  "id": "brainstorm-to-mirror",
-  "name": "Idea to Public Release",
-  "description": "Takes a rough idea all the way from planning through implementation, committing, and a public mirror release -- the canonical end-to-end Jenga workflow chain.",
-  "keywords": [
-    "idea to release",
-    "plan and ship",
-    "idea to done",
-    "full workflow",
-    "end to end",
-    "plan build ship",
-    "idea to production"
-  ],
-  "examples": [
-    "I have an idea, help me plan it, build it, and ship it",
-    "take this feature from idea to committed and published",
-    "let's go from a rough idea all the way to a public release",
-    "plan this out, implement it, commit it, and push it to the public mirror",
-    "walk this through the whole pipeline from brainstorm to release"
-  ],
-  "steps": ["brainstorm", "todo", "do", "dev-done", "mirror-public"]
-}