@papi-ai/server 0.7.79 → 0.7.81

package/dist/prompts.js

@@ -13,6 +13,24 @@ If a candidate AD body could be invalidated by running a SQL query, refreshing a
 **Negative example (reject):** "External user feedback is now flowing. Stonebridge Systems is actively building." \u2014 this is a fact about the current state of the world. Capture as dogfood/signal observation; do not mint.
 
 This rule applies to: new ADs proposed during planning (Step 9), strategy review AD updates (section 5), and strategy_change AD updates. If you find an existing AD that violates this rule during housekeeping, propose deleting it (action: "delete") with a one-line rationale.`;
+var AD_ADMISSION_RULES = `**AD Admission Rule \u2014 PROPOSE a decision when the project takes a real stance.**
+
+The guard above says what to reject. This says what to propose. Rejecting is not the safe default: a stance that never gets minted is a stance the next cycle cannot see, and re-deciding it every session is the exact cost this project is paying you to remove. When a candidate passes all four tests below, propose it \u2014 do not wait for the next strategy review.
+
+**The four tests. All four must pass.**
+(a) **Alternatives were real.** Something else could genuinely have been chosen. If there was only ever one way to do it, it is not a decision.
+(b) **It constrains future work not yet scoped.** It changes what a task nobody has written yet will do. Not "it describes work we did" \u2014 "it binds work we have not planned".
+(c) **It is arguable today.** A competent person could argue the other side right now, with the evidence currently available. Not "was once debated" \u2014 live.
+(d) **Reversing it costs more than making it did.** If undoing it is as cheap as doing it, nothing is being constrained.
+
+**Routing for a near-miss \u2014 a candidate that fails one test still goes somewhere.**
+- **Fails (c) only** \u2014 real alternatives, binds future work, expensive to reverse, but nobody is arguing the other side any more: it is a **Convention**, not a Decision. A Convention is a settled answer to a recurring question; it does not need adjudicating, it needs to be *known* by whoever builds next. Record it as a project convention so it rides future build handoffs. Do not mint it as an AD, and do not drop it.
+- **Fails (b)** \u2014 it does not constrain any future work: it is not durable at all, it is just work. Capture it as a task, a build report note, or a doc. Do not mint it.
+- **Fails (a) or (d)** \u2014 not a stance. Same routing as (b): capture it, do not mint it.
+
+**Copy variants are NEVER decisions.** A tagline, a headline, a value proposition, a piece of marketing or product wording: swapping one for another constrains no future work, so it fails test (b) outright. Wording changes as often as the market teaches you something, and routing every edit through decision ceremony is what buries the handful of decisions that genuinely constrain the project. Edit the wording where the wording lives. If two variants are being compared against a measurement, that is an experiment, not a decision.
+
+**A decision decaying into a convention is the healthy path, not a failure.** When a live AD stops being arguable \u2014 the alternatives are no longer on the table and nobody would re-litigate it \u2014 say so during housekeeping and propose retiring it into a convention. An AD registry where most entries are settled is one nobody reads.`;
 var AD_CONFLICT_SURFACING_RULES = `**A contradiction is NOT a veto \u2014 surface it, never silently shelve it.**
 
 Active Decisions are *active*: they can be superseded, modified, or abandoned. You do NOT have authority to kill a piece of work simply because it cuts against one. That is the user's call, and they can only make it if you show it to them.
@@ -65,6 +83,7 @@ SCOPE BOUNDARY (DO NOT DO THIS)
 ACCEPTANCE CRITERIA
 [ ] [criterion 1]
 [ ] [criterion 2]
