@jenga-ai/agent 3.1.0 → 3.2.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/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"
+  ]
+}