naive-framework 0.0.0-stage → 0.1.0

package/operations/handoff-v2.md

@@ -0,0 +1,93 @@
+---
+type: planning
+source: hybrid
+created: <% tp.date.now("YYYY-MM-DDTHH:mm:ss[Z]") %>
+ai-model: <model>
+authority: implementation
+decision-status: in-force
+status: READY
+progress: "Not started."
+governed-by:
+  - "<the ADR or decision this executes>"
+role: builder            # the position this handoff is assigned to (agent-roles.json id)
+entity: "<entity>"       # where the position lives (decision levels)
+domain: <domain>
+serves: [<product or harness>]
+owner: <position id>
+session-id: "<id of the session that wrote this handoff>"      # Claude Code: from the scratchpad path; otherwise the runtime's run id, or unknown
+parent-session-id: "<id of the session that assigned it, if any>"  # lineage: umbrella CoS -> ecosystem CoS -> role
+handoff-status: ready     # ready | in-progress | escalated | done
+claimed-by: ""            # session or run id of the agent that claimed it
+pr: ""                    # PR link once opened
+max-attempts: 3           # runs (claims) allowed before escalating to the Architect (EE-006)
+run-cap: "2h"             # wall-clock or spend cap per run, e.g. "2h" or "$20"; reaching it escalates (EE-006)
+attempts: 0               # incremented by each run that claims this handoff
+tags: [handoff, v2]
+---
+
+# <Title>: handoff to <role> (<date>)
+
+> Handoff contract v2 ([[FOUNDER_OPERATING_MODEL_CAMPAIGN_2026-10-14]] §4.4). You hold the decision rights below. **Do not report back to Claude or the founder for anything inside them.** Stop only on an escalation class (§4).
+
+## 0. Where this lives and how it is picked up
+
+- **Implementation handoffs** live in the code repo at `docs/handoffs/` and are listed in `docs/handoffs/index.json`; the vault work queue points to them (implementation-bound artifacts are canonical in the repo).
+- **Other handoffs** (finance, research, design) live in the vault at `<entity>/product/planning/handoffs/`, listed in `<vault>/_meta/registers/work-queue.json`.
+- **To claim (code handoffs):** open a draft PR titled `<id>: <title>` whose first commit sets `handoff-status: in-progress` and `claimed-by` in the index and this file. The open PR is the lock; if two exist, the older wins. Cursor automations open PRs but are not documented to push to main, so this replaces committing to main (see the repo's `docs/handoffs/PICKUP_AUTOMATION.md`).
+- **To claim (vault handoffs):** set `handoff-status: in-progress` and `claimed-by`, commit and push; a rejected push means someone else claimed it.
+- **Before claiming, check it is ready (EE-019):** run `node schema/check-ready.mjs <venture> <id>`. Any FAIL is a question for the author, asked before work starts; do not fill the gap yourself. When every item passes and the brief tells you enough to act, record it with `--record --by <you>`. An in-progress handoff without this record fails `check-execution.mjs`.
+- **While working:** `in-progress`; on an escalation, `escalated` and write §7; when done-criteria pass and the PR is up, `done` with `pr`.
+
+## 1. Outcome
+
+One paragraph: what exists when this is done, and why (the decision it executes).
+
+## 2. Work
+
+Numbered steps or workstreams. One PR per workstream.
+
+## 3. Your decision rights
+
+From `everything-ecosystem/venture-template/decision-rights.json` (and `<entity>/_meta/registers/decision-rights.json` if it tightens any class). List the classes that apply:
+
+| You decide | Level |
+|---|---|
+| Implementation inside this handoff | decide |
+| Accepting work that passes the done-criteria in §5 | decide |
+| Schema change inside the governing ADR, via the documented procedure | decide-inform |
+| Security tightening | decide-inform |
+
+**Research:** you may research anything this work needs (current docs, APIs, library versions, prior art). Record new sources in the source register. If a finding would change a decision above your level, escalate it; do not act on it.
+
+## 4. Escalate only for
+
+| Class | Goes to |
+|---|---|
+| Contradicts an in-force ledger decision or ADR | Architect, then founder |
+| Security loosening; irreversible data change; new structure without an ADR | Architect |
+| Money, legal terms, anything public, production ship | Founder (or named delegate) |
+| `attempts` reached `max-attempts`, or a run hit `run-cap` (EE-006) | Architect |
+
+Write the question in §7 and continue any work it doesn't block.
+
+## 5. Done-criteria (conformance, checked by CI or scripts)
+
+Each criterion is objectively checkable. Name the command or test:
+
+- [ ] `<command>` passes
+- [ ] `<golden or invariant>` holds
+- [ ] **Self-proof (EE-006):** `<the command or skill that exercises the change for real, e.g. drive the running app to the changed screen>`; evidence (screenshot, log or output) attached to the PR. Tests passing is not this step.
+
+Classes marked for Architect review (fit to intent), if any: <list, or "none">.
+
+## 6. Report (to the PR and registers, not to a person)
+
+- PR link and description: what changed, criteria results, anything unexpected.
+- Update affected registers (dependency, risk, open questions) and run their renderers.
+- Record decide-inform decisions in the PR description.
+- Put this handoff's `session-id` and your own run or session id in the PR description, so work traces back through the chain (source S-001).
+- If something failed for a reason that could recur (a wrong path, a missed convention, a check you had to run by hand), name the lesson and propose the check one rung higher that would catch it next time: prose, skill, rule, static analysis, code (EE-006). The Architect decides whether to add it.
+
+## 7. Escalations
+
+(Write here. Each: class, question, what is blocked, what continued.)

package/operations/layer.json

@@ -0,0 +1,60 @@
+{
+  "layer": "operations",
+  "purpose": "Run the business (business operations): the team plan and hiring, handing work to people and agents (handoffs, with decision rights, done-criteria, attempt limits and run caps), and the tools each function uses, such as marketing (including the marketing website, EE-044), sales and research. How software or hardware gets built is MAD's, a separate product that reads these records (EE-038).",
+  "skills": [
+    {
+      "id": "tool-selection",
+      "path": "operations/skills/tool-selection/SKILL.md"
+    },
+    {
+      "id": "team-design",
+      "path": "operations/skills/team-design/SKILL.md"
+    },
+    {
+      "id": "recruiting",
+      "path": "operations/skills/recruiting/SKILL.md"
+    }
+  ],
+  "records": [
+    "team-plan",
+    "handoff",
+    "department-catalog",
+    "department",
+    "marketing-matrix",
+    "site-presence",
+    "marketing-sitemap",
+    "marketing-content"
+  ],
+  "reads": [
+    "agent-capability",
+    "board",
+    "decision",
+    "decision-rights",
+    "icp",
+    "integration",
+    "ownership",
+    "product",
+    "publication-policy",
+    "role",
+    "telos",
+    "venture"
+  ],
+  "writes": [
+    "evidence"
+  ],
+  "checks": [
+    "schema/check-team.mjs",
+    "schema/check-ready.mjs",
+    "schema/run-handoff.mjs",
+    "schema/check-execution.mjs",
+    "schema/check-departments.mjs",
+    "operations/marketing/site/presence.mjs",
+    "operations/marketing/site/plan.mjs",
+    "operations/marketing/check-public.mjs"
+  ],
+  "gaps": [
+    "No run-handoff skill: the handoff contract is prose (operations/handoff-v2.md) beside three scripts in schema/ (check-ready, run-handoff, check-execution)",
+    "Business functions (marketing, sales, finance) have no record types yet; only the team plan and handoffs do"
+  ],
+  "name": "operations"
+}

package/operations/marketing/check-public.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// The public gate for marketing content (EE-064): marketing records are public variants of internal
+// records, written by marketing agents as their own MDX, never internal records published as they are.
+// Every file in operations/marketing/content/ must name the internal record it is a variant of, the
+// audience it is for, and whether it is published; a published file must name the person who approved
+// it (EE-025). And it must not copy the internal record: any run of ten words shared with it is a leak,
+// unless the run is a public field (the venture's name and tagline, a product's name).
+//
+//   node operations/marketing/check-public.mjs <venture> [--json]
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+export const CONTENT = "operations/marketing/content";
+const RUN = 10;
+const words = (s) => s.toLowerCase().replace(/<[^>]+>/g, " ").match(/[a-z0-9$%']+/g) ?? [];
+const runs = (s) => { const w = words(s), out = new Set(); for (let i = 0; i + RUN <= w.length; i++) out.add(w.slice(i, i + RUN).join(" ")); return out; };
+const strings = (x) => typeof x === "string" ? [x] : Array.isArray(x) ? x.flatMap(strings) : x && typeof x === "object" ? Object.values(x).flatMap(strings) : [];
+
+export function frontmatter(text) {
+  const m = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!m) return { meta: {}, body: text };
+  const meta = Object.fromEntries(m[1].split("\n").map((l) => l.match(/^([a-z_]+):\s*(.*)$/)).filter(Boolean).map(([, k, v]) => [k, v.replace(/^["']|["']$/g, "").trim()]));
+  if (meta.publish) meta.publish = meta.publish === "true";
+  return { meta, body: m[2] };
+}
+
+function files(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).flatMap((f) => statSync(join(dir, f)).isDirectory() ? files(join(dir, f)) : f.endsWith(".mdx") ? [join(dir, f)] : []);
+}
+
+export function check(dir) {
+  const venture = existsSync(join(dir, "venture.json")) ? JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")) : {};
+  const publicText = [venture.name, venture.brand?.tagline].filter(Boolean);
+  const pdir = join(dir, "products");
+  if (existsSync(pdir)) for (const f of readdirSync(pdir).filter((f) => f.endsWith(".json"))) publicText.push(JSON.parse(readFileSync(join(pdir, f), "utf8")).name ?? "");
+  const allowed = new Set(publicText.flatMap((t) => [...runs(t)]));
+  const results = files(join(dir, CONTENT)).map((f) => {
+    const rel = relative(dir, f), { meta, body } = frontmatter(readFileSync(f, "utf8")), errors = [];
+    if (!meta.variant_of) errors.push("names no internal record (variant_of): marketing content is a variant of an internal record");
+    else if (!existsSync(join(dir, meta.variant_of))) errors.push(`variant_of ${meta.variant_of} does not exist`);
+    if (!meta.audience) errors.push("names no audience");
+    if (meta.publish === undefined) errors.push("does not say whether it is published (publish: true or false)");
+    if (meta.publish === true && !meta.approved_by) errors.push("is published without a person's approval (approved_by, EE-025)");
+    if (meta.variant_of && existsSync(join(dir, meta.variant_of))) {
+      const src = join(dir, meta.variant_of);
+      const raw = readFileSync(src, "utf8");
+      const internal = new Set(strings(src.endsWith(".json") ? JSON.parse(raw) : raw).flatMap((s) => [...runs(s)]));
+      const leaks = [...runs(body)].filter((r) => internal.has(r) && !allowed.has(r));
+      if (leaks.length) errors.push(`copies ${leaks.length} run(s) of ${RUN} words from ${meta.variant_of}, such as "${leaks[0]}": write the public variant in its own words`);
+    }
+    return { file: rel, publish: meta.publish ?? null, errors };
+  });
+  return { venture: venture.id ?? null, files: results.length, errors: results.filter((r) => r.errors.length), results };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const dir = process.argv[2];
+  if (!dir) { console.error("usage: node operations/marketing/check-public.mjs <venture> [--json]"); process.exit(2); }
+  const r = check(dir);
+  if (process.argv.includes("--json")) console.log(JSON.stringify(r, null, 2));
+  else {
+    console.log(`${r.files} marketing content file(s); ${r.errors.length} blocked at the public gate`);
+    for (const x of r.errors) for (const e of x.errors) console.log(`  ${x.file}: ${e}`);
+  }
+  process.exit(r.errors.length ? 1 : 0);
+}

package/operations/marketing/site/README.md

@@ -0,0 +1,86 @@
+---
+type: framework
+source: hybrid
+created: 2026-10-28T20:10:00Z
+ai-model: claude-opus-5.5
+tags: [everything-ecosystem, operations, marketing, marketing-website, site-presence, icp, typesafe, jev, firecrawl]
+description: "Site presence: read a venture's website, judge which pages say what with Jev, and score how present its public records are, weighed by who the site must speak to now and why (the marketing matrix, customer types), shown as the site's sitemap with a rating per route. Version 0.1.0, unevaluated."
+---
+
+# Site presence and the marketing matrix
+
+Version 0.1.0, ours and unevaluated (EE-062, EE-063, EE-064, EE-065). For the demo there are no connections: a founder pastes a link to their marketing site (or their product), and Naive reads it.
+
+## What it does
+
+1. **Read.** `platform/integrations/site.mjs` reads the home page and up to nine pages it links to. Pages a marketing site usually has (about, pricing, careers, investors, community, press, security) come first, one per section. Firecrawl renders the pages when `FIRECRAWL_API_KEY` is set. Otherwise a plain fetch reads the HTML, which misses sites that only render in the browser. Each page records where it sits: the home page, the header or navigation, linked from the home page (the footer counts), or deeper.
+2. **Judge.** Jev answers one typed question per page and item: "Does this page tell a visitor …?" That is 150 questions for ten pages, in about 0.4 seconds. Without a Jev key, the matrix's keywords judge instead, which is rougher, and the result says so.
+3. **Weigh.** The marketing matrix (`matrix.json`) names six audiences: customers, investors, candidates, contributors, partners and press. It lists fifteen items each audience may need to learn, and the record each item comes from. Every item is public by default (publish: true).
+   - **Audience weights** come from the venture's facts: raising, hiring, inviting contributors, and what its ICP records say about who it courts. Investors weigh 1 while the venture is raising and 0.15 otherwise.
+   - **An item's need** is its strongest audience weight times importance.
+   - **Need sets prominence:** 0.7 or more belongs on the home page, 0.4 in the navigation, 0.2 linked from the home page, and anything less can be anywhere. An item with its own page, such as pricing or careers, needs that page in the navigation, not on the home page.
+4. **Score.** An item scores 1 when it is as prominent as it needs to be, 0.5 when it is present but buried, and 0 when it is missing. The site score is the need-weighted share, from 0 to 100, with a score for each audience. "Fix first" lists the three most-needed items that fall short. A missing item that no audience needs now is noted and not held against the site.
+
+## Who the customers are, and why they look for what they look for (EE-063)
+
+What a customer looks for depends on who the customer is. A consumer rarely looks up the founders. A clinic owner trusting a vendor with patient data often does. So the matrix has customer types, and each type says how much each item matters to it and why:
+
+- consumers, small-business owners, teams inside companies, enterprise buyers;
+- developers, regulated professionals, creators, public sector and nonprofits.
+
+The reasons are claims to test with the venture's own customers, not findings.
+
+- **The ICP.** It comes, in order of preference, from:
+  - the founder's own sentence;
+  - the venture's ICP record (`purpose/icp.json`);
+  - failing both, the home page's opening text, marked inferred.
+- **Placing the ICP.** Jev places the ICP into types. It answers "mainly" conservatively, so a type counts at 0.25 or more and within 0.6 of the strongest type.
+- **Several types at once.** A customer who is several types needs what the most demanding one needs.
+- **Evidence on every item.** Each item shows every audience's weight, the item's importance to that audience, and the reason. The rating can always be traced back to who the ICP is and why we think they look for it.
+
+## The sitemap
+
+The result is drawn as the site's sitemap. The home page sits on top, with the pages in its navigation in one band and the pages linked elsewhere (usually the footer) in another. Each page's own routes sit under it.
+
+- **Ratings.** Each route that was read is rated on the items that belong there. On the home page, that is what must be on the home page. On other pages, it is the items whose place is that page type.
+- **Suggested pages.** Dashed ghost routes are pages the venture's priorities call for and the site lacks, for example an investors page while raising.
+- **Route detail.** Click a route to see what belongs there, what is missing and why.
+
+## Where to run it
+
+- **Board:** `node interface/demo/board.mjs`, then `/site`. Paste a link, say who your customers are (optional), tick raising, hiring or contributors, and read the sitemap and its ratings.
+- **CLI:** `node interface/harness/site.mjs <url> [--venture <dir>] [--icp "<who your customers are>"] [--raising] [--hiring] [--contributors]`. With a venture, the result is saved to `operations/marketing/site-presence.json`, and the router command `operations/marketing/site` reads it back.
+
+## In reverse: planning the site from the venture (EE-064)
+
+`plan.mjs` uses the same matrix in the other direction. It reads the venture's records and plans the site. The plan says what is shown where, how (the MDX component), when, and for whom, with the reason for each.
+
+- **The product decides the audience.** A product's `offered_to` names the ICP profiles it is offered to, and `serves` names the profiles it reaches through them. In a partner-led (B2B2C) venture, the partners are the site's customers. A profile can say it is `reached_through` another and which buying-center roles it plays (Webster and Wind 1972, with the initiator added by Bonoma 1982).
+- **Services are already an offering type** on the product card (product, service, platform, content, marketplace), so services drive the site like any other product.
+- **Topics, not audiences.** Pages follow topics, because audience-based navigation tends to hurt usability (NN/g). An audience with content of its own (candidates, investors, contributors, press) gets its own page, and only while it is a priority. Otherwise the plan says when that page would appear.
+- **Each page lists its sections in order of need**, each with:
+  - the MDX component;
+  - the audiences and why;
+  - any condition;
+  - the internal record it draws on;
+  - the public variant a marketing agent writes, at `operations/marketing/content/<page>/<item>.mdx`.
+- **The public gate.** `../check-public.mjs` checks every content file before it can be published:
+  - it names the internal record it is a variant of, its audience, and whether it is published;
+  - a published file names the person who approved it;
+  - it copies no run of ten words from its internal record, apart from public fields.
+
+  This keeps internal content out of public pages and keeps generic text off them.
+- **The handoff (EE-065).** The plan, the content variants and the brand make up the marketing package. Marketing hands it to engineering, which builds the site and does not decide what goes where. Planning the sitemap and designing the site are separate agents.
+
+Run it with `node operations/marketing/site/plan.mjs <venture> [--raising] [--hiring] [--contributors] [--write]`, or from the board's /site page with "Plan from my venture".
+
+## What is not settled
+
+The matrix is a starting opinion. Where information belongs depends on the startup type, the product, the industry and who the venture courts. That includes how to become a contributor, whether the venture is hiring, and whether it is raising, which can sit on an about, investors, careers or community page.
+
+Next work, logged in EE-062:
+- research best practice and replace the matrix's guesses with sourced conventions;
+- rank several ICPs against each other (today they are one customer audience);
+- derive the recommended sitemap and the order a visitor meets information from those priorities, beyond suggested pages;
+- write skills and kits for organizing marketing content (MDX, EE-044);
+- draft missing marketing records from what the site already says.