@pushpalsdev/cli 1.0.79 → 1.0.81

package/runtime/vision.example.md

@@ -2,7 +2,7 @@
 
 > **One sentence:** What does this repo exist to make true in the world?
 >
-> Example: “Make it easy for developers to ship <X> reliably, without needing deep expertise in <Y>.”
+> Example: Make it easy for developers to ship `<X>` reliably without needing deep expertise in `<Y>`.
 
 ---
 
@@ -10,201 +10,204 @@
 
 ### Primary users
 
-- **User type A:** (e.g., app developers, SREs, analysts, end-users)
-  - Jobs-to-be-done: …
-  - Pain today: …
-  - Success looks like: …
+- **User type A:** Who depends on this repo most?
+  - Jobs-to-be-done: What are they trying to accomplish?
+  - Pain today: What is slow, confusing, risky, or broken?
+  - Success looks like: What should be easier or more trustworthy?
 
 ### Secondary users
 
-- **User type B:** …
-  - Jobs-to-be-done: …
-  - Pain today: …
-  - Success looks like: …
+- **User type B:** Who benefits indirectly?
+  - Jobs-to-be-done: ...
+  - Pain today: ...
+  - Success looks like: ...
 
-### Non-users (explicitly _not_ optimizing for)
+### Non-users
 
-- **Not for:** …
-  - Why: …
-
-> **Guidance:** Keep this section concrete. If you can’t name the user and their job, you’ll argue about priorities forever.
+- **Not for:** Who or what are we explicitly not optimizing for?
+  - Why: ...
 
 ---
 
 ## 2) The problem we solve
 
-### Today’s reality
+### Today's reality
 
-- What is hard / slow / risky today?
-- What failures happen repeatedly? (bugs, incidents, misconfig, confusion)
-- What is expensive? (time, money, cognitive load, coordination)
+- What repeatedly fails, confuses users, wastes time, or creates operational risk?
+- What is expensive in time, money, cognitive load, or coordination?
+- Which current limitations block the repo from delivering its core value?
 
 ### The change we want
 
-- In 6–12 months, what should feel _meaningfully easier_?
-- In 2–3 years, what should be _obviously different_?
-
-> **Optional:** Add a 3–5 line “story” of a user before vs after.
+- In the next few months, what should become meaningfully easier?
+- In the longer term, what should be obviously different because this repo succeeds?
 
 ---
 
-## 3) Product principles (decision rules)
-
-These are **tie-breakers** when tradeoffs happen. Put them in priority order.
+## 3) Product principles
 
-1. **Principle 1:** (e.g., “Safe by default”)
-   - We will: …
-   - We won’t: …
-2. **Principle 2:** (e.g., “Make the common path fast”)
-   - We will: …
-   - We won’t: …
-3. **Principle 3:** (e.g., “Prefer boring, maintainable solutions”)
-   - We will: …
-   - We won’t: …
+Put these in priority order. They should help say "no" to tempting but wrong work.
 
-> **Guidance:** A principle is only useful if it can help you say “no” to a PR.
+1. **Principle 1:** e.g. Safe by default.
+   - We will: ...
+   - We will not: ...
+2. **Principle 2:** e.g. Make the common path fast.
+   - We will: ...
+   - We will not: ...
+3. **Principle 3:** e.g. Prefer maintainable, reversible changes.
+   - We will: ...
+   - We will not: ...
 
 ---
 
-## 4) What “good” looks like (measures)
-
-Pick a small set of metrics you can actually track.
+## 4) What good looks like
 
 ### User-facing outcomes
 
-- **Time-to-success:** e.g., median time from install → first successful use
-- **Quality:** e.g., bug rate / support tickets per active user
-- **Trust:** e.g., SLO compliance, error rate, crash-free sessions
-
-### Developer / maintainer outcomes
+- Users can complete the core workflow with less time, confusion, or failure.
+- The most important behavior is observable and trustworthy.
+- Regressions in the core path are caught before they reach users.
 
-- **Change velocity:** PR cycle time, lead time to release
-- **Operational burden:** pages/alerts per week, toil hours
-- **Maintainability:** test coverage for critical paths, build time, flake rate
+### Product quality measures
 
-> **Guidance:** Avoid vanity metrics. Prefer “time, errors, incidents, support load, cost”.
+- Reliability: ...
+- Performance: ...
+- Validation coverage: ...
+- Maintainability: ...
 
 ---
 
 ## 5) Scope and boundaries
 
-### In scope (what we _are_)
+### In scope
 
-- Core capability A: …
-- Core capability B: …
-- Core capability C: …
+- Core capability A: ...
+- Core capability B: ...
+- Core capability C: ...
 
-### Out of scope / non-goals (what we are _not_)
+### Out of scope / non-goals
 
-- Not a replacement for: …
-- Not trying to support: …
-- Not optimizing for: …
-
-### Compatibility & support policy (optional)
-
-- Supported platforms / versions: …
-- Breaking changes policy: …
-- Deprecation timeline: …
-
-> **Guidance:** This section prevents “just one more feature” creep.
+- Not trying to support: ...
+- Not optimizing for: ...
+- Not a replacement for: ...
 
 ---
 
-## 6) Current priorities (next 4–8 weeks)
-
-Pick 3–5 items max. Each should be **outcome-oriented**.
+## 6) Current priorities
 
-1. **Priority:** …
-   - Why now: …
-   - Success criteria: …
-   - Owner / area: …
-2. **Priority:** …
-3. **Priority:** …
+Pick 3-7 outcome-oriented priorities. Put the most important first; PushPals uses this order.
 