+[Write criteria the builder can actually check. A criterion MAY optionally carry a typed check that the BUILDER'S HOST runs at build_execute (complete) and reports back \u2014 PAPI never executes anything (AD-58). Checks cannot be expressed in this markdown: to attach one, emit that criterion in the Part 2 structured JSON as {"text": "\u2026", "check": {\u2026}} instead of a bare string, where check is one of {"kind":"command","run":"npm test"} / {"kind":"http","url":"https://\u2026","expect":"2xx"} / {"kind":"grep","file":"path/to/file","pattern":"\u2026","expect":"present"|"absent"}. Do NOT force machine-checkability \u2014 a criterion that is a human judgement ("copy reads well") stays a plain string with no check, and that is a valid criterion.]
 
 PRE-MORTEM
 [For projects with 10+ cycles: 1-3 bullet points \u2014 most likely technical blocker, integration risk with adjacent systems, and scope creep signal. Draw from dead_ends and surprises in recent build reports for the same module. Omit this section entirely for projects with fewer than 10 cycles.]
@@ -258,7 +277,7 @@ var PLAN_FRAGMENT_SPIKE = `
 var PLAN_FRAGMENT_DESIGN_BRIEF = `
    **Design brief task detection:** When a task's task type is "design-brief", generate a DESIGN BRIEF handoff. Inside SCOPE (DO THIS), use these type-specific subsections. KEEP the "SCOPE (DO THIS)" header and put these subsections INSIDE it \u2014 the handoff parser only recognises the standard headers (packages/adapter-md build-handoff.ts SECTION_HEADERS) and a handoff with no SCOPE section is rejected outright (task-3050, C357):
    - AUDIENCE: Who this design is for \u2014 persona and context of use (e.g. "non-technical Owner, first dashboard visit")
-   - BRAND CONSTRAINTS: Palette, typography, tone \u2014 pull from \`.impeccable.md\` (dev patterns, anti-patterns, component rules) AND \`docs/branding/brand-book.html\` (brand identity, positioning, voice canon) if present. If neither exists, state "No brand doc \u2014 Owner should define constraints before starting."
+   - BRAND CONSTRAINTS: Palette, typography, tone \u2014 pull from \`PRODUCT.md\` (strategic: brand, users, product purpose, design principles) AND \`DESIGN.md\` (visual tokens: palette, typography, elevation, components) if present. If neither exists, state "No brand doc \u2014 Owner should define constraints before starting."
    - DELIVERABLE FORMAT: What the output looks like \u2014 design handoff package / annotated mockup / style spec. Be specific so the person doing the work knows what "done" means.
    - REVIEW POINTS: What the Owner must approve before the design is considered done (e.g. layout, copy, colour, imagery).
    Keep SCOPE BOUNDARY, ACCEPTANCE CRITERIA, SECURITY CONSIDERATIONS, and PRE-BUILD VERIFICATION sections as normal.
@@ -290,11 +309,11 @@ var PLAN_FRAGMENT_OPS_BRIEF = `
 var PLAN_FRAGMENT_UI = `
    **UI/visual task detection:** Apply these additions ONLY to tasks whose PRIMARY scope is frontend visual work \u2014 the task's main deliverable must be a UI change, new component, visual design, or page. Do NOT apply to backend tasks, DB migrations, or prompt/config changes that merely mention a dashboard or page in passing. Signal: the task would fail if no .tsx/.css files were changed. If uncertain, skip the UI additions.
    When a task IS a UI task (primary scope is visual/frontend):
-   - Add to SCOPE: "Read \`.impeccable.md\` for component patterns, anti-patterns, and dev-loop design rules. Read \`docs/branding/brand-book.html\` for brand identity (positioning, voice, palette as final canon). Use the \`frontend-design\` skill for implementation."
+   - Add to SCOPE: "Read \`PRODUCT.md\` for product purpose, users and design principles, and \`DESIGN.md\` for the visual tokens (palette, typography, elevation, components) \u2014 these are the two files the \`impeccable\` skill reads, and every visual decision must align with them. Run \`impeccable init\` to create them if they do not exist. Use the \`frontend-design\` skill for implementation."
    - For M/L UI tasks, add to SCOPE: "Use the full impeccable workflow: shape (direction approval) \u2192 craft (design+build via \`impeccable craft\` / frontend-design) \u2192 live (in-browser HMR iteration via \`impeccable live\`) \u2192 detect (slop check). The approved direction is the quality bar; expect 2-3 iterations. Playground is for pre-build direction approval of shareable/static artifacts or non-dashboard explorers; Playwright is for post-build verification, not mid-design iteration."
    - Add to ACCEPTANCE CRITERIA: "[ ] Visually verify rendered output in browser \u2014 provide localhost URL or screenshot to user for review." and "[ ] No raw IDs, abbreviations, or jargon visible without human-readable labels or tooltips."
-   - If the task involves image selection, add to SCOPE: "Include brand/theme direction constraints for image selection \u2014 pull from \`docs/branding/brand-book.html\` for canonical brand identity."
-   The planner's job is scoping, not design direction. Design decisions happen at build time via \`.impeccable.md\` (dev patterns) + \`docs/branding/brand-book.html\` (brand identity) and the frontend-design skill \u2014 don't try to write design specs in the handoff.`;
+   - If the task involves image selection, add to SCOPE: "Include brand/theme direction constraints for image selection \u2014 pull from \`PRODUCT.md\` and \`DESIGN.md\` for canonical brand identity."
+   The planner's job is scoping, not design direction. Design decisions happen at build time via \`PRODUCT.md\` (product purpose, users, design principles) + \`DESIGN.md\` (visual tokens) and the frontend-design skill \u2014 don't try to write design specs in the handoff.`;
 var PLAN_FRAGMENT_PRODUCT_BRIEF = `
 12. **Product Brief** \u2014 Check whether the product brief still reflects reality. Update the brief when ANY of these apply:
    - A new AD was created or an existing AD was superseded that changes product scope, target user, or positioning
@@ -388,6 +407,8 @@ ${AD_CONFLICT_SURFACING_RULES}
 
 ${AD_REJECTION_RULES}
 
+${AD_ADMISSION_RULES}
+
    **\u2192 PERSIST:** EVERY AD you created, updated, or confirmed with changes MUST appear in \`activeDecisions\` array in Part 2. Include the full replacement body with ### heading.
 
 ### Operational Quality Rules
@@ -930,6 +951,8 @@ You MUST cover these 5 sections. Each is mandatory.
 
 ${AD_REJECTION_RULES}
 
+${AD_ADMISSION_RULES}
+
 **Registered Documents:** If a "### Registered Documents" section is present in context, scan it for: (a) research findings that contradict current ADs or strategy, (b) unactioned research that should influence the next plan. Reference relevant docs by title in your review. If unregistered docs are listed, flag 1-2 that look strategically relevant and suggest registering them.
 
 **Doc Action Staleness:** If a "### Doc Action Staleness" section is present, treat it as a research-to-action audit. For each entry:
@@ -1278,6 +1301,8 @@ The body field must be the COMPLETE replacement text for the AD block (including
 
 ${AD_REJECTION_RULES}
 
+${AD_ADMISSION_RULES}
+
 ## PHASE UPDATES
 
 If the strategic change affects the project's phase structure, include a phaseUpdates array.
@@ -1450,10 +1475,15 @@ function buildPreScanInstruction(opts) {
   const docRouting = opts.hosted ? "paste the relevant content (decision records, roadmap, spec excerpts) directly into `description` \u2014 over a remote connector PAPI cannot read local file paths." : "pass local doc file paths as `sources` (comma-separated), or paste content into `description`.";
   return [
     `**\u{1F50E} Before you generate anything \u2014 scan the project and gather real context.**`,
-    `A brief and Active Decisions built from the real code and docs are far sharper than ones guessed from a project name. You (the agent running this) have local access that PAPI does not \u2014 do the gathering, then pass it back.`,
+    // task-3293: state the division of labour ONCE, up front. A user watching this
+    // session sees PAPI say it cannot read their files and then sees their agent
+    // read their files. That reads as a contradiction, or worse, unless it is named
+    // first: PAPI never touches the filesystem, YOU do, and you send back a summary.
+    `**How this works:** PAPI has no access to your machine and never reads your files. You (the agent running this) do the reading locally and send back a short summary. Nothing is uploaded except what you pass in that summary.`,
+    `A brief and Active Decisions built from the real code and docs are far sharper than ones guessed from a project name.`,
     ``,
     `1. **Confirm the environment.** Check that you are running from the root of this project's dev environment \u2014 the folder that holds its source, git history, and docs. If you are not there, or you are connected over a remote connector with no access to the user's files, say so and ask the user where the project lives before continuing.`,
-    `2. **Scan the code.** List the top-level directories and files, read the package/build manifest and the README (first ~3000 chars), and collect recent commit subjects. Pass this back as \`codebase_scan\` on the next \`setup\` call.`,
+    `2. **Scan the code.** List the top-level directories and files, read the package/build manifest and the README (first ~3000 chars), and collect recent commit subjects. Pass this back as \`codebase_scan\` on the next \`setup\` call. **Never include secrets** \u2014 skip \`.env\` and any credential, key or certificate file, and do not paste tokens, passwords or connection strings into the summary. PAPI also strips secret-shaped values server-side, but do not rely on that: leave them out.`,
     `3. **Scan the docs.** Look through \`docs/\`, design notes, ADRs/decision records, and any roadmap or planning files \u2014 not just code.`,
     `4. **Check for sibling / separate repos.** Many projects span more than one repo (a separate frontend, backend, infra, or mobile repo, or other packages in a monorepo). Ask the user whether any related repos or directories exist, and scan those too.`,
     `5. **Ask the user to point you at extra context.** Prompt them: "Is there anything else I should read before setting this up \u2014 a PRD or spec, decision records, a roadmap, or links to related repos or docs?" Fold whatever they share into the scan.`,
@@ -1695,6 +1725,7 @@ ${inputs.codebaseContext}
 Return a JSON array of 3-10 tasks based on gaps, improvements, and next steps visible from the codebase analysis above.`;
 }
 export {
+  AD_ADMISSION_RULES,
   AD_CONFLICT_SURFACING_RULES,
   AD_REJECTION_RULES,
   AD_SEED_SYSTEM,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.7.79",
+  "version": "0.7.81",
   "description": "PAPI MCP server — AI-powered sprint planning, build execution, and strategy review for software projects",
   "license": "Elastic-2.0",
   "mcpName": "io.github.getpapi/papi",
@@ -51,13 +51,13 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.82.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@papi-ai/adapter-md": "^0.2.0",
     "@papi-ai/adapter-pg": "^0.2.0",
-    "@papi-ai/shared": "^0.1.0",
+    "@papi-ai/shared": "^0.2.0",
     "@papi-ai/skills": "^0.1.0",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {
+    "@papi-ai/adapter-md": "^0.2.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "tsup": "^8.0.0",