sherpa-skill 2.0.6 → 2.0.7

package/skills/sherpa/rules/testing-security-rules.md

@@ -0,0 +1,87 @@
+# sherpa — Testing + Security Rules
+
+Defines authoritative Phase 5 behavior. Phase 5 inspects the implemented project, creates test/security plans, executes applicable checks, records evidence, and evaluates quality. Phase 4 is a frozen dependency: never modify its rules, templates, or workflow. Phase 5 does not replace Phase 4 or silently modify application code or architecture.
+
+## 1. Readiness and evidence first
+
+Read `.sherpa/project-state.md`, the Phase 3 project plan, and `.sherpa/implementation-plan.md` before normal testing. Read artifacts at explicitly referenced stable paths when needed. Inspect the actual repository and test baseline before making claims.
+
+- If `Implementation status = NOT_STARTED`, report `Testing blocked until implementation exists.` Do not run a normal project test campaign.
+- If implementation status, selected idea, or required plans are missing/UNKNOWN, mark readiness `UNKNOWN` or `BLOCKED`; do not infer readiness from an artifact alone.
+- If status is `IN_PROGRESS`, test implemented scope only and label incomplete flows accordingly. If status is `BLOCKED`, tests may be run only for an explicitly bounded existing scope; overall quality cannot be READY while the blocker remains unexplained.
+- Implementation status `COMPLETE` permits testing; it does not prove quality.
+
+Every test/security assertion uses one status: `PLANNED`, `EXECUTED`, `PASSED`, `FAILED`, `BLOCKED`, or `UNKNOWN`. A pass requires direct execution evidence (command/procedure, scope, result, and output or report). An unexecuted check is never PASSED. A missing test framework is `UNKNOWN` or `NOT PRESENT`, not FAILED. A broken/unavailable environment is `BLOCKED`.
+
+Generated plans, reviews, and finding records are not independent execution evidence. Do not invent tool availability, test results, vulnerabilities, scan results, CI status, or dependency audit results.
+
+## 2. Test baseline and categories
+
+Record observed test framework/runner, test directories/files, scripts, build/lint/typecheck commands, API/E2E setup, CI, runtime, application structure, configuration/environment names, test data, fixtures, mocks, and known failures. Do not expose secret values. For each item state the evidence source or UNKNOWN.
+
+Use only applicable categories: `UNIT`, `INTEGRATION`, `E2E`, `UI`, `API`, `SECURITY`, `PERFORMANCE`, `ACCESSIBILITY`, and `MANUAL`. No project must use all categories. Do not describe a script or test file as passing until it has actually been run.
+
+Prioritize in order: critical user flows; MUST HAVE MVP behavior; authentication/authorization where applicable; data validation/integrity; API boundaries; error handling; security-sensitive paths; regression-prone areas; secondary features; optional features. Do not spend limited time on optional checks while critical flows remain unverified.
+
+## 3. Test execution and failures
+
+Use `templates/test-plan.md` at `.sherpa/test-plan.md` and `templates/test-result.md` at `.sherpa/testing/test-NNN.md`. Record planned tests separately from executed results. Before execution, state expected result and relevant scope. After execution, capture exact command/procedure, exit/result, relevant output, date/time, and affected revision when available.
+
+- Mark a check `EXECUTED` while evidence is being recorded; mark `PASSED` only when observed results meet its expected result.
+- Preserve failures as `FAILED` with output, impact, and affected component. Do not relabel them PASSED without a rerun that succeeds.
+- If a test cannot run due to absent tools, dependencies, data, or environment, mark `BLOCKED` and identify the blocker. Do not install dependencies merely to make a test possible.
+- Record tests not applicable with a reason; do not fabricate coverage.
+
+## 4. Bounded security review
+
+Use `templates/security-review.md` at `.sherpa/security-review.md` and `templates/security-finding.md` at `.sherpa/security/finding-NNN.md`. Every review states scope, files/areas inspected, method, limitations, and unknowns. Never claim a complete security audit from bounded inspection. Use the phrase `No confirmed vulnerabilities identified within the inspected scope.` only when it is accurate; it does not imply the whole application is safe.
+
+Cover applicable areas: authentication, authorization/access control, input validation, output encoding, injection, secrets/environment, sensitive data, file/upload handling, API exposure, CORS, CSRF, XSS, SQL/NoSQL injection, command execution, path traversal, dependency vulnerabilities, rate limiting, logging, error leakage, and session/token handling. Mark uninspected or uncertain areas `UNKNOWN`. Classify observations `FACT`, `INFERENCE`, `ASSUMPTION`, or `UNKNOWN`, with source and confidence. Do not label a vulnerability without supporting evidence.
+
+Use severity `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO`, or `UNKNOWN`, based on exploitability, impact, affected surface, likelihood, and evidence. Do not inflate severity. Record confidence as `HIGH`, `MEDIUM`, `LOW`, or `UNKNOWN` separately from severity.
+
+For dependency auditing, use an already-available project-native audit tool where practical. Record the exact command and results. If no appropriate tool is available, set dependency security status to `UNKNOWN`. Never install an auditor or automatically upgrade dependencies as part of review.
+
+## 5. Remediation and regression
+
+For each actionable finding record finding, impact, recommended remediation, approval/implementation decision required, focused verification method, and regression checks. Source changes and dependency upgrades are implementation work: route them through the approved Phase 4 process. Phase 5 may verify a fix after it exists; a proposed patch is not a fixed finding.
+
+Mark a finding `FIXED` only after focused verification evidence passes. Meaningful fixes require identifying directly affected tests, related tests, critical user-flow checks, and security regression checks where applicable. If appropriate regression cannot run, status is `BLOCKED` or `UNKNOWN`, not verified.
+
+## 6. Quality gate
+
+Allowed quality gate values: `NOT_READY`, `TESTING_IN_PROGRESS`, `BLOCKED`, `CONDITIONAL`, `READY`.
+
+`READY` requires all applicable critical tests to be executed and passed; critical failures resolved or explicitly accepted by a human; critical security findings fixed and verified or explicitly accepted by a human; no unexplained blocker; and evidence-backed status. A successful build alone is insufficient. Missing/unverified information, an open critical finding, or an unverified critical fix prevents READY. Keep the gate CONDITIONAL or BLOCKED when applicable tests, reviews, or regression evidence remain unavailable.
+
+## 7. Time-aware testing
+
+Use the existing project deadline/time. Do not calculate a false estimate or invent a deadline.
+
+| Time remaining | Focus |
+|---|---|
+| >24h | Broad testing, security review, regression, and quality |
+| 12–24h | MVP critical paths, security, high-value regression |
+| 6–12h | Critical user flow, security-sensitive paths, demo reliability |
+| 2–6h | Smoke tests, critical security checks, recent-change regression |
+| <2h | Freeze features; test core demo, critical failures, obvious security risks, runtime-critical behavior |
+| UNKNOWN | `TIME STRATEGY = UNKNOWN`; time-neutral prioritization |
+
+## 8. Compact project state
+
+Add/update only these Phase 5 fields in `.sherpa/project-state.md`:
+
+| Field | Allowed values |
+|---|---|
+| Testing status | `NOT_STARTED`, `IN_PROGRESS`, `BLOCKED`, `COMPLETE` |
+| Test baseline | `UNKNOWN`, `VERIFIED` |
+| Security review | `UNKNOWN`, `IN_PROGRESS`, `COMPLETE` |
+| Critical test status | `UNKNOWN`, `PASS`, `FAIL`, `BLOCKED` |
+| Critical security status | `UNKNOWN`, `PASS`, `FAIL`, `BLOCKED` |
+| Quality gate | `NOT_READY`, `TESTING_IN_PROGRESS`, `BLOCKED`, `CONDITIONAL`, `READY` |
+
+Do not add arbitrary fields or put detailed test/finding data in state. `Testing status = COMPLETE` means the defined Phase 5 test/review scope is complete, not that every test passed. Do not alter the selected idea, architecture, MVP, or Phase 4 implementation status.
+
+## 9. Output
+
+Return exactly one `PRIMARY NEXT ACTION`. Include readiness, scope, test/security status, executed evidence and failures, blockers/unknowns, quality gate, and one next action. Never start Phase 6.

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