-> **Tip:** If everything is a priority, nothing is.
+1. **Priority 1 title**
+   - Why now: ...
+   - Success criteria: ...
+   - Expected validation: ...
+2. **Priority 2 title**
+   - Why now: ...
+   - Success criteria: ...
+   - Expected validation: ...
+3. **Priority 3 title**
+   - Why now: ...
+   - Success criteria: ...
+   - Expected validation: ...
 
 ---
 
-## 7) Near-term objectives (1–2 quarters)
-
-These are “bets” with explicit results.
+## 7) Near-term objectives
 
 ### Objective A: <name>
 
-- **Problem:** …
-- **Approach:** …
-- **Deliverables:** …
-- **Risks:** …
-- **Exit criteria:** How we’ll know it worked (measurable)
+- Problem: ...
+- Approach: ...
+- Deliverables: ...
+- Risks: ...
+- Exit criteria: ...
+- Expected validation: ...
 
 ### Objective B: <name>
 
-- …
+- Problem: ...
+- Approach: ...
+- Deliverables: ...
+- Risks: ...
+- Exit criteria: ...
+- Expected validation: ...
 
 ---
 
-## 8) Long-term direction (1–3 years)
-
-Describe where this repo is going, without over-promising.
+## 8) Long-term direction
 
 ### Strategic bets
 
-- **Bet 1:** …
-  - Why it matters: …
-  - What we’ll likely build: …
-  - What we likely won’t build: …
-- **Bet 2:** …
+- **Bet 1:** ...
+  - Why it matters: ...
+  - What we will likely build: ...
+  - What we likely will not build: ...
+- **Bet 2:** ...
 
-### “If we’re right, then…”
+### If we are right, then
 
-- Users will be able to: …
-- Maintainers will spend less time on: …
-- The ecosystem will have: …
+- Users will be able to: ...
+- Maintainers will spend less time on: ...
+- The project will be known for: ...
 
 ---
 
 ## 9) Guardrails and constraints
 
-### Guardrails (how we avoid harm / churn)
+### Guardrails
 
-- Prefer changes that are **reversible** or behind flags.
-- Default to **secure / safe** settings.
-- Optimize for the **common path**; support escape hatches for experts.
-- Avoid adding new dependencies unless they reduce net complexity.
-- Pay down operational toil before adding big surface area.
+- Prefer small, reversible changes with clear validation.
+- Protect the core user workflow before widening scope.
+- Do not hide validation failures or claim untested work is complete.
+- Avoid new dependencies unless they reduce net complexity.
 
-### Constraints (reality checks)
+### Constraints
 
-- Staffing level / maintainer bandwidth: …
-- Hard requirements (privacy, compliance, perf, cost): …
-- External dependencies: …
+- Supported platforms / runtimes: ...
+- Performance or cost limits: ...
+- External dependencies: ...
+- Maintainer bandwidth: ...
 
----
+### Agent validation policy
+
+- Agents must name the validation path before starting work.
+- If the expected validation cannot run, agents must surface that as a blocker.
+- User-facing or UI-affecting work should include an end-to-end or rendered-surface check when available.
 
-## 10) How decisions get made (governance-lite)
+### Risk policy
 
-- **Source of truth:** issues + RFCs + docs in `docs/`
-- **When we require an RFC:** breaking changes, new public APIs, major deps, new architecture
-- **Review expectations:** tests required for critical paths, docs for user-facing behavior
-- **Release cadence:** …
-- **What we won’t merge:** (examples)
-  - large rewrites without an incremental plan
-  - behavior changes without migration guidance
-  - features that expand scope beyond the non-goals
+- Core-path regressions are more serious than missing stretch features.
+- High-risk architecture or behavior changes require explicit maintainer review.
 
 ---
 
-## Appendix (optional but powerful)
+## 10) How decisions get made
 
-### A) Glossary
+- Source of truth: this `vision.md`, issues, and repo docs.
+- Prefer work that advances section 6 priorities and section 7 objectives.
+- Require tests or equivalent validation for critical-path changes.
+- Do not merge broad rewrites without an incremental plan and rollback path.
 
-- Term: definition…
+---
+
+## 11) Active repo autonomy loop
 
-### B) Personas (one-page each)
+- PushPals should compile section 6 priorities and section 7 objectives into small, ranked autonomous work items.
+- Every selected objective should include:
+  - Source signal: which priority/objective/guardrail triggered it.
+  - Weight: why it matters now.
+  - Scope: files or areas expected to change.
+  - Guardrail check: what the work must not break.
+  - Validation path: the command or manual check that proves the change.
+- PushPals should favor repo-native work over meta/autonomy work unless this repo's own vision makes meta/autonomy infrastructure a top priority.
+
+---
 
-- Persona, environment, constraints, success criteria…
+## 12) Testing criteria
 
-### C) Example “no” responses (template)
+This is the user-owned validation contract for autonomous work.
+Fill this section with the exact repo commands WorkerPals must run before submitting a PR or revision.
+PushPals treats command-like bullet items in this section as required validation and blocks publication when they fail.
 
-- “Thanks — this is valuable, but it conflicts with our non-goal X…”
-- “We’d reconsider if metric Y becomes a problem…”
+- Add repo-required test commands as separate bullet items after they exist in this repository.
+- Keep conditional or manual checks in section 9 unless they are mandatory for every WorkerPal PR or revision.