sherpa-skill 2.0.6 → 2.0.7

package/skills/sherpa/rules/red-team-rules.md

@@ -0,0 +1,185 @@
+# sherpa — Red Team Rules
+
+These rules are authoritative for the RED-TEAM capability. Red Team is lifecycle Phase 13; this is engineering capability Phase 8. Do not renumber or edit the 20-phase lifecycle.
+
+## Purpose and boundaries
+
+Actively attempt to disprove project readiness. Attack the project and its claims — not the team. Identify hidden weaknesses, technical weaknesses, product weaknesses, UX weaknesses, differentiation weaknesses, judging weaknesses, demo weaknesses, evidence weaknesses, credibility risks, and failure modes.
+
+Review and recommend; do not change product scope, selected idea, approved Phase 3 architecture, Phase 4 implementation plan, application source, or Phase 5/Phase 7 results. Do not replace Phase 5 testing/security, Phase 7 UX review, judge simulation, score optimization, presentation, submission, or post-mortem work.
+
+If a proposed remediation needs database/API redesign, authentication redesign, major frontend restructuring, service restructuring, or a major dependency change, record **ARCHITECTURE CHANGE REQUIRED**, why, evidence, impact, estimated effort, alternative, risk, and recommendation. Stop that remediation pending human-controlled architecture approval.
+
+## Readiness and source of truth
+
+Read `.sherpa/project-state.md`, the Phase 2 idea evaluation, Phase 3 project plan, Phase 4 implementation evidence, Phase 5 testing/security evidence, and Phase 7 UX evidence before inspecting UX. Red Team review normally requires implementation baseline, Phase 5 evidence, and Phase 7 evidence. If implementation is incomplete or readiness cannot be established, report **RED TEAM REVIEW = BLOCKED** or **LIMITED**; do not imply a review occurred.
+
+Use the selected idea as context only. Never change it. Consume existing Phase 2 idea evaluation, Phase 3 project plan, Phase 4 implementation state, Phase 5 test/security findings, and Phase 7 UX findings. If a red-team question requires an automated or functional test, mark **TEST REQUIRED** and route it to the Phase 5 process; do not execute or duplicate that engine.
+
+## Evidence model
+
+Every claim is labeled FACT, INFERENCE, ASSUMPTION, or UNKNOWN. FACT identifies inspected source, UI, state, test, or direct observation. INFERENCE states its evidence and reasoning. ASSUMPTION is an explicit provisional premise. UNKNOWN includes what is missing and why. Every finding cites reproducible evidence: path/line, route/screen, steps, result, or evidence artifact. Never claim an interaction, state, or behavior was tested when it was not.
+
+Generated sherpa artifacts are not independent evidence. Evidence must trace back to repository inspection, actual execution, external verification, or explicit human-provided information. Do not treat previous AI-generated recommendations as facts.
+
+## Attack surfaces
+
+Inspect applicable attack surfaces: Product, Differentiation, Technical, Reliability, Security/Trust, Privacy, UX, Accessibility, Responsive, Demo, Performance, Evidence, Credibility, Deployment.
+
+Challenge every important project claim. Distinguish "the application performs the algorithm" from "the algorithm produces high-quality outcomes." Challenge unsupported statistics, unsupported performance claims, unsupported user claims, unsupported AI claims, "production-ready" claims, "secure" claims, "scalable" claims, "real-time" claims, and "zero vulnerabilities" claims.
+
+Functional abuse scenarios include invalid input, missing input, duplicate actions, repeated submissions, unexpected navigation, invalid sequences, and unsupported actions.
+
+## Adversarial actors
+
+The system considers applicable perspectives:
+
+| Actor | Perspective |
+|-------|-------------|
+| Malicious User | Attempts to abuse the product |
+| Careless User | Makes realistic mistakes |
+| Curious User | Explores unsupported behavior |
+| Skeptical Judge | Challenges claims and asks difficult questions |
+| Unlucky Runtime | Produces timing, network, storage, or dependency failures |
+| Invalid Input | Provides malformed or unexpected data |
+| Empty Environment | Removes expected data/resources |
+| Partial Failure | Breaks one component while others remain operational |
+| Repeated Action | Performs the same action multiple times |
+| Boundary Condition | Uses minimum, maximum, zero, empty, unusually large, or unusual values |
+
+Every applicable actor must be considered at least once. Actors not applicable to the project are marked NOT_APPLICABLE with justification.
+
+## Adversarial scenarios
+
+Each scenario contains: Scenario ID, Attack Surface, Attacker/Skeptical Judge Perspective, Preconditions, Attack, Expected Failure, Actual Result, Evidence, Severity, Confidence, Finding, Mitigation, Verification Method, Status.
+
+Only scenarios applicable to the actual project should be executed. Non-applicable scenarios are marked NOT_APPLICABLE with justification.
+
+## Finding model
+
+Each finding contains: Finding ID, Title, Attack Surface, Category, Severity, Confidence, Affected Flow/Component, Claim Challenged, Observation, Evidence, Attack/Reproduction Steps, User Impact, Judge Impact, Technical Impact, Recommended Mitigation, Required Owner, Required Phase, Architecture Impact, Verification Method, Status, Verification Evidence.
+
+Categories: PRODUCT, DIFFERENTIATION, TECHNICAL, RELIABILITY, SECURITY, PRIVACY, UX, ACCESSIBILITY, RESPONSIVE, DEMO, PERFORMANCE, EVIDENCE, CREDIBILITY, DEPLOYMENT, OTHER.
+
+Severity: CRITICAL / HIGH / MEDIUM / LOW / INFO / UNKNOWN. CRITICAL blocks the primary flow or makes the demo fundamentally unusable; HIGH is a major MVP weakness or significant reliability issue; MEDIUM is a meaningful weakness with a workaround; LOW is minor friction; INFO is an observation; UNKNOWN means insufficient evidence. Do not inflate severity.
+
+Confidence: HIGH / MEDIUM / LOW / UNKNOWN. Depends on evidence quality. Do not give HIGH confidence to speculation.
+
+## Likelihood
+
+Use: VERY_HIGH / HIGH / MEDIUM / LOW / VERY_LOW / UNKNOWN. Never fabricate likelihood. If evidence is insufficient, record UNKNOWN.
+
+## Recoverability
+
+Use: AUTOMATIC / EASY / MANUAL / DIFFICULT / NONE / UNKNOWN. Evaluate whether the user/system can recover from the failure.
+
+## Red Team Scoring
+
+Do NOT create a fake official hackathon score. Red Team may calculate a risk-priority indicator for internal ordering. If used, explicitly label it:
+
+```
+INTERNAL RED TEAM PRIORITIZATION
+NOT OFFICIAL JUDGING SCORE
+```
+
+Never mix it with Phase 10 score optimization.
+
+## Critical Finding Rule
+
+A CRITICAL finding must prevent unconditional RED_TEAM_QUALITY_GATE = READY unless it is VERIFIED_MITIGATED or explicitly ACCEPTED_RISK with human authority. Do not silently downgrade a CRITICAL finding.
+
+## Findings and status
+
+Finding status: OPEN / IN_PROGRESS / MITIGATED / VERIFIED / ACCEPTED_RISK / BLOCKED / UNKNOWN / NOT_APPLICABLE / WONT_FIX. A finding may only become VERIFIED after actual verification evidence exists. Never mark a mitigation verified merely because a recommendation was written.
+
+## Mitigation routing
+
+Every meaningful finding determines where action belongs:
+
+- PHASE 4 — IMPLEMENTATION: technical code bugs, implementation gaps
+- PHASE 5 — TESTING / SECURITY: missing security verification, missing test coverage
+- PHASE 7 — UX: UX issues, usability problems
+- PHASE 8 — RED TEAM: red-team-specific mitigations, scenario validation
+- HUMAN ARCHITECTURE APPROVAL: architecture limitations
+- FUTURE PHASE: judge/pitch issues, presentation issues
+- ACCEPTED RISK: risks explicitly accepted by human
+
+Do not fix issues by silently modifying another phase.
+
+## Priority order
+
+1. CRITICAL MVP failure
+2. CRITICAL demo failure
+3. confirmed security/trust issue
+4. HIGH reliability risk
+5. HIGH differentiation weakness
+6. unsupported major claim
+7. HIGH UX/demo friction
+8. important technical risk
+9. evidence gaps
+10. medium risks
+11. low-risk polish
+
+Do not prioritize cosmetic issues over project-breaking risks.
+
+## Time-aware red team strategy
+
+Use verified remaining time:
+
+- >24 hours: Broad adversarial testing + mitigation + regression
+- 12–24 hours: Critical flows + high-risk technical/product weaknesses + demo reliability
+- 6–12 hours: Primary user journey + demo + critical reliability + major claims
+- 2–6 hours: Demo-breaking scenarios + critical MVP failures + obvious credibility risks
+- <2 hours: Freeze features. Attack only: demo path, critical MVP, obvious reliability failures, obvious unsupported claims, severe trust/security issues
+
+If time is UNKNOWN: TIME STRATEGY = UNKNOWN. Never fabricate remaining time.
+
+## Red team quality gate
+
+Gate values: NOT_READY / RED_TEAM_IN_PROGRESS / BLOCKED / CONDITIONAL / READY.
+
+READY requires:
+- critical attack surfaces reviewed
+- no unresolved critical project-breaking finding
+- critical demo path challenged
+- major claims challenged
+- high-severity findings resolved or explicitly accepted
+- security/UX dependencies clearly routed
+- verification evidence for claimed mitigations
+- limitations documented
+- remaining risks visible
+- evidence-backed conclusions
+
+A project can be RED TEAM READY while still having accepted medium/low risks. A strong red-team review should find weaknesses.
+
+## State and artifacts
+
+Keep `.sherpa/project-state.md` compact. Add only these fields:
+
+| Field | Values |
+|-------|--------|
+| Red Team Status | NOT_STARTED | IN_PROGRESS | BLOCKED | COMPLETE |
+| Red Team Baseline | UNKNOWN | VERIFIED |
+| Critical Attack Surfaces | UNKNOWN | IDENTIFIED | REVIEWED |
+| Critical Findings | UNKNOWN | PASS | FAIL | BLOCKED |
+| High Findings | UNKNOWN | PASS | FAIL | BLOCKED |
+| Red Team Quality Gate | NOT_READY | RED_TEAM_IN_PROGRESS | BLOCKED | CONDITIONAL | READY |
+
+Detailed material belongs in `.sherpa/red-team.md` and `.sherpa/red-team/{claim-NNN,scenario-NNN,finding-NNN,verification-NNN}.md`. Do not turn project-state.md into a giant report.
+
+## Human control
+
+Human approval is required for:
+- idea changes
+- architecture changes
+- major scope changes
+- destructive refactors
+- accepting CRITICAL risk
+- accepting HIGH security/privacy risk
+- irreversible changes
+
+AI recommends. Human decides. Phase 8 never changes the selected idea or silently redesigns architecture.
+
+## Exactly one primary next action
+
+Every successful Red Team workflow execution returns exactly one PRIMARY NEXT ACTION. Do not create another NEXT engine.

