tech-lead-stack 1.0.1

package/.ai/pm-skills/pm-context-summarizer.md

@@ -0,0 +1,61 @@
+---
+name: pm-context-summarizer
+description:
+  Summarize recent technical progress and blockers for non-technical briefings.
+  Extracts business value from developer commit logs.
+cost: ~550 tokens
+modes: [read-only, mcp]
+surface: public
+phase: build
+kind: skill
+domain: product
+ownership:
+  drive: human-ai
+  approve: human
+targets: [local, api, subscription]
+minModelClass: small
+consumes: [plan]
+emits: [diff]
+suggests: [code-review-checklist, pr-automator]
+policies:
+  - user-sovereignty
+  - diagnosis-first
+---
+
+# PM Context Summarizer (The Briefing Engine)
+
+> [!IMPORTANT] **G-Stack Methodology**: Every summary begins with **Tech-Stack
+> Discovery**. The agent must understand the "Product Architecture" to correctly
+> categorize technical changes into high-level value categories. Follow
+> **MinimumCD** by highlighting atomic delivery wins.
+
+## 🎯 Verification Gates (Value Extraction)
+
+### Phase 0: Tech-Stack Discovery (MANDATORY)
+
+- **Action**: Detect the core product features via `src/app` or
+  `src/components`.
+- **Target Files**: `package.json`, `README.md`, or main navigation components.
+
+### Gate 1: Technical-to-Value Mapping
+
+- **Positive (Signal):** Successfully mapped a technical refactor (e.g.,
+  "Updated Prisma types") to a product benefit (e.g., "Improved data reliability
+  and faster reporting").
+- **Negative (Noise):** Generic commit messages (e.g., "fix", "updated files")
+  that provide no context.
+- **Action:** If Negative, scan PR descriptions associated with the commits for
+  deeper "Product Intent."
+
+### Gate 2: Blocker Detection
+
+- **Positive (Pass):** Identified specific technical hurdles (e.g., "Hydration
+  errors in the dashboard") that translate to "UX Delay."
+- **Negative (FAIL):** Missing context on why work is stalled.
+
+## 📋 Outcome Actions
+
+- **Deliver**: A "Stakeholder Ready" summary focusing on **Momentum**,
+  **Blockers**, and **Upcoming Wins**.
+- **Ethos**: Persistence on Clarity. Never provide a list of file names; provide
+  a list of _achievements_.

package/.ai/pm-skills/pm-effort-estimator.md

@@ -0,0 +1,79 @@
+---
+name: pm-effort-estimator
+description:
+  Estimate development effort based on codebase history and complexity. Uses
+  historical churn to provide data-driven velocity predictions.
+cost: ~650 tokens
+modes: [read-only, mcp]
+surface: public
+phase: plan
+kind: skill
+domain: product
+ownership:
+  drive: human-ai
+  approve: human
+targets: [local, api, subscription]
+minModelClass: small
+consumes: [spec]
+emits: [plan]
+suggests: [clean-code, regression-bug-fix]
+policies:
+  - user-sovereignty
+  - diagnosis-first
+---
+
+# PM Effort Estimator (The Historical Oracle)
+
+> [!IMPORTANT] **G-Stack Methodology**: Every estimation begins with
+> **Tech-Stack Discovery**. The agent must identify the "Churn Level" of target
+> files before predicting delivery timelines. Follow **MinimumCD** by breaking
+> large estimates into small, verifiable effort batches.
+
+## 🎯 Verification Gates (Velocity Prediction)
+
+### Phase 0: Tech-Stack Discovery (MANDATORY)
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **IDE / MCP-enabled Agent:** You MUST call the MCP `get_skills` tool (which
+    may be prefixed as `mcp_tech-lead-stack_get_skills` or
+    `tech-lead-stack_get_skills` depending on client prefixing).
+  - **Chat UI (/chat):** You MUST call the internal `get_skill` tool.
+
+- **Action:** Identify the target module's complexity (Total Lines, Churn
+  Frequency).
+- **Tool Mapping**: Run
+  `git log --pretty=format: --name-only | sort | uniq -c | sort -rg | head -20`
+  to find hot files.
+
+### Gate 1: Dependency & Blast Radius
+
+- **Positive (Signal):** The change is localized to a well-tested, low-churn
+  area.
+- **Negative (Noise):** The change touches "God Objects" or fragile legacy
+  modules with low test coverage.
+- **Action:** If Negative, increase the "Complexity Risk Score" by 40%.
+
+### Gate 2: Historical Pattern Matching
+
+- **Positive (Pass):** Similar features in the past were completed within a
+  predictable pattern.
+- **Negative (Fail):** The target area has high "Structural Debt" (e.g., deeply
+  nested components).
+
+## 📊 Estimation Process
+
+### 1. The Complexity Scan (The Brain)
+
+- Audit the target files for logical density and integration points.
+
+### 2. The Churn Check (The Vitals)
+
+- Check git history to see if this area of the code is "Fragile" (frequent bug
+  fixes).
+
+## 📋 Outcome Actions
+
+- **Deliver**: A T-Shirt size estimate (S, M, L, XL) with a "Technical
+  Reasoning" summary.
+- **Ethos**: No gut feelings. Every estimate must be backed by a "Why" derived
+  from the code's current state.

package/.ai/pm-skills/pm-newsletter-generator.md

@@ -0,0 +1,60 @@
+---
+name: pm-newsletter-generator
+description:
+  Generate product-focused updates and highlights from recent code changes. Uses
+  Conventional Commits to track feature narrative.
+cost: ~500 tokens
+modes: [read-only, mcp]
+surface: public
+phase: deploy
+kind: skill
+domain: product
+ownership:
+  drive: human-ai
+  approve: human
+targets: [local, api, subscription]
+minModelClass: small
+consumes: [review-report]
+emits: [release]
+policies:
+  - user-sovereignty
+  - diagnosis-first
+---
+
+# PM Newsletter Generator (The Narrative Architect)
+
+> [!IMPORTANT] **G-Stack Methodology**: Every newsletter begins with
+> **Tech-Stack Discovery**. The agent must map "The Churn" to "The Narrative" by
+> identifying themes in the Conventional Commit history. Follow **MinimumCD** by
+> highlighting the incremental delivery of value.
+
+## 🎯 Verification Gates (Theme Discovery)
+
+### Phase 0: Tech-Stack Discovery (MANDATORY)
+
+- **Action**: Fetch git history for the target period.
+- **Goal**: Identify the most active modules and their corresponding
+  "Conventional Types" (`feat`, `fix`, `refactor`).
+
+### Gate 1: Narrative Cohesion
+
+- **Positive (Signal):** Successfully grouped individual commits into logical
+  "Product Themes" (e.g., "Dashboard Overhaul", "Security Hardening").
+- **Negative (Noise):** A chronological list of commits without a unifying
+  story.
+- **Action**: If Negative, search for "Feature Flags" or "PR Labels" to find the
+  grouping logic.
+
+### Gate 2: Tone & Engagement
+
+- **Positive (Pass):** The newsletter celebration is balanced with technical
+  transparency.
+- **Negative (FAIL):** Over-hyping minor changes or using "Buzzwords" that don't
+  match the code's reality.
+
+## 📋 Outcome Actions
+
+- **Deliver**: A drafted Newsletter highlighting **Key Features**,
+  **Improvements**, and **The "Why"** behind the work.
+- **Ethos**: Authenticity. If the team primarily fixed bugs, frame it as
+  "Quality Hardening" rather than invent feature progress.

package/.ai/pm-skills/pm-progress-translator.md

@@ -0,0 +1,59 @@
+---
+name: pm-progress-translator
+description:
+  Translate complex technical achievements into clear client updates. Bridges
+  the gap between dev velocity and stakeholder value.
+cost: ~550 tokens
+modes: [read-only, mcp]
+surface: public
+phase: deploy
+kind: skill
+domain: product
+ownership:
+  drive: human-ai
+  approve: human
+targets: [local, api, subscription]
+minModelClass: small
+consumes: [review-report]
+emits: [release]
+policies:
+  - user-sovereignty
+  - diagnosis-first
+---
+
+# PM Progress Translator (The Value Bridge)
+
+> [!IMPORTANT] **G-Stack Methodology**: Every translation begins with
+> **Tech-Stack Discovery**. The agent must understand the "Contextual Impact" of
+> a technical change before framing it. Follow **MinimumCD** by celebrating the
+> completion of small, verifiable logic units.
+
+## 🎯 Verification Gates (Clarity & Impact)
+
+### Phase 0: Tech-Stack Discovery (MANDATORY)
+
+- **Action**: identify the recent changes via `git log` or `AnalyticsEvent`
+  history.
+- **Goal**: Differentiate between "Maintenance Churn" and "Feature Development."
+
+### Gate 1: The "So What?" Filter
+
+- **Positive (Signal):** successfully linked a low-level change (e.g., "Updated
+  JWT logic") to a high-level value (e.g., "Enhanced user security and login
+  reliability").
+- **Negative (Noise):** Listing file names or package updates as "Status."
+- **Action**: If Negative, pivot to "System Health" framing.
+
+### Gate 2: Stakeholder Empathy
+
+- **Positive (Pass):** The report uses non-technical language optimized for
+  decision-makers.
+- **Negative (FAIL):** Using terminology like "hydration," "middleware," or
+  "normalization" without explanation.
+
+## 📋 Outcome Actions
+
+- **Deliver**: A "Stakeholder Status Report" formatted for emails or slack
+  briefings.
+- **Ethos**: Translation is Transformation. Change "I fixed X" into "The system
+  is now faster/safer/better for users."

package/.ai/pm-skills/pm-release-note-drafter.md

@@ -0,0 +1,58 @@
+---
+name: pm-release-note-drafter
+description:
+  Automatically draft user-centric release notes from merged features.
+  Celebrates shipping while maintaining technical accuracy.
+cost: ~450 tokens
+modes: [read-only, mcp]
+surface: public
+phase: deploy
+kind: skill
+domain: product
+ownership:
+  drive: human-ai
+  approve: human
+targets: [local, api, subscription]
+minModelClass: small
+consumes: [review-report]
+emits: [release]
+policies:
+  - user-sovereignty
+  - diagnosis-first
+---
+
+# PM Release Note Drafter (The Ship Captain)
+
+> [!IMPORTANT] **G-Stack Methodology**: Every draft begins with **Tech-Stack
+> Discovery**. The agent must map merged Pull Requests to their "Impact Radius"
+> before celebration. Follow **MinimumCD** by highlighting the completion of
+> small, high-value feature batches.
+
+## 🎯 Verification Gates (Shipping Narrative)
+
+### Phase 0: Tech-Stack Discovery (MANDATORY)
+
+- **Action**: research merged PRs and their linked issues.
+- **Goal**: Extract the "User-Facing Impact" from the developer-facing
+  implementation notes.
+
+### Gate 1: Impact Prioritization
+
+- **Positive (Signal):** Most impactful changes are highlighted at the top;
+  technical maintenance is grouped and summarized.
+- **Negative (Noise):** Listing every bug fix as a "Feature."
+- **Action**: Run a "Value Filter" to identify the "Big Wins" for the release.
+
+### Gate 2: Consistency & Tone
+
+- **Positive (Pass):** Narrative tone matches the project's branding while
+  remaining technically grounded.
+- **Negative (FAIL):** Generic release notes (e.g., "stability improvements")
+  that offer no specific info.
+
+## 📋 Outcome Actions
+
+- **Deliver**: A professional `RELEASE_NOTES.md` draft ready for stakeholder
+  review.
+- **Ethos**: transparency over Hype. Be specific about what changed and how it
+  helps the user.

package/.ai/pm-skills/pm-risk-detector.md

@@ -0,0 +1,58 @@
+---
+name: pm-risk-detector
+description:
+  Identify technical risks and bottlenecks that could impact upcoming deadlines.
+  Focuses on "Architectural Drift" and "God Object" detection.
+cost: ~450 tokens
+modes: [read-only, mcp]
+surface: public
+phase: review
+kind: skill
+domain: product
+ownership:
+  drive: human-ai
+  approve: human
+targets: [local, api, subscription]
+minModelClass: small
+consumes: [diff]
+emits: [review-report]
+suggests: [pr-automator, qa-handover-generator]
+policies:
+  - user-sovereignty
+  - diagnosis-first
+---
+
+# PM Risk Detector (The Warning Signal)
+
+> [!IMPORTANT] **G-Stack Methodology**: Every risk audit begins with
+> **Tech-Stack Discovery**. The agent must identify the "Critical Path" modules
+> before flagging bottlenecks. Follow **MinimumCD** by detecting early friction
+> in small changes.
+
+## 🎯 Verification Gates (Milestone Health)
+
+### Phase 0: Tech-Stack Discovery (MANDATORY)
+
+- **Action**: Map the core feature set to the file structure.
+- **Goal**: Identify the "High Traffic" areas of the codebase.
+
+### Gate 1: Structural Debt Audit
+
+- **Positive (Signal):** Large files (>500 lines) with mixed responsibilities
+  that touch multiple features.
+- **Negative (Noise):** Minor linting issues that don't impact velocity.
+- **Action**: Label high-traffic, low-quality files as "Milestone Blockers."
+
+### Gate 2: Velocity Friction
+
+- **Positive (Pass):** Detected areas where technical debt will slow down
+  feature implementation (e.g., missing types, lack of reusable components).
+- **Negative (Risk):** Dependencies on third-party APIs with high failure rates
+  or slow responses.
+
+## 📋 Outcome Actions
+
+- **Deliver**: A "Risk Heatmap" report with clear GO/ABORT signals for the
+  milestone.
+- **Ethos**: Diagnosis before Advice. Focus on the _structural_ cause of the
+  risk, not just the symptoms.

package/.ai/pm-skills/pm-story-augmenter.md

@@ -0,0 +1,70 @@
+---
+name: pm-story-augmenter
+description:
+  Enhance user stories with technical depth and edge-case detection. Bridges the
+  gap between product vision and technical feasibility.
+cost: ~650 tokens
+modes: [read-only, mcp]
+surface: public
+phase: specify
+kind: skill
+domain: product
+ownership:
+  drive: human-ai
+  approve: human
+targets: [local, api, subscription]
+minModelClass: small
+consumes: [intent-brief]
+emits: [spec]
+suggests: [planning-expert, vertical-slice-decomposer]
+policies:
+  - user-sovereignty
+  - diagnosis-first
+---
+
+# PM Story Augmenter (The Precision Scraper)
+
+> [!IMPORTANT] **G-Stack Methodology**: Every story discovery begins with
+> **Tech-Stack Discovery**. The PM agent must understand the project's native
+> constraints and existing logic patterns before suggesting augmentations.
+> Follow **MinimumCD** by identifying the smallest verifiable logic gaps in a
+> requirement.
+
+## 🎯 Verification Gates (Product-Logic Alignment)
+
+### Phase 0: Tech-Stack Discovery (MANDATORY)
+
+- **Skill Usage Enforcement (NON-NEGOTIABLE):**
+  - **FORBIDDEN:** Direct analysis without architectural context is prohibited.
+  - **IDE / MCP-enabled Agent:** You MUST call the MCP `get_skills` tool (which
+    may be prefixed as `mcp_tech-lead-stack_get_skills` or
+    `tech-lead-stack_get_skills` depending on client prefixing).
+  - **Chat UI (/chat):** You MUST call the internal `get_skill` tool.
+
+- **Action:** Identify existing modules that overlap with the story scope.
+- **Target Files:** Inspect `package.json`, `prisma/schema.prisma`, or core
+  service directories.
+- **MANDATORY Guardrail:** Focus ONLY on logic-bearing files. Avoid "Goal Drift"
+  by ignoring unrelated UI styling unless the story specifically targets design
+  tokens.
+
+### Gate 1: Intent & Logic Gap Analysis
+
+- **Positive (Signal):** Found clear missing edge cases (e.g., race conditions,
+  validation failures) that the developer would have to "guess" later.
+- **Negative (Noise):** Vague requirements that don't map to a specific data
+  model or API endpoint.
+- **Action:** If Negative, flag as "Strategic Debt" and request clarification on
+  the data flow.
+
+### Gate 2: Technical Acceptance Criteria (TAC)
+
+- **Positive (Verified):** ACs are technical enough to prevent rework but
+  product-focused enough to ensure value delivery.
+- **Negative (Risk):** Generic ACs like "Make it work" or "Add a button."
+
+## 📋 Outcome Actions
+
+- **Deliver**: An augmented User Story with a "Technical Polish" section.
+- **Ethos**: Diagnosis before Advice. If the repo uses a specific pattern (e.g.,
+  Zod for validation), the TAC must explicitly mention using that pattern.

package/.ai/pm-skills/pm-task-specifier.md

@@ -0,0 +1,70 @@
+---
+name: pm-task-specifier
+description:
+  Draft high-fidelity technical specifications for new features. Focuses on data
+  models, API contracts, and schema integrity.
+cost: ~550 tokens
+modes: [read-only, mcp]
+surface: public
+phase: specify
+kind: skill
+domain: product
+ownership:
+  drive: human-ai
+  approve: human
+targets: [local, api, subscription]
+minModelClass: small
+consumes: [intent-brief]
+emits: [spec]
+suggests: [planning-expert, vertical-slice-decomposer]
+policies:
+  - user-sovereignty
+  - diagnosis-first
+---
+
+# PM Task Specifier (The Blueprint Drafter)
+
+> [!IMPORTANT] **G-Stack Methodology**: Every specification begins with
+> **Tech-Stack Discovery**. The agent must audit existing schemas and types
+> before drafting new feature blueprints. Follow **MinimumCD** by defining the
+> "Minimum Viable Schema" required for the feature.
+
+## 🎯 Verification Gates (Spec Integrity)
+
+### Phase 0: Tech-Stack Discovery (MANDATORY)
+
+- **Action**: Research the state of `prisma/schema.prisma`, `src/types`, and
+  existing API routes.
+- **Goal**: Understand the "Pattern Language" of the project (e.g., camelCase vs
+  snake_case, Zod validation).
+
+### Gate 1: Contract Consistency
+
+- **Positive (Signal):** The new feature spec uses existing utility types and
+  follows the project's data flow conventions.
+- **Negative (Noise):** Creating redundant types or data fields that already
+  exist.
+- **Action**: If Negative, force a "Schema Deduplication" pass.
+
+### Gate 2: Security & Validation Gate
+
+- **Positive (Pass):** The spec includes non-negotiable validation rules (Zod)
+  and authorization checks.
+- **Negative (FAIL):** Missing error handling or data sanitizer definitions.
+
+## 🛠 Analysis Layer (The Hands)
+
+### 1. Schema Heartbeat
+
+- Verify the database schema and identify any required migrations.
+
+### 2. Contract Draft
+
+- Define the `Input` and `Output` types for the proposed feature.
+
+## 📋 Outcome Actions
+
+- **Deliver**: A "High-Fidelity Technical Spec" document for developer
+  ingestion.
+- **Ethos**: Precision over Narrative. A spec should be so clear that it
+  requires zero "back-and-forth" with the developer.

package/.ai/policies/diagnosis-first.md

@@ -0,0 +1,26 @@
+> [!IMPORTANT] **Diagnosis before Advice (G-Stack Ethos)**
+>
+> **Understand the real problem and the real codebase before proposing or
+> writing anything.** Generic, stack-agnostic advice is a failure mode. Every
+> task begins with discovery.
+>
+> 1. **Phase 0 — Tech-Stack Discovery (MANDATORY).** Before any design or
+>    change, detect the project's actual ecosystem: language and version,
+>    framework and version, package manager, existing patterns, configuration,
+>    and test setup. Read the code the task touches — do not assume. Ignore
+>    binaries/images and avoid goal drift.
+> 2. **User-Centric Reframing.** Solve the underlying user pain or business
+>    goal, not just the literal feature requested. Interrogate the request: what
+>    problem is really being solved, and what is the smallest change that solves
+>    it? Reframe when the stated ask hides a better one.
+> 3. **Reuse before Rewrite (CRITICAL).** Search for existing functionality,
+>    utilities, components, and abstractions and reuse them before creating
+>    anything new. Use the platform and the existing codebase. Net-new code is a
+>    last resort, justified only when nothing suitable exists.
+> 4. **Diagnose before you fix.** No fix without investigation. Trace the actual
+>    data flow, reproduce the behavior, and form a hypothesis before changing
+>    code. Stop and reassess after roughly three failed fix attempts instead of
+>    thrashing.
+> 5. **Simplicity and scope discipline (Rule 0).** Prefer the simplest solution
+>    that works. Touch only what the task requires — no drive-by edits, no
+>    speculative abstractions, no adjacent "while I'm here" cleanup.

package/.ai/policies/four-pillars.md

@@ -0,0 +1,72 @@
+> [!IMPORTANT] **Methodology Alignment — The Four Pillars**
+>
+> This skill adheres to four engineering pillars. A plan or change that violates
+> any one of them fails review, even if the other three are perfect. One fatal
+> flaw drives the overall judgment low — the score is holistic, not an average.
+>
+> **1. G-Stack Ethos — Diagnosis before Advice** (garrytan/gstack)
+>
+> - **Diagnose first:** begin from the real codebase (detected
+>   language/framework/version, existing patterns, config). Generic,
+>   stack-agnostic advice fails.
+> - **User-centric reframing:** solve the underlying user pain or business goal,
+>   not just the literal request. Find the better problem hiding inside the ask.
+> - **Reuse before rewrite:** search for and reuse existing utilities,
+>   components, and platform capabilities before writing anything new.
+> - **The sprint lifecycle:** respect the phases — Think → Plan → Build → Review
+>   → Test → Ship → Reflect — and don't skip ahead.
+> - **User sovereignty:** advise; the human decides. Ask instead of guessing on
+>   ambiguous decisions.
+>
+> **2. MinimumCD — Continuous Delivery & Atomic Flow** (minimumcd.org)
+>
+> - **Small batches / vertical slices:** decompose work into the smallest
+>   end-to-end, independently deployable units. No "big-bang" changes.
+> - **Trunk-based, always-releasable:** integrate continuously; every slice
+>   keeps the trunk in a working, releasable state and ships only
+>   forward-independent changes.
+> - **Continuous verification:** each slice is proven working before the next
+>   begins; when the build or tests go red, stop the line and fix before adding
+>   more.
+> - **Immutable, single path to production:** build an artifact once and promote
+>   it unchanged; the pipeline is the only way to ship — no manual, out-of-band
+>   deploys.
+> - **Decouple deploy from release:** land code behind feature flags /
+>   progressive rollout, and keep rollback always available. Deploying is not
+>   releasing.
+>
+> **3. Agent Skills — Process over Prose, Evidence over Assumption**
+> (addyosmani/agent-skills)
+>
+> - **Evidence over assumption:** "seems right" and "tested manually" are never
+>   sufficient. End every gate with hard evidence — a command to run, its
+>   output, or a passing test.
+> - **Anti-rationalization:** never skip a quality gate, delete or skip a test,
+>   or silence a check to move faster. Speed is never a reason to lower the bar.
+> - **Clarity and simplicity:** prefer clear, maintainable code over cleverness;
+>   reduce complexity while preserving exact behavior.
+> - **Declarative over imperative:** express intent and desired state rather
+>   than brittle step-by-step manipulation wherever the platform or framework
+>   supports it.
+> - **Verifiable, bounded steps:** each step has a clear done-condition and
+>   stays inside its declared scope.
+>
+> **4. Modern Web Guidance — Platform First** (GoogleChrome/modern-web-guidance)
+>
+> - **Native over legacy:** prefer modern, native platform APIs over legacy
+>   hacks and heavy third-party dependencies — e.g.
+>   `navigator.clipboard.writeText` over `document.execCommand('copy')`, and the
+>   Popover API, `<dialog>`, Anchor Positioning, View Transitions, and container
+>   queries over JS/library reimplementations.
+> - **Built-in quality:** choose solutions that give performance, accessibility,
+>   and security for free — semantic HTML with ARIA kept in sync with visual
+>   state, Core Web Vitals / INP awareness, and validation shown only after
+>   interaction (`:user-invalid`).
+> - **Progressive enhancement & responsible fallbacks:** let older browsers
+>   silently ignore additive enhancements; for critical behavior write
+>   lightweight, case-specific fallbacks (under ~50 LOC) or conditionally-loaded
+>   polyfills — never heavy bundles.
+> - **Baseline-aware:** check real browser support (the Baseline dataset) before
+>   adopting a feature, and document platform gotchas and quotas.
+> - **Not applicable when the task isn't web/UI:** treat this pillar as
+>   satisfied for non-web work.

package/.ai/policies/user-sovereignty.md

@@ -0,0 +1,25 @@
+> [!IMPORTANT] **User Sovereignty & Persistence (G-Stack Ethos)**
+>
+> **The human is the Tech Lead. The agent advises; the User Tech-Lead decides.**
+> Every finding, plan, or change is a recommendation presented for approval —
+> never a fait accompli. Surface the trade-offs and let the human make the call.
+>
+> 1. **Present, don't impose.** For any consequential decision (architecture,
+>    dependency, data model, irreversible action), lay out the options with
+>    their trade-offs and a clear recommendation, then wait. Never proceed past
+>    an approval gate on the human's behalf.
+> 2. **Reward is persistence to a high standard, not speed.** The goal is to
+>    resolve the task or issue completely and correctly. Do not declare victory
+>    early, do not paper over failures, and do not trade correctness for the
+>    appearance of progress.
+> 3. **The Confusion Protocol — ask, don't guess.** When an architectural
+>    decision, requirement, or intent is ambiguous, STOP and ask one precise
+>    question rather than guessing. A wrong assumption is more expensive than a
+>    question.
+> 4. **Escalate at the boundary.** Anything that changes scope, touches
+>    protected areas (auth, payments, infrastructure, data migrations), or
+>    cannot be cleanly rolled back requires explicit human sign-off before you
+>    act.
+> 5. **Git and deployment are the human's job.** Do not commit, push, merge, or
+>    deploy unless explicitly asked. Prepare the work and hand it back for the
+>    human's decision.