@raquezha/norpiv 0.0.6 → 0.0.8

package/README.md

@@ -2,12 +2,17 @@
 
 RPIV: a gated workflow for reliable AI coding agents.
 
+RPIV is one implementation of the broader `nothing` Workflow Contract. The contract defines the generic shape for workflows such as RPIV and Research, focusing on 3 Real Modes (Chat, Research, RPIV) tracked by `.workflow/active.json`.
+
+Standalone package usage still works: `@raquezha/norpiv` includes the RPIV skills, `distill`, and helper scripts needed for handoff. The local Research workflow lives separately under `packages/workflows/noresearch`. The platform-level contract lives in the source repo at <https://github.com/raquezha/nothing/blob/main/docs/workflow.md>.
+
 ## 🔁 The Lifecycle
 
 The RPIV engine splits task execution into separate, focused phases:
 
 | Phase | Command | Purpose | Input / Output Files |
 | :--- | :--- | :--- | :--- |
+| **0. Refine (optional)** | `/refine [source]:[id]` | Repair tracker readiness before RPIV when outcome, acceptance criteria, ownership, dependencies, or decomposition are still unclear. | Proposes tracker edits/child work with ownership/dependency recommendations; no `.workflow/` state |
 | **1. Ingest** | `/triage [source]:[id]` | Initial task verification and workspace setup. | Creates `.workflow/tasks/[source-id]/WORK.md` & `metadata.json` |
 | **2. Scoping** | `/frame` | Author a clear, structured task brief. | Populates `WORK.md` ➔ `[BRIEF]` section |
 | **3. Interrogate**| `/grill-with-docs` | Stress-test brief against rules and docs. | Records decisions in `WORK.md` ➔ `[GRILL]` |
@@ -42,6 +47,10 @@ Rules:
 - **Measure Twice, Cut Once**: Never implement code during scoping or planning. The agent will wait for an explicit `EXECUTE` statement before modifying files.
 - **One Source of Truth**: All task state belongs in `.workflow/tasks/[source-id]/WORK.md`. Avoid creating separate `PROBLEM.md` or `PLAN.md` files.
 - **Safe Branching**: Triage and planning happen on the main branch. Create the feature branch (`feat/*` or `fix/*`) only when starting `/implement`.
+- **Real In-Progress Starts at Implement**: `/refine`, `/triage`, `/frame`, and `/plan` are preparation, not execution. Move the remote Jira/GitHub/GitLab work item to an in-progress state only when `/implement` actually begins.
+- **Refine Preserves Intent**: `/refine` should preserve product-authored text, append acceptance criteria instead of rewriting it, and only assign or link child work when ownership/dependency signals are clear.
+- **Canonical Pointer**: `.workflow/active.json` is the active RPIV pointer. Legacy `active_task.json` is compatibility-only during migration.
+- **Normalized Intake**: `/triage` writes a small local projection into `WORK.md`; tracker snapshots live in `metadata.json`, not raw CLI dumps.
 
 ## 📦 Install as a skill bundle
 
@@ -51,7 +60,7 @@ Best for trying or handing off RPIV skills without installing the full `nothing`
 
 ```bash
 npx -y skills add raquezha/nothing --full-depth -g -a pi \
-  -s triage frame grill-with-docs plan implement verify sync post-merge-prune update-docs distill \
+  -s refine triage frame grill-with-docs plan implement verify sync post-merge-prune update-docs distill \
   -y
 ```
 
@@ -84,7 +93,7 @@ Targets:
 
 | Hat | Purpose |
 | :--- | :--- |
-| `pi --rpiv` | Full RPIV workflow. Loads triage, frame, grill-with-docs, plan, implement, verify, sync, post-merge-prune, and update-docs. |
+| `pi --rpiv` | Full RPIV workflow. Loads refine, triage, frame, grill-with-docs, plan, implement, verify, sync, post-merge-prune, and update-docs. |
 | `pi --notes` | Conversation distiller. Saves useful thinking to Obsidian without RPIV ceremony. |
 
 ## 📝 Pre-RPIV note capture
@@ -112,6 +121,8 @@ Obsidian note → /triage → RPIV             (only when ready to commit)
 
 `distill` is the missing layer before RPIV. Use `pi --notes` to load it.
 