package/skills/sherpa/rules/research-rules.md

@@ -0,0 +1,184 @@
+# sherpa — Research Rules
+
+Defines authoritative behavior for the Research capability. Research is a reusable capability
+that supports multiple lifecycle phases (Understand Rules, Analyze Problem, Generate Ideas,
+Validate Ideas, Research Market, Select Idea, Architecture, Data Architecture, Development
+Plan, Testing, Security, UX, Judge Simulation, Score Optimization, Demo Preparation,
+Presentation, Final Audit, Submission, Post-Mortem). It does not create a new lifecycle phase.
+
+## 1. Purpose
+
+Research provides transparent, evidence-based answers to research questions. It is not
+autonomous web browsing; it is a disciplined process of finding, verifying, and organizing
+evidence to support hackathon decisions.
+
+Every research claim must carry an evidence tag: FACT, INFERENCE, ASSUMPTION, or UNKNOWN.
+Every research output must trace back to repository inspection, actual execution, external
+verification, or explicit human-provided information.
+
+## 2. Core Principles
+
+### Evidence Discipline
+
+Classify repository observations and claims as FACT, INFERENCE, ASSUMPTION, or UNKNOWN.
+Execution claims require direct execution evidence, including the command, result, and scope.
+A present test/configuration file does not prove it works; a test failure must remain visible.
+Generated sherpa state, plans, tasks, and recommendations are planning records, not
+independent repository facts or execution evidence.
+
+Never invent a commit, installed dependency, test/build result, environment value, API behavior,
+deployment result, completion claim, or remaining time. When Git is unavailable, record
+`Git baseline = UNKNOWN`.
+
+### Human Authority
+
+Research is advisory. The human team decides what to believe and what to do. Research does not
+auto-approve ideas, architecture, implementation, or any decision. Research findings route to
+the appropriate phase but do not replace that phase's engine.
+
+### Time Awareness
+
+Research should be time-bounded. Do not spend unlimited time searching. If remaining time is
+UNKNOWN, record `TIME STRATEGY = UNKNOWN` and give a time-neutral research order.
+
+## 3. Research Pipeline Stages
+
+### Stage 1: Input
+
+**Read from `.sherpa/project-state.md`:**
+- Hackathon name, deadline, time remaining
+- Judging criteria and weights (or UNKNOWN)
+- Problem statement
+- Target users (if known)
+
+**Accept from user:**
+- Research question (one sentence)
+- Scope (what is in scope, what is out of scope)
+- Depth (calibration, standard, deep)
+
+**If no research question provided:**
+- Report "No research question provided."
+- Ask user to supply a research question before evaluation can run.
+- Stop.
+
+### Stage 2: Research Plan
+
+Define:
+- What needs to be found
+- Where to look (repository, web, documentation, tests)
+- Evidence quality threshold
+- Time budget
+
+Record the research plan in `.sherpa/evidence/research/<research-query>.md`.
+
+### Stage 3: Retrieve
+
+Retrieve candidate evidence from:
+- Repository source code, config, tests, docs
+- Web search (if available and permitted)
+- Team input
+- Existing sherpa artifacts
+
+Save raw retrieval results to `.sherpa/evidence/research/`.
+
+### Stage 4: Verify
+
+For each candidate evidence item:
+- Verify the source is real and accessible
+- Check the claim against the source text
+- Verify numbers, dates, entity names match exactly
+- Check polarity/negation (does the source say the opposite?)
+- Check temporal consistency (dates, versions)
+
+### Stage 5: Analyze
+
+Classify each claim as FACT, INFERENCE, ASSUMPTION, or UNKNOWN.
+- FACT: directly verified from source
+- INFERENCE: logical conclusion from facts
+- ASSUMPTION: provisional premise not yet verified
+- UNKNOWN: no information available
+
+### Stage 6: Synthesize
+
+Combine evidence into a coherent answer. Address:
+- What is known
+- What is unknown
+- What assumptions must hold
+- What the evidence does and does not support
+
+### Stage 7: Decide
+
+Determine what the research means for the project decision:
+- Does it support proceeding?
+- Does it raise blockers?
+- What assumptions must hold?
+- What is the recommended next action?
+
+### Stage 8: Persist
+
+Save the research record to `.sherpa/evidence/research/<research-query>.md`.
+Include all evidence, gates, decisions, and unknowns.
+
+## 4. Evidence Model
+
+| Field | Values |
+|-------|--------|
+| type | FACT | INFERENCE | ASSUMPTION | UNKNOWN |
+| value | The claim |
+| source | URL, file path, or "team input" |
+| confidence | low | medium | high |
+
+Rules:
+- No claim may be tagged FACT unless directly verified from source
+- No claim may be tagged INFERENCE without explicit reasoning
+- ASSUMPTION must be explicitly marked as provisional
+- UNKNOWN means no information available
+- Never claim research was performed unless evidence was actually retrieved
+
+## 5. Source Priorities
+
+Priority order for evidence:
+1. Official documentation / official repository / official specification
+2. Repository source code and tests (direct inspection)
+3. Team input (explicitly attributed)
+4. Secondary sources (blog posts, tutorials, secondary docs)
+5. General web search results (lowest confidence)
+
+## 6. Source Consistency
+
+When multiple sources conflict:
+- Record each claim separately with its source
+- Do not silently reconcile contradictions
+- Flag the contradiction explicitly
+- Mark conflicting claims as UNKNOWN until resolved
+
+## 7. Time Awareness
+
+- If remaining time is UNKNOWN, record TIME STRATEGY = UNKNOWN
+- Do not spend unlimited time on research
+- If time is limited, prefer direct repository evidence over web search
+- Record time spent on research if it exceeds a reasonable threshold
+
+## 8. Human Authority
+
+Research recommends; the human decides. Research does not:
+- Auto-approve ideas
+- Auto-approve architecture
+- Auto-approve implementation
+- Change the selected idea
+- Silently redesign architecture
+- Replace Phase 5/7/8 engines
+
+Research findings route to the appropriate phase but do not replace it.
+
+## 9. Output Contract
+
+After each research invocation, return:
+- Research question
+- Evidence found (with sources and confidence)
+- Contradictions found (if any)
+- Unknowns
+- Decision/recommendation
+- Exactly one PRIMARY NEXT ACTION
+
+All research artifacts live in `.sherpa/evidence/research/`.