@vegastack/vegafactory 0.19.0

package/skill/dev-intake/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: dev-intake
+description: Turn ideas, brainstorms, feature requests, bug reports, or SOW documents into GitHub issues an agent can act on without further questions. Use when the user asks for a new feature or capability ("add support for X", "I need Y", "can we make it do Z"), when asked to "turn this into issues", "create tasks from this SOW", "write up an issue for" a feature or bug, "users report X — make an issue", "plan this as issues", "slice this epic", or when the user gives approval on a drafted issue and it needs recording. Not for writing the implementation plan of an approved issue (dev-plan), implementing issues or a trivial one-or-two-file fix (dev-implement), creating PRs or merging (dev-ship), or project bootstrap (dev-setup).
+---
+
+# dev-intake
+
+Write the issue: every question is asked here, because dark mode asks none.
+
+Requirements come in as the operator's brainstorm, feature thought, bug report, or SOW; issues go out complete enough that a fresh agent needs nothing but the URL, because an under-specified issue becomes an interruption or a guess.
+
+Nearest neighbors: `dev-plan` owns the how once a brief is approved; intake owns the what/why and the approval mechanics; `dev-implement` builds.
+
+## Ground before you ask
+
+Finding facts is your job, because a brief built on unverified facts is a confident mistake waiting for dark mode. Before the first question:
+
+- **Read the file before speaking about it** — open the actual paths the work would change: current behavior, patterns to reuse, where it plugs in. The brief cites these real paths later, because a brief naming no files is a sign this step was skipped.
+- Verify dependencies: any library, service, or API capability the approach leans on gets checked against current official docs, noted with the date; stack, schema, auth, and infra choices route through `dev-architect`'s verify protocol.
+- Cross-check the request against product docs and current behavior; a contradiction is asked out loud — "you asked for X; the code does Y — which wins?" — because a silently resolved contradiction is a guess the operator did not make. Push back on cost the same way: when a simpler version covers most of the need, name it.
+- Triage every unknown into three bins: *findable* → find it now, yourself; *only-the-operator-knows* → ask, with a recommendation; *only-running-code-can-tell* → a `research` issue or the issue's first spike step. Guessing is not a bin.
+
+## Scope the work — say it out loud
+
+Every issue gets one scope call, announced with its reason, applied as a label, and recorded in the brief's `**Scope:**` line so the reasoning survives the conversation; the operator can override it:
+
+- **`research`** — a question to answer, not code to keep. The brief is the question plus what "answered" looks like.
+- **`quick-build`** — the objective test (conventions' wording): *a small change and the flow being changed already exists in the repo to read*. Missing either half means it is not quick-build; familiarity with the kind of app doesn't count.
+- **`full-plan`** — big or new ground: a new subsystem, a restructuring, a brand-new flow.
+
+When the two halves of the test disagree, or the class is unclear, take the heavier one, because the ratchet only ever goes up. Re-classification after this point belongs to `dev-plan`'s one-way ratchet, and a downgrade waits for the operator's yes.
+
+## The interview
+
+Ask in rounds by the ask route (`references/ask-route.md`): your harness's question tool when you have one and the asker is the issue's operator, otherwise one `questions` comment on the issue and `needs-operator`, because a headless run that cannot ask is not a run that may guess. On that issue route, create the issue before the first round — `needs-operator`, the operator assigned, the request as its body — so the round has a surface; the brief replaces that body once the round is answered. Each round covers the current frontier, every open decision that doesn't depend on another answer. Number the questions; give each a recommended answer with a one-line reason so the operator can reply "all recommended", and skip what the material or an earlier round settled, because a re-asked question reads as not having listened. A vague or self-contradicting answer gets pushback with concrete options — a mermaid or ASCII sketch when a picture beats prose — because a vague answer absorbed silently becomes a guess in dark mode. Stop when *a fresh agent could act on each issue without asking anything.*
+
+The angles, in order — product (who, observable outcome, in/out of scope, slices, priority) → behavior (flows, rules, permissions, edge and failure cases; UI states and copy) → technical (only choices genuinely the operator's, each with a recommendation, checked against `dev-architect`; the version impact where the project versions releases) → quality and risk (what proves it works, what earns `risky`, what stops a dark run). Deep approach trade-offs beyond the operator's choices belong to `dev-plan`. Where dev.md's `issue-fields:` knob names org fields, two of the numbered questions are Priority and Effort, their options read once from `gh api orgs/<org>/issue-fields` and ordered by each option's `priority` key rather than guessed — recommend the option named `Medium` for Priority, or the middle option where the org names none, and for Effort the lowest option on `research` and `quick-build`, the middle option on `full-plan` — so "all recommended" still answers both, and a knob at `none` skips them.
+
+**Bug variant** (`fix:` issues): reproduction steps — or the artifacts needed to obtain them (logs, HAR, recording) — are a required brief section, the brief names `dev-debug` as the implement path, and a bug that can't be reproduced yet becomes a `research` issue first.
+
+## Slicing and hierarchy
+
+- One issue = one outcome that fits one agent session, sliced vertically; blockers use native dependencies, phases milestones, parents native sub-issues.
+- Deliberately deferred work ("someday, not now") lives in the parent's out-of-scope section, because an icebox issue clutters the tracker; a tracking issue exists only on the operator's ask.
+- **Epics:** a multi-deliverable feature gets a parent whose body is a map, because a parent that is also work gets claimed — `Destination` (the one or two lines every session orients to) · `Decisions so far` (one-line gists linking closed children) · `Not clear yet` (in-scope questions you cannot yet phrase sharply — the test is phrasing, not answering; don't pre-slice fog) · `Out of scope` (the tempting adjacent work, named). Each child is classified independently. Only children get `ready`, because the epic is the map.
+- Titles carry the type prefix (dev.md `branch:` type list + `research:`) and the native issue type where the org has them; issue, branch, and PR agree.
+
+## The brief
+
+The issue body follows [brief-template](references/brief-template.md), marker line included: inline over linked, concrete over abstract, evidence over confidence — touch points name real paths, dependency claims carry their check date, and anything unverifiable goes to **Assumptions — confirm or correct**, because an asserted guess binds the agent. Tests-and-acceptance names the seams — the public boundaries tests will live at — because dark mode can't ask later. A brief runs 300–600 words: a section the fresh agent would not need is cut, and one they would have to guess at is missing.
+
+Quick-build issues get their plan now: after the brief has consensus, invoke `dev-plan`'s inline mode in this conversation and post brief (description) + plan (comment) together, so the operator's single approval covers both.
+
+Before posting any brief, run `node <path-to-this-skill>/scripts/brief-lint.mjs --file <draft> --scope <class> --json` (add `--fix` for fix:-type briefs — it requires the Reproduction section): structure gaps block (exit 2), quality smells warn; fix blocks before the operator sees the draft. Inline plans also pass `dev-plan`'s plan-lint.
+
+## Labels and approval
+
+- A new issue starts at `needs-operator` plus its scope label, and `risky` when it touches security, money, user data, or production (names from dev.md's `labels:` knob); create it with `--assignee <operator>`, the login conventions' Labels table resolves from dev.md's `operators:` list, so GitHub's own notification reaches the human whose move it is. An `--assignee` GitHub rejects is reported and the issue stands unassigned, because guessing another login hands the work to the wrong person.
+- Creation also stamps the native type where dev.md's `issue-types:` knob names one for the issue's title prefix — `gh issue create --type <Name>` at gh 2.94.0 and above, otherwise `gh api -X PATCH repos/{owner}/{repo}/issues/{n} -f type=<Name>` in the same breath as creation — and both fields where `issue-fields:` names them, in one request, because the PUT replaces every value it does not carry:
+
+  ```sh
+  gh api "orgs/$ORG/issue-fields" --jq '.[] | select(.name=="Priority" or .name=="Effort") | {id, name}'   # once per run
+  printf '{"issue_field_values":[{"field_id":%s,"value":"%s"},{"field_id":%s,"value":"%s"}]}' \
+    "$PRIORITY_ID" "$PRIORITY" "$EFFORT_ID" "$EFFORT" |
+    gh api -X PUT "repos/$OWNER/$REPO/issues/$N/issue-field-values" --input -
+  gh api "repos/$OWNER/$REPO/issues/$N" --jq .type.name                 # read the type back
+  gh api "repos/$OWNER/$REPO/issues/$N/issue-field-values"              # read the values back
+  ```
+
+  GitHub drops a type or a field value written without push access and returns success, so the two readbacks decide the claim and a mismatch is reported rather than assumed away. Both knobs at `none` — a personal repo, or an org defining neither — means the issue carries its labels and nothing else; say that in one plain sentence instead of reporting a failure.
+- Approval is the operator's explicit words tied to the issue, because labels, silence and time say nothing about consent.
+- Record one schema-v2 approval event per conventions: `scope=brief`, or `scope=brief+plan` for brief plus plan comment. Use bundled `scripts/lib/approval.mjs`’s `artifactRef` on refreshed canonical artifacts; include actual operator words and artifact bindings. Session attestations require a policy-operator publisher; other recorders may only relay an independently verified identical scoped grant per conventions. Evaluate fresh complete history/current policy, preserving canonical `approvalBindings`. Preserve legacy records for scoped reconfirmation; a marker alone grants nothing.
+- Then flip the state, carrying the assignee the Labels table names: `research` and `quick-build` → `ready` (unassigned); `full-plan` → `needs-plan` (the operator).
+- An issue leaves `needs-operator` only once every Assumptions entry is resolved (confirmed, corrected, or moved to a spike) and the section deleted.
+- A directional decision this work settles (dev.md's Decisions test) is proposed as one register line on the operator's yes; `dev-ship` records at merge.
+- The operator edits a draft → apply it and summarize what changed since they last read it.
+
+## After approval
+
+An approved issue that later needs a material change flips back to `needs-operator` with one comment naming what changed; the new approval is recorded the same way and the brief's revision marker bumps. Only the canonicalizer’s specified progress fields preserve approval; every other scope-byte edit requires refreshed intent.

package/skill/dev-intake/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "dev-intake"
+  short_description: "Turn ideas or SOWs into agent-ready GitHub issues"
+  default_prompt: "Use $dev-intake to turn this into GitHub issues."

package/skill/dev-intake/references/ask-route.md

@@ -0,0 +1,80 @@
+# The ask route
+
+Where a round of questions goes when a skill needs the user. Two surfaces: the harness's question tool, or the issue itself. This file is the one home for the route, the comment shape and the reply grammar; `scripts/questions.mjs` is the deterministic method behind them, and the marker row lives in [conventions](conventions.md).
+
+## The route
+
+Three steps, in this order, first match wins:
+
+1. `VSK_ASK_ROUTE` is set to `issue` or `tool` — the dispatcher and CI set it; any other non-empty value is refused rather than guessed.
+2. This harness and this run have no question tool → `issue`.
+3. The asker is not the issue's operator → `issue`. An unresolved asker or operator is also `issue`.
+
+Otherwise the tool. The issue route needs an issue: where none exists yet — dev-intake's interview runs before its issue is created — the skill creates the issue first, at `needs-operator` with the operator assigned and the request as its body, and posts the round to it; the brief is written into that issue once the round is answered. On the tool route the issue is created after approval, as before. Settle it deterministically rather than by judgement:
+
+```sh
+node <path-to-this-skill>/scripts/questions.mjs route --tool <name|none> --asker <login> --operator <login> --json
+```
+
+Which tool each harness has — and the Codex Plan-mode gating on `request_user_input` — is recorded in dev-setup's `references/harness-facts.md` (a backticked path, not a link: this file ships into dev-intake, dev-plan and dev-implement, which do not carry that reference) and not restated here. The operator identity comes from the caller under dev.md's `operators:` knob; the script takes both logins as inputs and never resolves them itself.
+
+The bias is deliberate: a round in a comment is always readable by whoever owns the issue, and a round put to the wrong person is not.
+
+## The comment
+
+One comment per round, marker first, the whole round wrapped in `<questions>` tags so the parser and the model both find it inside a comment that may carry prose around it:
+
+```markdown
+<!-- vsk:v1 type=questions rev=1 -->
+## Questions (v1)
+
+<questions>
+**Q1.** Where does the reminder queue live?
+- a) A Postgres table
+- b) A Redis list (recommended — Redis is already a dependency)
+
+**Q2.** How late may a reminder fire?
+- a) Within the hour (recommended — matches the existing cron cadence)
+- b) Same day
+
+Reply with `1: a` per question, or `all recommended`.
+</questions>
+```
+
+No question, option or reason may carry an HTML comment delimiter or a `questions` block tag: a round can be read back out of a comment anyone may have written, so text that could close the block or forge a marker is refused in both directions. Every question carries at least two options and exactly one recommendation, and every recommendation carries its one-line reason — a round that cannot say which way it leans is a round that has not been thought through, and the renderer refuses it. Options run `a` through `h`. After posting, the label moves to `needs-operator` and the session ends.
+
+## Replying
+
+Anyone on the issue may answer, in an ordinary comment, one line per question:
+
+- `1: b`
+- `2: a — the cron already runs` (trailing prose after the dash is kept)
+- `3: other — a third way` (`other` is accepted for any question)
+- `all recommended` on its own line fills every question not answered explicitly
+
+An explicit line always beats `all recommended`. Bulleted lines, a `.` instead of `:`, and upper-case letters all parse. Surrounding prose is ignored; the first answer to a question stands and a repeat is reported. A numbered line whose letter runs straight into prose with no dash (`1: a is wrong, go with b`) is malformed, not an answer of `a` — the parser reports it and the question is re-asked.
+
+## Re-asks
+
+Parse before asking anything. A later session has no `round.json` on disk, so it reads the round back out of the posted comment — that is what the `<questions>` wrapper is for, and `--round <comment.md>` takes it in place of `--spec`. What comes back is answered questions, still-open questions, and malformed lines. If nothing is open, continue — never re-ask an answered question. If something is open, post a second comment at `rev=<n+1>` carrying only the open questions **at their original numbers**, so `**Q3.**` stays Q3. Earlier `questions` comments are left in place as record. A reply with no answer line at all is malformed, not empty: it gets one re-ask naming the expected shape.
+
+## What it is not
+
+An answer is not an approval. Any teammate may answer a round; only the operator approves, and approval is still its own `approval` marker comment recording the operator's own words in the `(<username>)` format ([conventions](conventions.md)). A round that is fully answered unblocks the work; it does not move the issue to `ready`.
+
+Assignment is not this route's job either — the label moving to `needs-operator` is what puts the issue on the operator.
+
+## Commands
+
+Save the reply comment to `.vegastack/.tmp/<issue>-<slug>/reply.md` first; the parser reads a file, never a network.
+
+```sh
+node <path-to-this-skill>/scripts/questions.mjs render --spec round.json --rev 1 --json
+node <path-to-this-skill>/scripts/questions.mjs parse  --comment reply.md --round asked.md --json
+node <path-to-this-skill>/scripts/questions.mjs re-ask --round asked.md --comment reply.md --rev 2 --json
+node <path-to-this-skill>/scripts/questions.mjs route  --tool none --asker <login> --operator <login> --json
+```
+
+`asked.md` is the posted `questions` comment; `--spec round.json` takes the same round as JSON instead, where the rendering session still has it. A spec is `{ "questions": [ { "text": "…", "options": [ { "letter": "a", "text": "…" }, { "letter": "b", "text": "…", "recommended": true, "reason": "…" } ] } ] }`.
+
+Exit codes: 0 pass · 1 answers still open or malformed, and for `re-ask` nothing left to ask · 2 refusal or usage error.

package/skill/dev-intake/references/brief-template.md

@@ -0,0 +1,89 @@
+# Issue brief template
+
+The issue body a workable issue must have. Write the sections that apply, delete the rest. The test for every section: would a fresh agent have to guess or ask without it?
+
+```markdown
+<!-- vsk:v1 type=brief rev=1 scope=research|quick-build|full-plan -->
+**Scope:** research | quick-build | full-plan — the announced reason for the call, one line.
+**Priority:** <one of the org's Priority options> — the answer from the interview. Delete this line where dev.md's `issue-fields:` knob is `none`.
+**Effort:** <one of the org's Effort options> — the answer from the interview. Delete this line where the knob is `none`.
+
+## Outcome
+
+What exists when this is done, in observable terms — what the user can do, what the
+system produces. One paragraph.
+
+Research issues replace Outcome and the build sections with two headings brief-lint
+expects verbatim in spirit: `## The question` (what this issue resolves) and
+`## What answered looks like` (the evidence that closes it). Risks/stop conditions
+and Assumptions still apply.
+
+## Out of scope
+
+The nearby things this issue deliberately does NOT do. This is what stops scope creep
+in dark mode — name the tempting adjacent work.
+
+## Rules and edge cases
+
+The behavior that isn't obvious: validations, permissions, limits, empty/error/concurrent
+cases, what happens on failure. Bullet list, one behavior per line.
+
+## Reproduction            <!-- fix: issues only -->
+
+The exact steps (or attached artifacts — logs, HAR, recording) that demonstrate the
+bug today, and the observed vs expected behavior. A bug without this is a `research`
+issue, not a fix. The implement path is dev-debug.
+
+## UI states            <!-- only when there is UI -->
+
+Loading, empty, error, success, disabled. Which design-system components. Copy for
+user-facing text. Responsive and keyboard behavior when it matters.
+
+## Approach and touch points
+
+The chosen technical approach in a few lines: which parts of the codebase change,
+new/changed interfaces or schemas, data migrations. Routine choices stay the
+implementer's — don't specify them. Name the docs and changelog surfaces this change
+must update. Task-level detail belongs to the plan (dev-plan), not here.
+**Version impact:** patch | minor | major, one-line reason — only when the project
+versions releases (dev.md `changelog:` knob).
+
+## Tests and acceptance
+
+What proves it works: the cases tests must cover (success, boundary, failure,
+authorization where relevant), the commands to run, and the **seams** — the public
+boundaries tests live at (dark mode can't negotiate seams later; they're settled
+here). Acceptance = the Outcome plus these passing.
+
+## Risks and stop conditions
+
+What could go wrong and what should make the agent stop and ask instead of pushing
+through — beyond the standing stop-list in .vegastack/dev.md.
+
+## Assumptions — confirm or correct
+
+Anything material the grounding investigation could not verify, one per line, each
+awaiting the operator's confirm/correct. The issue cannot leave needs-operator while
+one is unconfirmed. Verified facts never appear here — they live in their section
+with their evidence. Delete the whole section once every entry is resolved (its
+presence alone blocks preflight).
+```
+
+## Writing rules
+
+- Inline over linked: the material details live in the issue itself. A link supports; it never substitutes.
+- Concrete over abstract: "rejects amounts over 10,000 with error E402" beats "validates input".
+- Evidence over confidence: touch points name real file paths; a dependency capability claim carries the doc check and its date; what couldn't be verified goes to Assumptions, never stated as fact.
+- The brief binds the agent, so ambiguity is a bug in the brief — if two readings exist, the interview wasn't done.
+- Post-approval edits follow the revision-marker rule in dev-setup's `references/conventions.md` (heading `(v2)`, marker `rev=2`, a `Revisions:` line).
+- A `Decision:` comment exists only for a choice that passes the Decisions test in `.vegastack/dev.md` — feature requests and implementation details never qualify; they are brief content, not register lines.
+
+### Summarising an SOW
+
+The brief restates the SOW in the agent's own words and quotes only the terms the client owns — dates, amounts, defined deliverables — so a reader can tell our reading from their commitment:
+
+<example>
+SOW excerpt: "Vendor shall deliver a customer portal supporting invoice download (PDF), payment status, and dispute submission within 60 days of kickoff."
+
+Outcome, in the brief: A signed-in customer opens their portal, downloads any invoice as a PDF, sees whether it is paid, and files a dispute against it. The SOW commits to delivery "within 60 days of kickoff" — quoted, because the date is the client's term and not ours to soften. "Dispute submission" is quoted because the SOW does not say what a dispute contains; that gap is the first line under Assumptions — confirm or correct.
+</example>

package/skill/dev-intake/references/conventions.md

@@ -0,0 +1,113 @@
+# Workflow conventions
+
+Artifact authority.
+
+Defaults resolve repo, group, then org; locks require explicit org delegation. Repository dispatch/commands never inherit; registers concatenate. Policy/migration uses dev-setup's `scripts/effective-policy.mjs` and vegafactory-setup's control-room reference.
+
+## Comment metadata markers
+
+Comments open:
+
+```markdown
+<!-- vsk:v1 type=<type> rev=<n> [key=value ...] -->
+## <Human title> (v<n>)
+```
+
+| type | required keys | instances |
+|---|---|---|
+| `approval` | `scope=<brief\|brief+plan\|plan\|consolidated\|none>` and schema-v2 JSON | one per approval event |
+| `questions` | `rev` | one per ask round; earlier rounds stay as record (dev-setup's `references/ask-route.md`) |
+| `plan` | `rev` | one, edited in place |
+| `ledger` | `branch` | one, edited in place |
+| `evidence` | `rev branch sha` | one, edited in place |
+| `review` | `round sha agent=<claude\|codex> verdict=<clean\|needs-fixes>` | one per review cycle, rounds appended inside |
+| `decision` | — | one per decision proposal |
+| `handback` | — | one per stop event |
+
+`rev=<n>` and `(v<n>)` start at 1 only on brief, plan, questions and evidence; other types have neither. Locate by marker, never heading/legacy fallback.
+
+## Operator identity
+
+Use parenthesized GitHub usernames:
+
+- Approval: `Approved by (<username>) on DD-MM-YYYY: "<their words>"`
+- Register line: `- DD-MM-YYYY (<username>) — <decision>`
+
+Approval.mjs’s publisher/relay contract lets current-policy provider-envelope publishers attest listed operators’ session words. Other recorders may only relay independently read identical operator-published scoped grants within complete authority history, without lifecycle mutations. Relays inherit source authority/lifecycle; account attestation cannot authenticate off-platform speech.
+
+## Scoped approval records
+
+Use only dev-implement’s `scripts/lib/approval.mjs` and follow its contract. Refresh current policy and complete GitHub histories. `ArtifactRef={repo,issue,kind,artifactId,rev,digest}` binds brief issue-node or unique plan/protocol comment-node identity, revision and canonical SHA-256.
+
+Post exactly one approval comment: matching scope marker, then one fenced JSON `ApprovalRecord={schemaVersion:2,id,operator,scope,source:{kind,ref,quote},artifacts,supersedes,revokes}`. Exclude outer Markdown fences, future alternatives and unresolved source locators; validate the whole body with approval.mjs's `parseApproval`. Source kind is `session` or `github-comment`, with inspectable words. Reuse valid current grants/relays; avoid counterfactual plan-only or redundant approvals. Scope is `brief`, `plan` or `brief+plan`; planning requires brief, implementation both, research execution also its protocol. Empty-artifact revocations remove exact earlier IDs. Conflicts explicitly supersede; newest never wins.
+
+Preserve legacy comments. Without writes, inventory refusals/current digests and request reconfirmation. For duplicate canonical plans preserve both identities/bodies and request record-preserving reconciliation; never delete to clear ambiguity. Follow approval.mjs’s exact correction schema, operator-publisher and target checks. Only malformed or demonstrably invalid-source targets qualify, never valid authority or unavailable/inconsistent facts. Resolve source facts first; corrections grant no scope. Exact child checkpoint actions bind one selected code child's branch/ref/base/tasks/files; other actions never substitute.
+
+Consolidated parent events bind frozen manifests, canonical artifacts and exact task/action subsets. Use inline UTF-8 or immutable repository/commit/path plus blob hash, never local paths. Canonical `approvalBindings` authorize; requested `recordBinding` only audits. Follow approval.mjs’s preparation/research/recovery provenance, receipts, adapters, counted attempts and fresh admission; retain immutable history and unverified legacy records. Keep checkpoint/private/live/shipping gates separate.
+
+Canonicalization normalizes CRLF; its only exceptions are structural plan checkboxes and one validated JSON `{tasks:[{id,evidenceUrls}]}` block between `<!-- vsk:progress:start -->` / `<!-- vsk:progress:end -->`. IDs must exist; URLs are HTTP(S); unknown fields/duplicates refuse. Stable task IDs/order, interfaces, actions, revisions and all other bytes remain scope. Brief/protocol bodies have no mutable fields; fenced examples stay immutable and grant no authority.
+
+## Revision markers
+
+Scope edits increment marker/heading revisions and append `Revisions: v2 — DD-MM-YYYY: <change>, per (<username>) correction`; preserve earlier lines and obtain fresh approval. Validated progress changes need neither.
+
+## Scope classes
+
+Intake explains scope; operator overrides:
+
+- **`research`** — inquiry; throwaway code allowed, never merged. No branch/PR/changelog; evidence comment contains findings and recommendation.
+- **`quick-build`** — existing flow: draft brief+plan together, approve both, then `ready`.
+- **`full-plan`** — new ground: approve brief, `needs-plan`, separate grounded planning session, `needs-operator`, approve plan, `ready`. Split multiple deliverables into independently classified epic children.
+
+Scope ratchet: `dev-plan`.
+
+## Labels
+
+One state; flips set assignees (colors: dev-setup):
+
+| label | meaning | assignee |
+|---|---|---|
+| `needs-operator` | question, brief or plan approval, proposal | the operator |
+| `needs-plan` | brief approved; awaiting planning (full-plan only) | the operator |
+| `ready` | approved — an agent may start | nobody |
+| `working` | claimed; ledger shows live progress | the runner |
+| `for-operator` | done — evidence posted, awaiting operator review | the operator |
+
+Modifiers coexist with state: `risky` · scope `research` / `quick-build` / `full-plan` · `epic` (map parents without a native Epic type). Boards mirror states one-way.
+
+## Titles, types, hierarchy
+
+- **Title prefixes:** issues, branches and PRs use dev.md's `branch:` types plus `research:`; PR title = issue title.
+- **Native issue types/fields:** Feature (feat) · Bug (fix) · Task (docs/chore/refactor/research) · Epic for parents (else label); intake sets Priority/Effort. Scope classes stay labels.
+- **Hierarchy:** epic parent = map only (Destination · Decisions so far · Not clear yet · Out of scope), with native child sub-issues. Issues are work units (brief, approvals, branch, PR, evidence); tasks are checkboxes **only in the plan comment**. Blockers use dependencies; phases use milestones. Only non-epic issues get `ready`.
+
+## The ledger
+
+One implementation ledger:
+
+```markdown
+<!-- vsk:v1 type=ledger branch=<branch> -->
+## Ledger — <branch>
+- <issue>-T<N>: complete (commits <base7>..<head7>[, review clean | K parked])
+- <issue>-T<N>: fix round <R>/3 (<X> addressed, <Y> open — <one-liners>; commits <a>..<b>)
+- Ruling: <what> — <why> — cost if wrong: <cost>
+- <issue>-T<N>: parked — <finding> — Ruling: <why the code stands>
+- Deferred minor: <one-liner>
+```
+
+
+**Resume protocol:** brief → plan comment → ledger → `git log`; then reconcile task IDs, canonical approval history, edited authority, source/evidence, ownership and delivery effects. Preserve completed work/provenance; stale heartbeat is not stop proof. Preparation never implies issue completion. Dev-implement's ledger reference owns recovery detail.
+
+## `.vegastack/` workspaces
+
+Drafts/reports: `.vegastack/.tmp/<issue-number>-<title-slug>/` (pre-issue: `intake-<slug>`), self-ignored by a `.gitignore` containing `*`. Branch checkouts: root-ignored `.vegastack/.worktrees/<issue-number>-<title-slug>/`; main stays on its default branch. Keep both outside `.git/`. Subagents save full reports and return short status. `<path-to-this-skill>` means SKILL.md’s directory.
+
+## Verification gate
+
+Prove claims with fresh command output and exit codes; report failures and skips. Delegate only substantial independent parallel work, never your own verification; keep spawn counts low. Guards block machine-verifiable failures (exit 2); heuristics warn. Guards contain no AI inference; unverifiable state fails closed.
+
+## Review bindings
+
+One fenced JSON each: `{"reviewBinding":{sha,baseSha,scopeDigest,verdict,findings:[{id,status}]}}` in review; `{"adjudication":{sha,reviewCommentId,operator,source:{kind,ref,quote},findings:[{id,disposition,reason}]}}` in evidence. Use full commit IDs and canonical-plan scopeDigest; status=open/resolved; disposition=accept-risk. Every open finding requires same-review operator acceptance. dev-ship’s README defines source checks. No prose exceptions.
+
+Communicate starts/findings/direction plainly; self-contained outcomes include paths and remaining checks. Avoid invented labels/arrows; visualize usefully. Challenge ambiguity with options; never guess silently.

package/skill/dev-intake/refresh/REFRESH.md

@@ -0,0 +1,3 @@
+# Refresh contract — dev-intake
+
+Evergreen: this skill asserts no version pins, vendor mechanism names, numeric vendor limits, or dated facts — its content is interview discipline, slicing rules, the brief template, and the approval-recording rule, all versionless. The harness question-tool mechanics it leans on are tracked by `dev-setup`'s registry (see `skills/dev-setup/refresh/`). Revisit if a future edit introduces a volatile fact.

package/skill/dev-intake/refresh/sources.json

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "retrievalBaseline": "2026-08-27",
+  "note": "Evergreen waiver recorded in REFRESH.md; sources deliberately empty.",
+  "sources": []
+}

package/skill/dev-intake/scripts/brief-lint.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// dev-intake guard: deterministic checks on a drafted brief before posting.
+// Missing structure blocks; quality smells only warn (heuristics never block).
+// Inline quick-build plans are linted separately by dev-plan's plan-lint — the
+// banned-placeholder list lives there, its single home.
+//
+// Exit codes: 0 pass · 1 pass-with-warnings · 2 blocked (reasons printed).
+// Usage: node brief-lint.mjs --file <brief.md> --scope <research|quick-build|full-plan> --json
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REQUIRED_HEADINGS = {
+  research: [/^##\s+.*question/im, /^##\s+.*answered/im],
+  'quick-build': [/^##\s+Outcome\b/m, /^##\s+Tests and acceptance\b/m, /^##\s+Approach/m],
+  'full-plan': [/^##\s+Outcome\b/m, /^##\s+Out of scope\b/m, /^##\s+Tests and acceptance\b/m, /^##\s+Approach/m],
+};
+
+const VAGUE_SMELLS = [
+  /\bworks (properly|correctly|as expected)\b/i,
+  /\buser[- ]friendly\b/i,
+  /\brobust(ly)?\b/i,
+  /\betc\.?\b/i,
+];
+
+export function lintBrief(text, scope, { fix = false } = {}) {
+  const blocks = [];
+  const warns = [];
+
+  if (!REQUIRED_HEADINGS[scope]) {
+    return { blocks: [`unknown scope class "${scope}" (research | quick-build | full-plan)`], warns };
+  }
+  if (!/<!--\s*vsk:v1\s+type=brief\b/.test(text)) blocks.push('missing brief marker (<!-- vsk:v1 type=brief rev=n scope=... -->)');
+  if (scope !== 'research' && !/^\*\*Scope:\*\*/m.test(text)) {
+    blocks.push('missing the **Scope:** line — the announced reason must survive the conversation');
+  }
+  if (fix && !/^##\s+Reproduction\b/m.test(text)) {
+    blocks.push('fix-type brief without a ## Reproduction section — an unreproducible bug is research first');
+  }
+
+  for (const heading of REQUIRED_HEADINGS[scope]) {
+    if (!heading.test(text)) blocks.push(`missing required section for ${scope}: ${heading.source}`);
+  }
+
+  if (scope !== 'research') {
+    const approach = text.split(/^(?=##\s)/m).find((chunk) => /^##\s+Approach/.test(chunk));
+    if (approach && !/`[^`]*[/.][^`]*`/.test(approach)) {
+      blocks.push('Approach and touch points names no real backticked paths — grounding was skipped or unrecorded');
+    }
+  }
+
+  for (const smell of VAGUE_SMELLS) {
+    const hit = smell.exec(text);
+    if (hit) warns.push(`vague wording: "${hit[0]}" — name the observable behavior instead`);
+  }
+
+  return { blocks, warns };
+}
+
+const invokedDirectly = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  const argv = process.argv.slice(2);
+  const json = argv.includes('--json');
+  const get = (flag) => { const i = argv.indexOf(flag); return i === -1 ? undefined : argv[i + 1]; };
+  let outcome;
+  const file = get('--file');
+  const scope = get('--scope');
+  if (!file || !scope) {
+    outcome = { blocks: ['usage: brief-lint.mjs --file <brief.md> --scope <class> [--fix] [--json]'], warns: [] };
+  } else {
+    try {
+      outcome = lintBrief(readFileSync(file, 'utf8'), scope, { fix: argv.includes('--fix') });
+    } catch (error) {
+      outcome = { blocks: [`cannot read brief: ${error.message}`], warns: [] };
+    }
+  }
+  const ok = outcome.blocks.length === 0;
+  const exitCode = ok ? (outcome.warns.length ? 1 : 0) : 2;
+  if (json) {
+    console.log(JSON.stringify({ guard: 'brief-lint', ok, ...outcome }, null, 2));
+  } else {
+    console.log(`brief-lint: ${ok ? (outcome.warns.length ? 'pass with warnings' : 'pass') : 'BLOCKED'}`);
+    for (const b of outcome.blocks) console.log(`  block: ${b}`);
+    for (const w of outcome.warns) console.log(`  warn: ${w}`);
+  }
+  process.exit(exitCode);
+}