@raquezha/norpiv 0.0.8 → 0.2.0

package/README.md

@@ -51,6 +51,7 @@ Rules:
 - **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.
+- **Evidence Classification & Gate**: `/frame` classifies task evidence requirements into `UI-sensitive`, `Formula-sensitive`, or `Backend-safe`, and records evidence status as `present`, `missing`, or `n/a`. Direct Zeplin screen links (`https://zpl.io/<id>`) or Figma frame URLs (`node-id`) are required for UI-sensitive work; attachments, generic links, and parent ticket links do not mark evidence `present`. For `UI-sensitive` work, `/plan` automatically consumes NoDesign preflight (`nodesign preflight`) to verify design evidence status, save task evidence to `.workflow/tasks/<task-id>/evidence/`, and distinguish missing provider access from missing design truth. Human waivers (`waived: <reason>`) unblock planning while preserving waiver audit records. Missing evidence causes `/plan` to flag dependent slices as `[BLOCKED]` and `/implement` to refuse code execution until unblocked or explicitly overridden. Backend-safe work uses status `n/a`.
 
 ## 📦 Install as a skill bundle
 

package/frame/SKILL.md

@@ -21,15 +21,22 @@ Turn raw task context into the stable "what/why" brief.
 3. Determine brief type:
    - **Problem** for bugs, regressions, crashes, broken behavior.
    - **Proposal** for features, enhancements, refactors, new behavior.
-4. Create or replace only the `[BRIEF]` section with:
+4. Classify task evidence requirements:
+   - **Evidence Category**: `UI-sensitive` (UI components, screens, layout), `Formula-sensitive` (math, rate tables, tier logic), or `Backend-safe` (pure backend, refactoring, infra).
+   - **Evidence Status**: `present`, `missing`, or `n/a`.
+   - **UI Evidence Rule**: `present` requires a direct Zeplin screen URL (`https://zpl.io/<id>` or `*.zeplin.io/.../screen/...`) or direct Figma screen/frame URL (`https://figma.com/design/...` with `node-id` / frame parameter) on the source ticket. Attachments, screenshots, generic project links, and links on parent/linked tickets do NOT satisfy `present` (parent links are logged as repair hints).
+   - **Formula Evidence Rule**: `present` requires explicit formula spec, truth table, or exact logic definition on ticket.
+   - **Backend-safe Exemption**: Evidence status is `n/a`.
+5. Create or replace only the `[BRIEF]` section with:
    - type and source id
+   - evidence classification (category and status)
    - current understanding
    - desired outcome
    - constraints / non-goals
    - acceptance hints if available
-5. Keep the brief concise and reviewable.
-6. **Log Activity**: Append a timestamped summary of the framing/re-framing to `[LOG]` (Format: `YYYY-MM-DD hh:mm AM/PM`). Include why the change was made if it is a pivot.
-7. End by recommending `/grill-with-docs`.
+6. Keep the brief concise and reviewable.
+7. **Log Activity**: Append a timestamped summary of the framing/re-framing to `[LOG]` (Format: `YYYY-MM-DD hh:mm AM/PM`). Include why the change was made if it is a pivot.
+8. End by recommending `/grill-with-docs`.
 
 ## Output contract
 End with:

package/grill-with-docs/SKILL.md

@@ -15,6 +15,7 @@ Challenge the brief before planning. This replaces passive ubiquitous-language c
 - 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.
+- EVIDENCE ISOLATION: Resolve task evidence from `.workflow/tasks/<task-id>/evidence/` or explicit active state references. Do not substitute arbitrary repository-root files as task evidence.
 
 ## Workflow
 1. **Context Loading**: Read the active brief, `CONTEXT.md`, and relevant `docs/agents/*`.
@@ -23,7 +24,12 @@ Challenge the brief before planning. This replaces passive ubiquitous-language c
    - Trace the data flow related to the problem/proposal.
    - Search for "Impact Surface": Who else uses or depends on these components?
 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.