+Research is a separate local workflow bundle in `packages/workflows/noresearch` and is loaded by the full `nothing` setup with `pi --research`.
+
 ## 🚀 Quick Start Example
 
 1. **Activate the RPIV Hat** from the full `nothing` setup:
@@ -121,34 +132,39 @@ Obsidian note → /triage → RPIV             (only when ready to commit)
 
    If installed via `npx skills add` or `norpiv-install`, invoke the skills directly in your agent instead.
 
-2. **Triage an Issue**:
+2. **Optional Tracker Refinement**:
+   ```text
+   /refine github:45
+   ```
+
+3. **Triage an Issue**:
    ```text
    /triage github:45
    ```
 
-3. **Frame the Work**:
+4. **Frame the Work**:
    ```text
    /frame
    ```
 
-4. **Verify Constraints**:
+5. **Verify Constraints**:
    ```text
    /grill-with-docs
    ```
 
-5. **Write the Plan Slices**:
+6. **Write the Plan Slices**:
    ```text
    /plan
    ```
 
-6. **Authorize Execution**:
+7. **Authorize Execution**:
    Provide the agent explicit permission to implement:
    ```text
    EXECUTE
    /implement
    ```
 
-7. **Verify & Close**:
+8. **Verify & Close**:
    ```text
    /verify
    /sync
@@ -161,39 +177,24 @@ The bundle includes helper scripts used by the workflow skills:
 
 - `scripts/triage_helper.sh`
 - `scripts/validate_active_task.sh`
-- `scripts/reposcry-bootstrap.sh`
-- `scripts/reposcry-task-context.sh`
-- `scripts/reposcry-refresh.sh`
+- `scripts/graphify-grill.sh`
+- `scripts/graphify-grill.py`
 
 When skills are loaded directly from this package, relative references like `../scripts/...` resolve against the package root. When skills are installed with `norpiv-install`, the same layout is recreated under the target runtime.
 
-## 🔎 Optional RepoScry integration
+## 🔎 Optional Graphify grilling
 
-RepoScry is an optional repo-memory layer for RPIV. norpiv does **not** require it.
+Graphify is an optional grill-only evidence layer for RPIV. norpiv does **not** require it.
 
-If `reposcry` is installed:
+If bootstrap provisions `~/.graphify/venv`, `/grill-with-docs` may run:
 
 ```bash