@@ -0,0 +1,89 @@
+# UX Review Rules
+
+These rules are authoritative for the UX-REVIEW capability. UX review is lifecycle Phase 12; this is engineering capability Phase 7. Do not renumber or edit the 20-phase lifecycle.
+
+## Purpose and boundaries
+
+Evaluate whether the strongest user journeys are understandable, usable, reliable, accessible within a defined scope, responsive where tested, and convincing in a demo. Prioritize user outcomes over aesthetic preference. Review and recommend; do not change product scope, selected idea, approved Phase 3 architecture, Phase 4 implementation plan, or application source. Do not replace Phase 5 testing/security, 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 3 project plan, Phase 4 implementation plan/tasks, and Phase 5 test results/security review/findings before inspecting UX. UX review normally requires implementation READY/COMPLETE (or the project's explicit equivalent) and Phase 5 evidence showing the relevant scope is tested/reviewed. If implementation is NOT_STARTED, incomplete, or readiness cannot be established, report **UX review BLOCKED** or **NOT_READY**; do not imply a review occurred. A bounded static baseline may be offered only when clearly separated from a UX review and dynamic claims remain UNKNOWN.
+
+Use the selected idea as context only. Never change it. Consume existing Phase 5 failures, blocked tests, security findings, and regression risks. If a UX 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, viewport/device, steps, result, or evidence artifact. Never claim an interaction, viewport, assistive technology, or state was tested when it was not.
+
+Never convert UNKNOWN into FACT. If evidence is unavailable, record UNKNOWN and explain what is missing and why.
+
+Finding observation status is one of: OBSERVED, SUPPORTED, INFERRED, UNKNOWN, NOT_TESTED.
+- OBSERVED: Directly visible or reproducible UX behavior.
+- SUPPORTED: Strongly supported by available evidence such as screenshots, tests, source inspection, or runtime evidence.
+- INFERRED: Reasonable conclusion based on available evidence but not directly verified.
+- UNKNOWN: Insufficient evidence.
+- NOT_TESTED: The relevant interaction or condition was not actually exercised.
+
+Do not collapse these states. Finding workflow status is OPEN, IN_PROGRESS, FIXED, ACCEPTED_RISK, BLOCKED, or UNKNOWN. Do not confuse these status sets. A proposed change is not a fix. FIXED requires focused verification evidence and relevant regression consideration.
+
+## Baseline and flow review
+
+Inspect the actual project and record root/revision, frontend and backend relationship, routes/entry points, page/component structure, styles/design system/UI libraries, responsive CSS/breakpoints, forms/validation, loading/error/empty/success/disabled/retry/progress/confirmation states, navigation, authentication where applicable, accessibility semantics, test infrastructure, existing screenshots/evidence, known UX issues, and limitations. Mark absent or unavailable details UNKNOWN. If there is no frontend, record **UI = NOT PRESENT / UNKNOWN** and state the limited UX scope.
+
+Review information architecture: content organization, page structure, grouping, terminology, discoverability, information density, and logical sequencing. Evaluate whether users can understand what belongs together, whether important information is easy to find, whether labels are meaningful, and whether the structure is predictable.
+
+Identify and review relevant journeys in this order: first entry; primary value proposition; critical MVP action; result/output; error recovery; return/repeat use; demo/judge flow. For each flow record goal, target user, entry, preconditions, ordered steps, expected/observed outcome, friction, severity, evidence, observation status, and recommended action. A flow can be UNKNOWN or BLOCKED; never fabricate observed behavior.
+
+Review clarity, labels, terminology, navigation/location, discoverability, actions, destructive intent, feedback, forms/validation/preserved input/defaults, content grouping, hierarchy, cognitive load, concrete visual hierarchy/usability consequences, and all applicable feedback states. Distinguish confirmed omissions from uninspected states.
+
+## Accessibility and responsive boundaries
+
+Record accessibility scope and limitations. Check applicable keyboard order and operability, visible focus, semantics, names/labels/form associations, contrast, zoom/text scaling, alternative text, ARIA correctness, error announcements, reduced motion, and touch target usability. Do not claim WCAG compliance without evaluation against a named version/level and defined scope. Prefer bounded language such as “No confirmed issue identified within the inspected scope.”
+
+For responsive behavior record tested viewports and examine overflow/clipping, navigation, forms, controls, cards/tables/modals, touch behavior, spacing, and typography. Review mobile/tablet/desktop only when actually inspected. Untested sizes are UNKNOWN, never PASS.
+
+## Findings and severity
+
+Each finding includes a stable ID, title, category, severity, affected flow and component, concrete observation, evidence, user impact, reproduction steps, remediation, architecture impact, verification method, workflow status, and verification evidence. Categories: USABILITY, NAVIGATION, ACCESSIBILITY, RESPONSIVE, VISUAL_HIERARCHY, FORM, FEEDBACK, ERROR_HANDLING, ONBOARDING, CONTENT, CONSISTENCY, DEMO_FLOW, OTHER.
+
+Confidence is recorded separately from severity as HIGH, MEDIUM, LOW, or UNKNOWN.
+
+Severity considers flow criticality, frequency, blockage/confusion, accessibility and demo impact, recovery cost, and evidence confidence. CRITICAL blocks the primary journey or makes the demo fundamentally unusable; HIGH is major friction in a critical MVP flow; MEDIUM is meaningful with a workaround; LOW is minor friction/polish; INFO is an opportunity; UNKNOWN means evidence is insufficient. Do not inflate severity.
+
+Priority uses P0, P1, P2, P3:
+- P0: Critical UX blocker that prevents the primary task or demo; must be fixed or explicitly accepted.
+- P1: High user/demo impact; fix before submission if time permits.
+- P2: Meaningful UX weakness; fix after P0/P1 if time remains.
+- P3: Minor polish; only if all higher priorities are complete.
+
+Do not confuse severity and priority. HIGH severity does not automatically mean P0 if the fix cannot be safely completed within remaining time.
+
+Conflicting UX evidence is recorded as a separate finding; do not silently reconcile contradictions between observations.
+
+## Remediation, regression, and human authority
+
+For each finding connect evidence → impact → recommendation → human/implementation decision when required → implementation through the existing Phase 4 process → focused UX verification → regression consideration (and Phase 5 test when needed) → evidence. Do not implement fixes as part of UX review. Do not mark FIXED without evidence. Do not mark a risk accepted without explicit human acceptance recorded in the project's decision evidence.
+
+Phase 7 never changes architecture or selected idea. It may recommend and size a change; explicit human approval and the existing architecture/implementation processes are required. Do not claim regression passed without an executed check and result.
+
+## Time strategy
+
+- `>24h`: broad UX, accessibility, responsive review, then targeted polish.
+- `12–24h`: critical flows, major usability, accessibility, demo polish.
+- `6–12h`: critical journey, demo flow, obvious blockers, responsive essentials.
+- `2–6h`: demo flow, navigation, forms, obvious breakage.
+- `<2h`: freeze features; fix only demo blockers, critical usability/accessibility blockers, broken navigation/forms, or demo-device responsive failure.
+- Unknown time: `TIME STRATEGY = UNKNOWN`; do not infer a deadline or remaining hours.
+
+Within any window, critical blockers outrank low-impact visual polish.
+
+## State, artifacts, and quality gate
+
+Keep detailed evidence in `.sherpa/ux-review.md` and `.sherpa/ux/{flow-NNN,finding-NNN,verification-NNN}.md`. Add only these compact fields to the project's `.sherpa/project-state.md`, and only if the file already exists / is being legitimately updated by the workflow: UX status (`NOT_STARTED | IN_PROGRESS | BLOCKED | COMPLETE`); UX baseline (`UNKNOWN | VERIFIED`); Critical flows (`UNKNOWN | IDENTIFIED | REVIEWED`); Critical UX status (`UNKNOWN | PASS | FAIL | BLOCKED`); Accessibility status (`UNKNOWN | PASS | FAIL | BLOCKED`); Responsive status (`UNKNOWN | PASS | FAIL | BLOCKED`); UX quality gate (`NOT_READY | REVIEW_IN_PROGRESS | BLOCKED | CONDITIONAL | READY`). Do not change Phase 1 template/workflow files or add other state fields. Do not set UX COMPLETE merely because a review document exists.
+
+Gate values: NOT_READY, REVIEW_IN_PROGRESS, BLOCKED, CONDITIONAL, READY. READY requires critical flows reviewed; no unexplained critical blocker; critical accessibility issues resolved or explicitly accepted; applicable critical responsive issues resolved or explicitly accepted; major navigation/usability issues addressed or accepted; findings evidence-backed; every claimed fix verified; and limitations documented. Unknown applicability or missing evidence prevents READY and may yield CONDITIONAL/BLOCKED. A polished appearance alone is insufficient.
+
+Return exactly one **PRIMARY NEXT ACTION**, chosen from the highest-impact unresolved blocker or next required human decision. Do not create another NEXT/lifecycle engine. Never silently change scope or fabricate observations, tests, fixes, approvals, or remaining time.

package/skills/sherpa/src/config_manager.py

@@ -0,0 +1,474 @@
+"""
+Sherpa Configuration Manager
+
+Defines authoritative Phase 1 behavior: initialization, collection, validation,
+and persistent storage of project-specific information in `.env.sherpa`.
+
+Design principles:
+- `.env.sherpa` lives in the project repository root (NOT in the skill directory).
+- `.env.hackathon` is read only as a deprecated fallback when the new file is absent.
+- It is the single source of truth for project-specific configuration.
+- All fields default to UNKNOWN until explicitly provided.
+- Human-editable: users may edit directly; skill must preserve manual edits.
+- No secrets: API keys and secrets go in `.env`, never in `.env.sherpa`.
+- Idempotent: running init multiple times must not duplicate or destroy data.
+
+Configuration categories:
+  HACKATHON_IDENTITY   - hackathon name, platform, URL, dates, rules
+  PROBLEM_IDEA         - problem statement, target users, selected idea, MVP
+  TECH_STACK           - programming languages, frontend, backend, database, AI/ML
+  SUBMISSION           - requirements, demo status, PPT status, deployment
+  TECHNICAL_CONSTRAINTS - budget, time, team size, constraints
+  ARCHITECTURE_DECISIONS - architecture summary, key differentiators
+  PROGRESS             - completed work, current work, blocked work, risks
+  DELIVERABLES         - demo status, PPT status, documentation, deployment URL
+  SUBMISSION           - submission requirements, team info, team captain
+"""
+
+from __future__ import annotations
+
+import configparser
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+ENV_SHERPA_FILENAME = ".env.sherpa"
+LEGACY_ENV_FILENAME = ".env.hackathon"
+ENV_FILE = ".env"
+
+# Category -> list of field names
+CATEGORY_FIELDS: dict[str, list[str]] = {
+    "HACKATHON_IDENTITY": [
+        "HACKATHON_NAME",
+        "HACKATHON_PLATFORM",
+        "HACKATHON_URL",
+        "HACKATHON_DASHBOARD_URL",
+        "START_DATE_TIME",
+        "DEADLINE_DATE_TIME",
+        "TIMEZONE",
+        "HACKATHON_ORGANIZER",
+        "HACKATHON_CONTACT",
+        "HACKATHON_THEME",
+        "ELIGIBILITY_REQUIREMENTS",
+        "PRIZE_INFORMATION",
+    ],
+    "PROBLEM_IDEA": [
+        "PROBLEM_STATEMENT",
+        "TARGET_USERS",
+        "SELECTED_IDEA",
+        "PRODUCT_CONCEPT",
+        "MVP_SCOPE",
+        "MVP_FEATURES",
+        "KEY_DIFFERENTIATORS",
+    ],
+    "TECH_STACK": [
+        "PROGRAMMING_LANGUAGES",
+        "FRONTEND_FRAMEWORK",
+        "BACKEND_FRAMEWORK",
+        "DATABASE",
+        "AI_ML_PROVIDER",
+        "AI_MODEL_NAME",
+        "DEPLOYMENT_PLATFORM",
+        "OTHER_TECHNOLOGIES",
+    ],
+    "SUBMISSION": [
+        "DEMO_STATUS",
+        "PPT_STATUS",
+        "DOCUMENTATION_STATUS",
+        "DEPLOYMENT_URL",
+        "GITHUB_REPOSITORY_URL",
+        "DEMO_URL",
+    ],
+    "TECHNICAL_CONSTRAINTS": [
+        "BUDGET_LIMIT",
+        "TIME_LIMIT",
+        "TEAM_SIZE",
+        "TECHNICAL_CONSTRAINTS",
+    ],
+    "ARCHITECTURE_DECISIONS": [
+        "ARCHITECTURE_SUMMARY",
+        "IMPORTANT_DECISIONS",
+        "KNOWN_LIMITATIONS",
+    ],
+    "PROGRESS": [
+        "COMPLETED_WORKSTREAMS",
+        "CURRENT_WORKSTREAM",
+        "BLOCKED_WORKSTREAMS",
+        "COMPLETED_FEATURES",
+        "MVP_STATUS",
+    ],
+    "DELIVERABLES": [
+        "DEMO_STATUS",
+        "PPT_STATUS",
+        "DOCUMENTATION_STATUS",
+        "DEPLOYMENT_URL",
+        "GITHUB_REPOSITORY_URL",
+        "DEMO_URL",
+    ],
+    "SUBMISSION": [
+        "SUBMISSION_REQUIREMENTS",
+        "OPTIONAL_DELIVERABLES",
+        "TEAM_NAME",
+        "TEAM_CAPTAIN",
+        "TEAM_MEMBERS",
+        "TEAM_CONTACT_EMAIL",
+        "TEAM_LOCATION",
+    ],
+}
+
+# Fields that must never contain secrets
+SECRET_FIELD_PATTERNS = [
+    re.compile(r".*API_KEY", re.IGNORECASE),
+    re.compile(r".*API_SECRET", re.IGNORECASE),
+    re.compile(r".*PASSWORD", re.IGNORECASE),
+    re.compile(r".*SECRET", re.IGNORECASE),
+    re.compile(r".*TOKEN", re.IGNORECASE),
+    re.compile(r".*PRIVATE_KEY", re.IGNORECASE),
+    re.compile(r".*CREDENTIAL", re.IGNORECASE),
+]
+
+# Default values for all known fields
+DEFAULT_VALUES: dict[str, str] = {
+    # Hackathon Identity
+    "HACKATHON_NAME": "UNKNOWN",
+    "HACKATHON_PLATFORM": "UNKNOWN",
+    "HACKATHON_URL": "UNKNOWN",
+    "HACKATHON_DASHBOARD_URL": "UNKNOWN",
+    "START_DATE_TIME": "UNKNOWN",
+    "DEADLINE_DATE_TIME": "UNKNOWN",
+    "TIMEZONE": "UNKNOWN",
+    "HACKATHON_ORGANIZER": "UNKNOWN",
+    "HACKATHON_CONTACT": "UNKNOWN",
+    "HACKATHON_THEME": "UNKNOWN",
+    "ELIGIBILITY_REQUIREMENTS": "UNKNOWN",
+    "PRIZE_INFORMATION": "UNKNOWN",
+    # Problem & Idea
+    "PROBLEM_STATEMENT": "UNKNOWN",
+    "TARGET_USERS": "UNKNOWN",
+    "SELECTED_IDEA": "UNKNOWN",
+    "PRODUCT_CONCEPT": "UNKNOWN",
+    "MVP_SCOPE": "UNKNOWN",
+    "MVP_FEATURES": "UNKNOWN",
+    "KEY_DIFFERENTIATORS": "UNKNOWN",
+    # Tech Stack
+    "PROGRAMMING_LANGUAGES": "UNKNOWN",
+    "FRONTEND_FRAMEWORK": "UNKNOWN",
+    "BACKEND_FRAMEWORK": "UNKNOWN",
+    "DATABASE": "UNKNOWN",
+    "AI_ML_PROVIDER": "UNKNOWN",
+    "AI_MODEL_NAME": "UNKNOWN",
+    "DEPLOYMENT_PLATFORM": "UNKNOWN",
+    "OTHER_TECHNOLOGIES": "UNKNOWN",
+    # Submission
+    "DEMO_STATUS": "UNKNOWN",
+    "PPT_STATUS": "UNKNOWN",
+    "DOCUMENTATION_STATUS": "UNKNOWN",
+    "DEPLOYMENT_URL": "UNKNOWN",
+    "GITHUB_REPOSITORY_URL": "UNKNOWN",
+    "DEMO_URL": "UNKNOWN",
+    # Technical Constraints
+    "BUDGET_LIMIT": "UNKNOWN",
+    "TIME_LIMIT": "UNKNOWN",
+    "TEAM_SIZE": "UNKNOWN",
+    "TECHNICAL_CONSTRAINTS": "UNKNOWN",
+    # Architecture Decisions
+    "ARCHITECTURE_SUMMARY": "UNKNOWN",
+    "IMPORTANT_DECISIONS": "UNKNOWN",
+    "KNOWN_LIMITATIONS": "UNKNOWN",
+    # Progress
+    "COMPLETED_WORKSTREAMS": "UNKNOWN",
+    "CURRENT_WORKSTREAM": "UNKNOWN",
+    "BLOCKED_WORKSTREAMS": "UNKNOWN",
+    "COMPLETED_FEATURES": "UNKNOWN",
+    "MVP_STATUS": "UNKNOWN",
+    # Deliverables
+    "DEMO_STATUS": "UNKNOWN",
+    "PPT_STATUS": "UNKNOWN",
+    "DOCUMENTATION_STATUS": "UNKNOWN",
+    "DEPLOYMENT_URL": "UNKNOWN",
+    "GITHUB_REPOSITORY_URL": "UNKNOWN",
+    "DEMO_URL": "UNKNOWN",
+    # Submission
+    "SUBMISSION_REQUIREMENTS": "UNKNOWN",
+    "OPTIONAL_DELIVERABLES": "UNKNOWN",
+    "TEAM_NAME": "UNKNOWN",
+    "TEAM_CAPTAIN": "UNKNOWN",
+    "TEAM_MEMBERS": "UNKNOWN",
+    "TEAM_CONTACT_EMAIL": "UNKNOWN",
+    "TEAM_LOCATION": "UNKNOWN",
+}
+
+
+class VerificationError(Exception):
+    """Raised when configuration validation fails."""
+
+
+class ProjectConfig:
+    """
+    Manages `.env.sherpa` — the persistent project state file.
+
+    Responsibilities:
+    - Initialize `.env.sherpa` if missing
+    - Load all fields into memory
+    - Update fields from user input or repository evidence
+    - Write changes back to disk (preserving comments and unknown fields)
+    - Validate values against expected formats
+    - Never write secrets to this file
+    """
+
+    def __init__(self, project_root: str | None = None):
+        self.project_root = Path(project_root or os.getcwd())
+        self.env_path = self.project_root / ENV_SHERPA_FILENAME
+        self.legacy_env_path = self.project_root / LEGACY_ENV_FILENAME
+        self.env_file = self.project_root / ".env"
+        self._config: dict[str, str] = {}
+        self._raw_lines: list[str] = []
+        self._loaded = False
+        self._changes: dict[str, str] = {}
+
+    # ------------------------------------------------------------------
+    # Loading / Saving
+    # ------------------------------------------------------------------
+
+    def load(self) -> dict[str, str]:
+        """Load .env.sherpa, or read the old filename as a deprecated fallback."""
+        self.env_path = self.project_root / ENV_SHERPA_FILENAME
+        source_path = self.env_path
+        if not source_path.exists() and self.legacy_env_path.exists():
+            import warnings
+            warnings.warn(".env.hackathon is deprecated; copy it to .env.sherpa. The original is preserved.", DeprecationWarning)
+        self._config = {}
+        self._raw_lines = []
+
+        if source_path.exists():
+            self._load_from_file(source_path)
+        else:
+            # Initialize with defaults
+            self._config = dict(DEFAULT_VALUES)
+            self._raw_lines = self._build_initial_lines()
+            self._write()
+
+        self._loaded = True
+        return dict(self._config)
+
+    def _load_from_file(self, path: Path) -> None:
+        """Parse a Sherpa project environment file, preserving comments and blank lines."""
+        raw = path.read_text(encoding="utf-8")
+        self._raw_lines = raw.splitlines(keepends=True)
+
+        for line in self._raw_lines:
+            stripped = line.strip()
+            # Skip blank lines and comments
+            if not stripped or stripped.startswith("#"):
+                continue
+            # Parse KEY=VALUE
+            if "=" in stripped:
+                key, _, value = stripped.partition("=")
+                key = key.strip()
+                value = value.strip()
+                # Strip surrounding quotes
+                if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+                    value = value[1:-1]
+                self._config[key] = value
+
+        # Fill in defaults for missing fields
+        for key, default_val in DEFAULT_VALUES.items():
+            if key not in self._config:
+                self._config[key] = default_val
+
+    def _build_initial_lines(self) -> list[str]:
+        """Build initial .env.sherpa content from defaults."""
+        lines: list[str] = []
+        lines.append("# =============================================================================")
+        lines.append("# Hackathon Project State")
+        lines.add("")
+        lines.add("# This file is the persistent state for a sherpa-managed project.")
+        lines.add("# It lives in .sherpa/project-state.md inside the hackathon project's repository.")
+        lines.add("")
+        lines.add("# Any field whose value is not known must be set to UNKNOWN.")
+        lines.add("# Never invent or guess missing information.")
+        lines.add("")
+        lines.add("# =============================================================================")
+        lines.add("")
+
+        # Add sections based on categories
+        for category, fields in CATEGORY_FIELDS.items():
+            lines.append(f"# =============================================================================")
+            lines.append(f"# {category}")
+            lines.add(f"# =============================================================================")
+            lines.add("")
+            for field in fields:
+                value = DEFAULT_VALUES.get(field, "UNKNOWN")
+                lines.append(f'{field}="{value}"')
+            lines.append("")
+
+        return lines
+
+    def save(self) -> None:
+        """Write current state to .env.sherpa, preserving comments and unknown fields."""
+        if not self.env_path:
+            raise RuntimeError("Verifier not initialized: call load() first")
+
+        lines: list[str] = []
+        seen_keys: set[str] = set()
+
+        # Preserve existing lines, updating values where we have new data
+        for line in self._raw_lines:
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#"):
+                lines.append(line.rstrip("\n"))
+                continue
+
+            if "=" in stripped:
+                key, _, _ = stripped.partition("=")
+                key = key.strip()
+                if key in self._config:
+                    lines.append(f'{key}="{self._config[key]}"')
+                    seen_keys.add(key)
+                else:
+                    lines.append(line.rstrip("\n"))
+            else:
+                lines.append(line.rstrip("\n"))
+
+        # Add any new keys not in original file
+        for key, value in self._config.items():
+            if key not in seen_keys:
+                lines.append(f'{key}="{value}"')
+
+        self._raw_lines = lines
+        self.env_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    # ------------------------------------------------------------------
+    # Get / Set
+    # ------------------------------------------------------------------
+
+    def get(self, key: str, default: str | None = None) -> str | None:
+        """Get a configuration value."""
+        if not self._loaded:
+            self.load()
+        return self._config.get(key, default)
+
+    def set(self, key: str, value: str, source: str = "user") -> None:
+        """Set a configuration value. Marks it as changed."""
+        if not self._loaded:
+            self.load()
+        self._config[key] = value
+        self._changes[key] = value
+
+    def get_all(self) -> dict[str, str]:
+        """Return all configuration values."""
+        if not self._loaded:
+            self.load()
+        return dict(self._config)
+
+    def has(self, key: str) -> bool:
+        """Check if a key exists."""
+        if not self._loaded:
+            self.load()
+        return key in self._config
+
+    def is_unknown(self, key: str) -> bool:
+        """Check if a field is UNKNOWN."""
+        val = self.get(key)
+        return val == "UNKNOWN" or val == ""
+
+    def get_changes(self) -> dict[str, str]:
+        """Return changes since last load."""
+        return dict(self._changes)
+
+    def mark_synced(self) -> None:
+        """Mark all pending changes as synced."""
+        self._changes.clear()
+
+    # ------------------------------------------------------------------
+    # Validation
+    # ------------------------------------------------------------------
+
+    def validate(self) -> list[str]:
+        """Validate all current values. Returns list of warning messages."""
+        warnings: list[str] = []
+
+        for key, value in self._config.items():
+            if not value or value == "UNKNOWN":
+                continue  # Skip unknowns
+
+            # Check for potential secrets in non-secret fields
+            for pattern in _SECRET_PATTERNS:
+                if pattern.search(key):
+                    warnings.append(
+                        f"WARNING: '{key}' appears to contain a secret. "
+                        f"Move to .env file instead."
+                    )
+                    break
+
+        return warnings
+
+    def validate_all(self) -> list[str]:
+        """Alias for validate()."""
+        return self.validate()
+
+    # ------------------------------------------------------------------
+    # Convenience methods for common fields
+    # ------------------------------------------------------------------
+
+    def get_hackathon_name(self) -> str | None:
+        return self.get("HACKATHON_NAME")
+
+    def get_problem_statement(self) -> str | None:
+        return self.get("PROBLEM_STATEMENT")
+
+    def get_target_users(self) -> str | None:
+        return self.get("TARGET_USERS")
+
+    def get_selected_idea(self) -> str | None:
+        return self.get("SELECTED_IDEA")
+
+    def get_tech_stack(self) -> dict[str, str]:
+        return {
+            "programming_languages": self.get("PROGRAMMING_LANGUAGES"),
+            "frontend_framework": self.get("FRONTEND_FRAMEWORK"),
+            "backend_framework": self.get("BACKEND_FRAMEWORK"),
+            "database": self.get("DATABASE"),
+            "ai_ml_provider": self.get("AI_ML_PROVIDER"),
+            "ai_model_name": self.get("AI_MODEL_NAME"),
+            "deployment_platform": self.get("DEPLOYMENT_PLATFORM"),
+            "other_technologies": self.get("OTHER_TECHNOLOGIES"),
+        }
+
+    def get_submission_info(self) -> dict[str, str]:
+        return {
+            "deadline": self.get("DEADLINE_DATE_TIME"),
+            "requirements": self.get("SUBMISSION_REQUIREMENTS"),
+            "demo_status": self.get("DEMO_STATUS"),
+            "ppt_status": self.get("PPT_STATUS"),
+            "deployment_url": self.get("DEPLOYMENT_URL"),
+            "github_url": self.get("GITHUB_REPOSITORY_URL"),
+            "demo_url": self.get("DEMO_URL"),
+        }
+
+
+# Singleton instance
+_verifier: ProjectConfig | None = None
+
+
+def get_verifier(project_root: str | None = None) -> ProjectConfig:
+    """Get or create the global verifier instance."""
+    global _verifier
+    if _verifier is None:
+        _verifier = ProjectConfig(project_root)
+    return _verifier
+
+
+def reset_verifier() -> None:
+    """Reset the verifier singleton (mainly for testing)."""
+    global _verifier
+    _verifier = None