+4. **Cross-check & Evidence Verification**:
+   - Compare findings against docs, ADRs, and repo patterns.
+   - **Evaluate Evidence Classification**: Check evidence status (`present`, `missing`, `n/a`).
+   - For `UI-sensitive` work: Verify the source ticket explicitly contains a direct Zeplin screen URL (`https://zpl.io/<id>` or `*.zeplin.io/.../screen/...`) or direct Figma screen/frame URL (`https://figma.com/design/...` with `node-id`). Reject attachments, screenshots, generic design links, and links present only on parent/linked tickets as direct evidence. If design links are discovered on parent/linked tickets, report them in `[GRILL]` as diagnostic context to help repair the ticket, but record evidence status as `missing`.
+   - For `Formula-sensitive` work: Verify explicit formula specifications or truth tables are on the ticket; if absent, record evidence status as `missing`.
+   - For `Backend-safe` work: Evidence status is `n/a`.
 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]`.

package/implement/SKILL.md

@@ -14,11 +14,12 @@ Execute one functional vertical slice and hand it to the human for review.
 - WRITE: code changes and `WORK.md` -> append to `[LOG]` only.
 - NEVER: edit `[BRIEF]` or `[GRILL]`.
 - NEVER: implement without explicit user instruction.
+- EVIDENCE REJECTION GATE: Before modifying code, `/implement` MUST verify that the target slice is not flagged `[BLOCKED: missing UI/formula evidence]` and evidence status is not `missing`. If blocked, STOP immediately, refuse code changes, surface what evidence is missing (direct Zeplin screen link `https://zpl.io/<id>`, direct Figma frame URL, or formula spec), and ask the human for explicit clarification or override. Never guess product UI or formula truth around a blocked state.
 - 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]`.
+1. Identify the first approved unchecked slice in `[PLAN]`. Verify the slice is not marked `[BLOCKED: missing UI/formula evidence]`. If blocked, STOP and ask the human for missing direct evidence or explicit override.
 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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raquezha/norpiv",
-  "version": "0.0.8",
+  "version": "0.2.0",
   "description": "Bundled RPIV workflow skills for Pi, Claude, and Codex-style coding agents",
   "type": "commonjs",
   "bin": {

package/plan/SKILL.md

@@ -15,16 +15,24 @@ Map the "how" into tracer-bullet vertical slices.
 - NEVER: implement code during planning.
 - NEVER: create standalone `PLAN.md`.
 - NEVER: ask whether to plan if the user invoked `/plan`; produce the plan.
+- EVIDENCE BLOCKING GATE: If task evidence status is `missing` for `UI-sensitive` or `Formula-sensitive` work, `/plan` MUST flag dependent slices as `[BLOCKED: missing UI/formula evidence]` and preserve blocked status instead of marking slices ready for implementation.
+- AUTOMATIC NODESIGN PREFLIGHT: For `UI-sensitive` work, `/plan` MUST automatically consume or run NoDesign preflight (`nodesign preflight --json --path . --task <source>:<id>`) without requiring manual preflight CLI execution.
+- EVIDENCEMAPPING: Map NoDesign preflight evidence status to RPIV evidence status: `ready` -> `present`, `missing` or `ambiguous` -> `missing`.
+- PROVIDER FAULT ISOLATION: Distinguish provider auth/access failures (`AUTH_REQUIRED`, `AUTH_REJECTED`, `ACCESS_DENIED`, `RATE_LIMITED`, `API_UNAVAILABLE`) from missing design evidence truth (`DESIGN_NOT_FOUND`, missing direct `node-id` / screen URL). Surface missing credentials or API access cleanly without treating provider auth errors as product specification failure.
+- CREDENTIAL SAFETY: Never request or pass NoDesign API tokens through model context; resolve credentials from OS keychain, environment variables, or `~/.pi-secrets/.env`.
+- HUMAN WAIVER: Allow explicit human waivers (recorded distinctly as `waived: <reason>` in `WORK.md`). Human waivers unblock implementation-ready planning while preserving explicit waiver audit state.
+- EVIDENCE ISOLATION: Resolve task evidence from active workspace `.workflow/tasks/<task-id>/evidence/` or task state. Do not scan arbitrary repository files as task evidence.
 
 ## Workflow
 1. Read the brief and grill decisions.
-2. **Branch Check**: Verify the current git branch. Planning on `main` is safe and encouraged. If you are on an unrelated feature branch, warn the human that the plan is being made on a stale or mismatched context.
+2. **Automatic NoDesign Preflight (UI-sensitive)**: If evidence category is `UI-sensitive`, invoke or consume `nodesign preflight --json --path . --task <source>:<id>`. Map `ready` status to `present`, and `missing` or `ambiguous` to `missing`. If credentials or provider access are missing (`AUTH_REQUIRED`, `ACCESS_DENIED`), surface the provider issue explicitly instead of mistaking it for a missing product design URL.
+3. **Branch Check**: Verify the current git branch. Planning on `main` is safe and encouraged. If you are on an unrelated feature branch, warn the human that the plan is being made on a stale or mismatched context.
 3. Draft thin vertical slices that are independently verifiable.
 4. Mark each slice:
    - **AFK**: agent can implement with clear checks.
    - **HITL**: human judgment, product decision, external access, or manual review required.
 5. Include dependencies and verification command(s) per slice.
-6. Write the plan into `[PLAN]` with checkboxes.
+6. Write the plan into `[PLAN]` with checkboxes. If evidence status is `missing`, mark the slice as `[BLOCKED: missing UI/formula evidence]` and explain what is needed (direct Zeplin `https://zpl.io/<id>` screen URL, direct Figma `node-id` frame URL, or formula spec).
 7. **Log Activity**: Append a timestamped entry to `[LOG]` summarizing the plan or revision (Format: `YYYY-MM-DD hh:mm AM/PM`).
 8. Recommend `/sync` if the task has a tracker, then `/implement`.
 