-./scripts/reposcry-bootstrap.sh
-./scripts/reposcry-task-context.sh "fix dependency graph rebuild"
-# edit code
-./scripts/reposcry-refresh.sh main
-reposcry validate main HEAD
+./scripts/graphify-grill.sh
 ```
 
-Typical usage by phase:
-
-- `/triage`: optionally seed `.reposcry/` with `scripts/reposcry-bootstrap.sh`
-- `/frame`: optionally generate `.reposcry/AI_CONTEXT.md` with `scripts/reposcry-task-context.sh`
-- `/grill-with-docs`: optionally use `reposcry query_graph`, `get_architecture_overview`, and `get_impact_radius`
-- `/implement`: optionally run `scripts/reposcry-refresh.sh` after edit batches
-- `/verify`: optionally add `reposcry validate main HEAD` and affected-flow output as extra evidence
-
-If RepoScry is absent, the helpers no-op and RPIV continues with normal repo reading, grep, and tests.
-
-RepoScry guardrails:
+Guardrails:
 
-- `.reposcry/` is generated local cache and must not be committed.
-- `scripts/reposcry-bootstrap.sh` automatically adds `.reposcry/` to the project `.gitignore` before initializing RepoScry.
-- If `.reposcry/` is already tracked or staged, bootstrap stops and tells you to remove it from the index.
-- `.reposcryignore` is indexing policy, not cache. Review and commit it when you want stable RepoScry behavior across machines.
+- input is a temporary `git archive HEAD` extraction, not the live repository root
+- extraction is structural only by default
+- Graphify warnings never block grilling; normal source reading remains the fallback
+- `INFERRED` or `AMBIGUOUS` edges are leads that still require source verification

package/frame/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: frame
+workflow: rpiv
+workflowPhase: frame
 description: Define the task brief inside the active WORK.md. Use after /triage to convert issue data into a clear Problem or Proposal brief without creating separate PROBLEM.md or PRD.md files.
 ---
 
@@ -8,15 +10,14 @@ description: Define the task brief inside the active WORK.md. Use after /triage
 Turn raw task context into the stable "what/why" brief.
 
 ## Guardrails
-- READ: `.workflow/active_task.json`, `.workflow/tasks/[active_task]/WORK.md`, and `.reposcry/AI_CONTEXT.md` when present.
-- WRITE: `WORK.md` -> `[BRIEF]` section and append to `[LOG]` only; optional `.reposcry/AI_CONTEXT.md` when RepoScry is installed.
+- READ: `.workflow/active.json` first, then legacy compatibility `.workflow/active_task.json` only if needed, and active `WORK.md`.
+- WRITE: `WORK.md` -> `[BRIEF]` section and append to `[LOG]` only.
 - NEVER: create `PROBLEM.md`, `PRD.md`, or extra planning files.
 - NEVER: overwrite `[PLAN]` or `[GRILL]`.
 - NEVER: ask whether to frame if the user invoked `/frame`; do it.
 
 ## Workflow
 1. Read the active task and remote metadata.
-2. If RepoScry is available, run the bundled `../scripts/reposcry-task-context.sh "<task summary>"` helper to generate `.reposcry/AI_CONTEXT.md`, then use that file as supplemental repo context. The helper path must preserve RepoScry guardrails: `.reposcry/` ignored, cache never tracked, `.reposcryignore` treated as reviewable indexing policy. Continue normally when unavailable.
 3. Determine brief type:
    - **Problem** for bugs, regressions, crashes, broken behavior.
    - **Proposal** for features, enhancements, refactors, new behavior.

package/grill-with-docs/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: grill-with-docs
+workflow: rpiv
+workflowPhase: grill-with-docs
 description: Stress-test the active WORK.md brief against docs, code, and domain language. Use after /frame before planning to clarify assumptions and update durable docs only when decisions are stable.
 ---
 
@@ -8,31 +10,25 @@ description: Stress-test the active WORK.md brief against docs, code, and domain
 Challenge the brief before planning. This replaces passive ubiquitous-language collection with active clarification.
 
 ## Guardrails
-- READ: `.workflow/active_task.json`, active `WORK.md` `[BRIEF]`, `CONTEXT.md`, relevant `docs/agents/*`, and `.reposcry/AI_CONTEXT.md` when present.
+- READ: `.workflow/active.json` first, then legacy compatibility `.workflow/active_task.json` only if needed, plus active `WORK.md` `[BRIEF]`, `CONTEXT.md`, and relevant `docs/agents/*`.
 - WRITE: `WORK.md` -> append to `[GRILL]` and `[LOG]` only; durable docs only when a stable rule is confirmed.
 - NEVER: edit `[BRIEF]` silently; propose brief changes if contradictions are found.
 - NEVER: plan or implement during grilling.
 - NEVER: ask questions the codebase can answer; inspect first.
 
 ## Workflow
-1. **Context Loading**: Read the active brief, `CONTEXT.md`, relevant `docs/agents/*`, and `.reposcry/AI_CONTEXT.md` when available.
+1. **Context Loading**: Read the active brief, `CONTEXT.md`, and relevant `docs/agents/*`.
 2. **Investigation & Trace**:
    - Locate the files/lines mentioned in the brief.
    - Trace the data flow related to the problem/proposal.
    - Search for "Impact Surface": Who else uses or depends on these components?
-3. **Optional RepoScry graph pass**: if `reposcry` is available, use it to ground architecture and blast radius. Before relying on it, ensure the bundled bootstrap/context helper has kept `.reposcry/` ignored and untracked. Use commands such as:
-   - `reposcry --repo . get_architecture_overview --format json`
-   - `reposcry --repo . query_graph "callers_of <symbol>"`
-   - `reposcry --repo . query_graph "tests_for <symbol>"`
-   - `reposcry --repo . get_impact_radius <symbol> --depth 4`
-   Proceed normally when RepoScry is absent.
+3. **Optional Graphify pass**: run `../scripts/graphify-grill.sh` once for bounded structural evidence. It reads only a temporary `git archive HEAD` extraction and warns instead of failing when unavailable. Treat `INFERRED` or `AMBIGUOUS` edges as leads: verify them in source before recording conclusions.
 4. **Cross-check**: Compare findings against docs, ADRs, and repo patterns.
-5. **Relentless Interview**:
-   - Ask one question at a time to resolve contradictions or clarify ambiguity.
-   - Challenge the brief if the code behaves differently than described.
-6. **Log Evidence**: Append resolved decisions, technical findings, edge cases, and constraints to `[GRILL]`.
-7. **Log Activity**: Append a timestamped summary of the grilling session to `[LOG]` (Format: `YYYY-MM-DD hh:mm AM/PM`).
-8. **Context Curation**: If a durable term/rule emerges, propose or apply a concise `docs/agents/*` update.
+5. **Challenge**: record confirmed constraints, challenged assumptions, chosen decisions, open blockers / HITL questions, and risks handed to `/plan` or `/implement`.
+6. **Interview**: ask one question at a time only for execution-blocking ambiguity the repository cannot answer.
+7. **Log Evidence**: Append resolved decisions, technical findings, edge cases, and constraints to `[GRILL]`.
+8. **Log Activity**: Append a timestamped summary of the grilling session to `[LOG]` (Format: `YYYY-MM-DD hh:mm AM/PM`).
+9. **Context Curation**: If a durable term/rule emerges, propose or apply a concise `docs/agents/*` update.
 
 ## Output contract
 End with:

package/implement/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: implement
+workflow: rpiv
+workflowPhase: implement
 description: Implement the next approved vertical slice from the active WORK.md and prepare a Draft PR/MR. Use when the plan is approved and the user explicitly asks to implement.
 ---
 
@@ -8,34 +10,34 @@ description: Implement the next approved vertical slice from the active WORK.md
 Execute one functional vertical slice and hand it to the human for review.
 
 ## Guardrails
-- READ: `.workflow/active_task.json` then active `WORK.md` `[PLAN]`, `[BRIEF]`, and relevant `[LOG]` evidence.
-- WRITE: code changes and `WORK.md` -> append to `[LOG]` only; optional `.reposcry/` cache refresh when RepoScry is installed.
+- READ: `.workflow/active.json` first, then compatibility `.workflow/active_task.json` only if needed, then active `WORK.md` `[PLAN]`, `[BRIEF]`, and relevant `[LOG]` evidence.
+- WRITE: code changes and `WORK.md` -> append to `[LOG]` only.
 - NEVER: edit `[BRIEF]` or `[GRILL]`.
 - NEVER: implement without explicit user instruction.
-- NEVER: commit a Jira-tracked task with a Jira-less subject; if the active task source is `jira`, the commit subject MUST include the Jira key from `.workflow/active_task.json` (e.g. `fix(PROJ-123): ...`).
-- NEVER: hide the Jira key only in the commit body/footer when the task is Jira-tracked; the subject itself must carry the key.
 - NEVER: add `Signed-off-by`; only the human can certify DCO.
 - NEVER: freestyle PR/MR descriptions; use the Draft PR/MR body contract below.
 
 ## Workflow
 1. Identify the first approved unchecked slice in `[PLAN]`.
-2. Move tracked task to **In Progress** only when implementation actually starts.
-3. **Mandatory Branch Check**: You MUST run the branch enforcement script before modifying any code.
+2. **Mandatory Branch Check**: You MUST run the branch enforcement script before modifying any code.
    - Use the absolute path if possible: `<skill_location>/scripts/enforce-branch.sh`.
    - This script prevents accidental implementation on `main`/`master`.
    - If the script switches branches, you must update the `[META]` section of `WORK.md` to reflect the new branch name.
    - If the script fails, STOP and ask the human for help. Do not proceed with code changes.
-4. Optional RepoScry blast-radius pass: if `reposcry` is available, inspect impact before wide edits (`reposcry --repo . get_impact_radius <symbol> --depth 4` or related graph queries). Continue normally when RepoScry is absent.
+3. Select the executable child item, not an umbrella parent; if it is unclear, STOP and ask.
+4. Move that remote item to **In Progress** immediately before code changes.
+   - Jira: transition only when an `In Progress`-style state exists.
+   - GitHub / GitLab: use an existing repository-specific status mapping only; do not invent a label, comment, or MR change. If none exists, leave the item unchanged and record why in `[LOG]`.
+   - If a configured transition fails, STOP and ask the human; do not begin code changes.
+   - Do not mark work in progress during `/refine`, `/triage`, `/frame`, or `/plan`.
 5. Implement test-first where practical; otherwise document why not in `[LOG]`.
-6. After each edit batch, if the bundled `../scripts/reposcry-refresh.sh` helper is present and `reposcry-update` is installed, run it. RepoScry refresh failure should not block implementation. Never stage or commit `.reposcry/`; it is generated cache. `.reposcryignore` may be committed only after review as indexing policy.
-7. Run the slice verification command and available quality gates.
-8. Commit with a Conventional Commit header and `Assisted-by: [AGENT]:[MODEL] [tools]` footer (populating the agent name and model ID from the current session context).
-   - For Jira-tracked tasks, the header MUST include the Jira key in the scope position: `fix(PROJ-123): ...` or `feat(PROJ-123): ...`.
-   - If release-note tooling also needs the key in parsed text, add `Refs: PROJ-123` in the body/footer as well.
-9. Push and open a Draft PR/MR with `gh` or `glab` when a remote exists.
-   - For Jira-tracked tasks, the PR/MR title MUST also include the Jira key and should mirror the commit subject.
-10. Use a temporary body file (`--body-file` or API equivalent) for PR/MR descriptions to avoid shell quoting and markdown escaping bugs.
-11. Append summary, commit hash, and PR/MR link to `[LOG]` (Format: `YYYY-MM-DD hh:mm AM/PM`).
+6. Run the slice verification command and available quality gates.
+7. Commit using the repository's normal conventions and hooks/CI rules.
+   - If the repo or tracker expects a Jira key, preserve it where that repository normally requires it.
+   - If AI attribution trailers are required, obtain them from the repository's documented policy rather than hard-coding RPIV-specific formatting.
+8. Push and open a Draft PR/MR with `gh` or `glab` when a remote exists.
+9. Use a temporary body file (`--body-file` or API equivalent) for PR/MR descriptions to avoid shell quoting and markdown escaping bugs.
+10. Append summary, commit hash, and PR/MR link to `[LOG]` (Format: `YYYY-MM-DD hh:mm AM/PM`).
 
 ## Draft PR/MR body contract
 

package/implement/scripts/enforce-branch.sh

@@ -44,22 +44,32 @@ json_pretty() {
 
 # Find repo root to ensure paths are absolute and reliable
 REPO_ROOT=$(git rev-parse --show-toplevel)
+ACTIVE_WORKFLOW_FILE="$REPO_ROOT/.workflow/active.json"
+# Deprecated compatibility fallback during active.json migration. Remove once all readers stop depending on active_task.json.
 ACTIVE_TASK_FILE="$REPO_ROOT/.workflow/active_task.json"
-
-if [[ ! -f "$ACTIVE_TASK_FILE" ]]; then
-    echo "ERROR: No active task found at $ACTIVE_TASK_FILE."
+POINTER_FILE=""
+POINTER_LABEL=""
+
+if [[ -f "$ACTIVE_WORKFLOW_FILE" ]]; then
+    POINTER_FILE="$ACTIVE_WORKFLOW_FILE"
+    POINTER_LABEL="active.json"
+elif [[ -f "$ACTIVE_TASK_FILE" ]]; then
+    POINTER_FILE="$ACTIVE_TASK_FILE"
+    POINTER_LABEL="active_task.json"
+else
+    echo "ERROR: No active task found at $ACTIVE_WORKFLOW_FILE or $ACTIVE_TASK_FILE."
     echo "Please run /triage [source]:[id] first."
     exit 1
 fi
 
 # Read canonical active task fields
-TASK_SOURCE=$(json_read "$ACTIVE_TASK_FILE" '.source // empty')
-TASK_ID=$(json_read "$ACTIVE_TASK_FILE" '.sourceId // .id // empty')
-TASK_PATH=$(json_read "$ACTIVE_TASK_FILE" '.taskPath // .path // empty')
+TASK_SOURCE=$(json_read "$POINTER_FILE" '.source // empty')
+TASK_ID=$(json_read "$POINTER_FILE" '.sourceId // .id // empty')
+TASK_PATH=$(json_read "$POINTER_FILE" '.taskPath // .path // empty')
 
 # Prefer explicit taskPath when available (most reliable)
 if [[ -n "$TASK_PATH" ]]; then
-    echo "INFO: Using taskPath from active_task.json: $TASK_PATH"
+    echo "INFO: Using taskPath from $POINTER_LABEL: $TASK_PATH"
     if [[ "$TASK_PATH" = /* ]]; then
         WORK_MD="$TASK_PATH/WORK.md"
     else
@@ -77,9 +87,9 @@ elif [[ -n "$TASK_ID" ]]; then
     WORK_MD="$REPO_ROOT/.workflow/tasks/$TASK_FOLDER/WORK.md"
 
 else
-    echo "ERROR: No 'sourceId' or 'taskPath' found in $ACTIVE_TASK_FILE."
-    echo "Please run /triage [source]:[id] to initialize a task. Here are the file contents for debugging:" 
-    json_pretty "$ACTIVE_TASK_FILE" || true
+    echo "ERROR: No 'sourceId' or 'taskPath' found in $POINTER_LABEL."
+    echo "Please run /triage [source]:[id] to initialize a task. Here are the file contents for debugging:"
+    json_pretty "$POINTER_FILE" || true
     exit 1
 fi
 
@@ -88,8 +98,8 @@ echo "DEBUG: Computed WORK.md path: $WORK_MD"
 
 if [[ ! -f "$WORK_MD" ]]; then
     echo "ERROR: WORK.md not found at $WORK_MD."
-    echo "Checked active_task.json values:" 
-    json_pretty "$ACTIVE_TASK_FILE" || true
+    echo "Checked $POINTER_LABEL values:"
+    json_pretty "$POINTER_FILE" || true
     echo "Please ensure the task was initialized with /triage and that WORK.md exists." 
     exit 1
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raquezha/norpiv",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Bundled RPIV workflow skills for Pi, Claude, and Codex-style coding agents",
   "type": "commonjs",
   "bin": {
@@ -12,6 +12,7 @@
     "distill",
     "frame",
     "grill-with-docs",
+    "refine",
     "implement",
     "plan",
     "scripts",
@@ -36,6 +37,7 @@
   },
   "pi": {
     "skills": [
+      "refine",
       "triage",
       "frame",
       "grill-with-docs",

package/plan/SKILL.md

@@ -1,5 +1,7 @@
 ---
 name: plan
+workflow: rpiv
+workflowPhase: plan
 description: Create or revise vertical implementation slices in the active WORK.md. Use after /grill-with-docs to produce a concise, reviewable plan for implementation.
 ---
 
@@ -8,7 +10,7 @@ description: Create or revise vertical implementation slices in the active WORK.
 Map the "how" into tracer-bullet vertical slices.
 
 ## Guardrails
-- READ: `.workflow/active_task.json` then active `WORK.md` `[BRIEF]` and `[GRILL]`.
+- READ: `.workflow/active.json` / `.workflow/active_task.json` then active `WORK.md` `[BRIEF]` and `[GRILL]`.
 - WRITE: `WORK.md` -> `[PLAN]` and append to `[LOG]` only.
 - NEVER: implement code during planning.
 - NEVER: create standalone `PLAN.md`.

package/refine/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: refine
+workflow: pre-rpiv
+workflowPhase: refine
+description: "Repair tracker work-item readiness before RPIV intake. Use for jira:, github:, or gitlab: items that still need clarified outcome, acceptance criteria, or child work before /triage."
+---
+
+# Skill: refine
+
+Make a tracker item ready for engineering handoff without inventing product decisions.
+
+## Guardrails
+- READ: tracker item, linked/child work, relevant comments, and targeted repo context only when needed for ownership or feasibility.
+- WRITE: proposals in chat first; tracker comments/field edits/child creation only after explicit human approval.
+- NEVER: implement code, create branches, or start RPIV task state.
+- NEVER: invent missing product intent when a human decision is required.
+- NEVER: duplicate existing child work or spam repeated agent comments.
+- NEVER: move work across trackers.
+
+## Workflow
+1. Parse namespaced source: `jira:KEY`, `github:ID`, or `gitlab:ID`.
+2. Read the item, current structure, and recent comments.
+3. Classify readiness gaps: missing outcome, acceptance criteria, ownership, dependencies, blockers, or decomposition.
+4. For every proposed child item, state intended owner, confidence, and fallback `unassigned`. Auto-assign only when the signal is strong from the tracker, comments, or existing team ownership patterns.
+5. Decide dependency handling explicitly for each child pair or blocker:
+   - no dependency
+   - description note only
+   - real tracker link
+   Prefer actual Jira `Blocks` links when child A must precede child B.
+6. Return one outcome:
+   - `ready-single`: one executable owner, no decomposition needed
+   - `ready-decomposed`: split is needed and children, links, and owners are clear
+   - `needs-decision`: missing product decision or not truly ready-decomposed because ownership/dependencies are still muddy
+7. Propose the smallest useful tracker edits and child items before mutating anything.
+8. Before any approved mutation, walk this checklist in order:
+   - preserve product-authored text
+   - append acceptance criteria instead of rewriting existing acceptance criteria
+   - create child?
+   - assign child?
+   - link child?
+   - then mutate parent text/fields
+9. On explicit approval, apply the approved tracker edits only.
+10. Re-run idempotently: reuse existing child items and any prior agent-owned refinement marker/comment.
+11. Recommend `/triage` only once the item is execution-ready.
+
+## Output contract
+End with:
+- **Outcome**: ready-single / ready-decomposed / needs-decision
+- **Missing information**
+- **Proposed tracker edits**
+- **Proposed child work**
+- **Proposed ownership**
+- **Proposed dependency links**
+- **Next step**: approve edits / answer question / `/triage`

package/scripts/graphify-grill.py

@@ -0,0 +1,42 @@
+"""Emit bounded structural Graphify evidence from a disposable archive."""
+import json
+import sys
+from contextlib import redirect_stdout
+from pathlib import Path
+
+EDGE_LIMIT = 100
+
+
+def normalize_edge(edge):
+    return {
+        "confidence": edge.get("confidence", "EXTRACTED"),
+        "source": edge.get("source", edge.get("from", "")),
+        "target": edge.get("target", edge.get("to", "")),
+        "type": edge.get("type", edge.get("relation", "")),
+    }
+
+
+def render_evidence(graph, limit=EDGE_LIMIT):
+    edges = graph.get("edges", [])[:limit]
+    return {
+        "edges": [normalize_edge(edge) for edge in edges],
+        "truncated": len(graph.get("edges", [])) > len(edges),
+    }
+
+
+def main(root_arg):
+    root = Path(root_arg)
+    out = root / "graphify-out"
+    from graphify.extract import collect_files, extract
+
+    with redirect_stdout(sys.stderr):
+        graph = extract(collect_files(root), cache_root=out, root=root, parallel=False)
+    print(json.dumps(render_evidence(graph)))
+
+
+if __name__ == "__main__":
+    try:
+        main(sys.argv[1])
+    except Exception as error:
+        print(f"Graphify extraction failed: {error}", file=sys.stderr)
+        raise

package/scripts/graphify-grill.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Optional structural Graphify pass over committed HEAD only.
+set -u
+
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null) || { echo "WARN: Graphify skipped: not a git repository." >&2; exit 0; }
+python=${GRAPHIFY_PYTHON:-"$HOME/.graphify/venv/bin/python"}
+if [[ ! -x "$python" ]]; then
+  python="$repo_root/.graphify/venv/bin/python"
+fi
+script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+temp=$(mktemp -d "${TMPDIR:-/tmp}/norpiv-graphify.XXXXXX") || { echo "WARN: Graphify skipped: cannot create temporary directory." >&2; exit 0; }
+trap 'rm -rf "$temp"' EXIT
+
+if [[ ! -x "$python" ]]; then
+  echo "WARN: Graphify skipped: machine-wide or repo-local Python is unavailable." >&2
+  exit 0
+fi
+if ! git -C "$repo_root" archive HEAD | tar -x -C "$temp"; then
+  echo "WARN: Graphify skipped: cannot archive HEAD." >&2
+  exit 0
+fi
+if ! "$python" "$script_dir/graphify-grill.py" "$temp"; then
+  echo "WARN: Graphify failed; continue with normal source reading." >&2
+fi

package/scripts/test_graphify_grill.py

@@ -0,0 +1,21 @@
+import importlib.util
+from pathlib import Path
+
+module_path = Path(__file__).with_name("graphify-grill.py")
+spec = importlib.util.spec_from_file_location("graphify_grill", module_path)
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+
+edge = module.normalize_edge({"from": "a", "to": "b", "relation": "calls"})
+assert edge == {
+    "confidence": "EXTRACTED",
+    "source": "a",
+    "target": "b",
+    "type": "calls",
+}
+
+rendered = module.render_evidence({"edges": [{"source": str(i)} for i in range(105)]}, limit=100)
+assert len(rendered["edges"]) == 100
+assert rendered["truncated"] is True
+
+print("graphify-grill.py self-check passed")