package/scripts/triage_helper.sh

@@ -373,7 +373,7 @@ set_metadata_status_phase() {
 }
 
 create_task() {
-    mkdir -p "$TASK_DIR"
+    mkdir -p "$TASK_DIR/evidence"
     echo "Creating task workspace in $TASK_DIR..."
 
     case "$SOURCE" in

package/sync/SKILL.md

@@ -16,6 +16,7 @@ Maintains consistency between local `.workflow` state and the remote source of t
 - **Idempotency**: If the remote Pi status already reflects the current local state, do not post or update.
 - **Human safety**: NEVER edit human-authored comments. Only update comments/notes containing the Pi sync marker.
 - **Target ownership**: Sync the executable child issue/MR/PR that the work completed, not the umbrella parent, unless the user explicitly asks for parent status. If the active GitHub issue has sub-issues, verify the PR/body/current request points to the right child before posting.
+- **Hyperlinks**: Always format issue references (e.g. `[#140](https://github.com/owner/repo/issues/140)`), source file paths, git branches, and commit hashes as explicit Markdown hyperlinks in sync comments whenever applicable.
 - **Shell safety**: Never pass markdown bodies inline through shell strings. Write bodies to files and use `--body-file` or JSON `--input` API calls so backticks and `$()` cannot execute.
 
 ## Living status marker
@@ -60,6 +61,7 @@ Do **not** use latest-comment ownership as the primary decision. Latest-comment-
 Format the message for two audiences:
 - **Stakeholders**: summarize outcome, current state, and next step.
 - **Developers**: list vertical slices, commit/PR/MR links, and verification evidence.
+- **Hyperlinking**: convert issue identifiers (`[#140](url)`), commit hashes (`[\`0011b4b\`](url)`), branch names (`[\`feat/140\`](url)`), and key file paths into explicit markdown hyperlinks so they render as interactive links.
 - **Signature and marker**: always append both the signature and `<!-- pi-sync-marker -->`.
 
 ### 3. Execution

package/triage/SKILL.md

@@ -21,6 +21,7 @@ Start RPIV by creating, resuming, or explicitly reopening a task workspace.
 - NEVER: guess source from `#123`; require explicit `jira:`, `github:`, `gitlab:`, or `local:`.
 - NEVER: strip or hide the Jira key for `jira:` tasks; preserve it in `[META]` and in the triage log so `/implement` can require it in the commit subject.
 - NEVER: mutate `done` or `archived` tasks unless the user explicitly requested `reopen`, `fresh`, or `reset`.
+- TASK EVIDENCE: Store task-acquired evidence (screenshots, attachments, PDFs, specs) under `.workflow/tasks/[source-id]/evidence/`.
 
 ## Command forms
 

package/verify/SKILL.md

@@ -15,6 +15,7 @@ The final gate for a slice or task. Verify truth before reporting progress.
 - NEVER: add `Signed-off-by`; tell the human to sign if needed.
 - NEVER: transition tracker state if verification fails.
 - NEVER: delete `.workflow` task folders without explicit user approval.
+- EVIDENCE ISOLATION: Resolve task evidence from active task workspace `.workflow/tasks/<task-id>/evidence/` or task state. Do not scan arbitrary repository files as task evidence.
 
 ## Workflow
 1. Compare code changes against `[BRIEF]` and the current `[PLAN]` slice.