Vocabulary

The canonical glossary for the Canopy Method. Every methodology doc, every marketing-site page, every CLI prompt obeys this file. The custom regex CI check (scripts/check-vocabulary.cjs) enforces it.

If a term appears here as banned, do not use it in prose. If a concept needs a name, use the preferred term. Vocabulary drift is how methodologies die — Scrum became unrecognizable because its words lost their meaning. Canopy does not negotiate on its words.

Preferred Terms

Preferred Field Names

Canonical field names for method primitives. Every surface — DB schema, Zod validators in @canopy/shared, tRPC router, web UI, methodology docs, CLI prompts — uses these names. The cross-surface CI gate (npm run check:cross-surface) enforces presence on every surface.

DB and methodology docs use snake_case. TypeScript code uses camelCase of the same name. No surface invents an alias.

Outcome fields (Phase 12 / Phase 17)

Issue fields (Phase 12)

Milestone / Phase fields (Phase 12)

Outcome.kind enum values

feature, infra, compliance, content, research, refactor, performance, operations. Default: feature. See OUTCOMES.md ## Outcome.kind for full semantics + rendering matrix.

Outcome.blocked_on enum values

internal, external_party. Nullable (NULL when not blocked). See OUTCOMES.md ## Outcome.blocked_on.

Issue.diagnostic_state enum values

triage, investigating, likely_resolved, awaiting_evidence, misdiagnosed, not_our_bug. Default: triage. See BUGS.md ## diagnostic_state enum.

Invariant fields (Phase 13)

Invariant.scope enum values

workspace, project, clan_wide. Required. See INVARIANTS.md ### scope enum.

Invariant.enforcement enum values

compile, deploy, ai_verified, manual. Required. See INVARIANTS.md ### enforcement enum. Snake_case is canonical (Postgres enum constraint); the prose form AI-verified is acceptable in narrative text but DB / API / CLI use ai_verified.

Invariant.health_status enum values

passing, failing, unknown. Default: unknown. Computed, never user-set. See INVARIANTS.md ### health_status enum.

Initiative fields (Phase 14)

Initiative.status enum values

planning, active, paused, shipped, abandoned. Default: planning. See INITIATIVES.md ### status enum. The v7.0 spec (Phase 14 CONTEXT.md) refines the original 3-value enum (active / completed / cancelled) to this 5-value form to capture in-progress states (planning, paused) and use clearer ship-vs-abandon terminology. An Initiative does not move through Flow stages — the Outcomes inside it do.

LivingProcess fields (Phase 15)

LivingProcess.type enum values

agent, service, scheduler, webhook_handler, nexus. See LIVING-PROCESS.md ### type enum.

LivingProcess.current_state enum values

running, degraded, stopped, unknown. Default: unknown. See LIVING-PROCESS.md ### current_state enum. The v7.0 spec (Phase 15 CONTEXT.md) refines LIVING-PROCESS.md's original draft (running/stopped/restarting/crashed/unknown) to this 4-value form — degraded captures partial-failure operational signal more usefully than separate restarting/crashed states (those are usually transient and observable elsewhere).

LivingProcess.health_status enum values

healthy, warning, critical, unknown. Default: unknown. Computed from external monitoring (fed via recordHealthCheck). See LIVING-PROCESS.md ### health_status enum. The v7.0 spec (Phase 15 CONTEXT.md) refines LIVING-PROCESS.md's original draft (healthy/degraded/unhealthy/unknown) to the standard severity ladder (healthy / warning / critical / unknown) used by external monitoring tools (Grafana, Datadog), matching what operators read elsewhere.

CrossClanDependency fields (Phase 16)

CrossClanDependency.direction enum values

outgoing, incoming. See CROSS-CLAN.md ### direction enum. The same logical dependency lives in both clans with mirrored direction values — joined cross-clan by sync_id. outgoing = this workspace is the originator; incoming = another clan filed against us.

CrossClanDependency.state enum values

requested, in_progress_by_them, delivered, acked, done, cancelled, sync_failed. Default: requested. See CROSS-CLAN.md ### state enum. The v7.0 spec (Phase 16 CONTEXT.md) refines the original 5-state draft (REQUESTED → IN_PROGRESS_BY_THEM → DELIVERED → ACKED → DONE plus a separate sync_status enum) into a 7-state form with cancelled as an explicit terminal and sync_failed folded into the primary state machine as a first-class recoverable error. The FSM guard in @canopy/shared/src/utils/cross-clan-fsm.ts enforces legal transitions; done and cancelled are strictly terminal; sync_failed returns to a valid prior state on Retry Sync.

This section is the spec. When a future phase (13-17) adds a primitive, it extends this section with the new primitive's field table. The cross-surface CI gate (scripts/check-cross-surface-fields.cjs FIELDS_CONFIG) then scans every named field across every surface.

Banned Terms

Every banned term has a preferred Canopy equivalent and a one-line rationale. If the rule is wrong for your case, use the HTML comment ignore markers (see Exemption Rules). Do not silently break the rule.

| task | Outcome | Outcomes describe results; tasks describe actions. Different ontology. | | ticket | Issue | "Ticket" is Jira/Linear/Zendesk heritage; Canopy uses Issue. | | story | Outcome | Scrum heritage; Canopy does not have stories. | | user story | Outcome | Same as story. The "as a X I want Y" template is a writing crutch, not a primitive. | | epic | Initiative | Scrum heritage; Canopy uses Initiative for cross-cutting work. | | sprint | (no equivalent) | Canopy is continuous flow. There is no time-box. | | backlog | Later | "Backlog" implies infinite queue; Later is a deliberate priority. | | standup | Signal activity feed | Daily ceremonies cost more than they signal. The activity feed is async. | | stand-up | Signal activity feed | Same as standup. | | stand up | Signal activity feed | Same as standup. | | retro | Decision Log review | "Retro" is a Scrum ceremony. The Decision Log is the audit trail. | | retrospective | Decision Log review | Same as retro. | | velocity | throughput | Velocity invites comparison and gaming; throughput is just a count. | | story point | (no equivalent) | Canopy does not estimate effort. Lead time is the measurement. | | story points | (no equivalent) | Same. | | definition of done | success criteria | Per-Outcome success criteria replace a global definition of done. | | P0 | Now | Canopy uses Now/Next/Later. | | P1 | Now | Same. | | P2 | Next | Same. | | P3 | Later | Same. | | P4 | Later | Same. | | P5 | Later | Same. | | Critical | Now | Severity tiers collapse to Now/Next/Later. | | High | Now | Same. | | Medium | Next | Same. | | Low | Later | Same. | | awaiting-approval | awaiting_approval | Snake_case is canonical. Kebab-case drifts in. | | Awaiting Approval | awaiting_approval | Same. Title-case is for headings, not stage names. | | AwaitingApproval | awaiting_approval | Same. CamelCase is for type identifiers, not stage names. | | awaitingApproval | awaiting_approval | Same. | | value-add | (state the actual value) | "Value-add" is consultant filler. Name the actual value. | | low-hanging fruit | (name the actual work) | Consultant filler. Name the Outcome. | | synergy | (name the actual interaction) | Consultant filler. Describe what actually couples. | | deliverable | Outcome | "Deliverable" is consultant heritage; Canopy uses Outcome. |

Exemption Rules

Some legitimate uses require a banned term. Wrap them with ignore markers so the CI check skips the region. Two marker styles are supported:

Markdown / HTML — use in .md and .mdx files:

<!-- vocab-ignore-start -->
Anti-pattern: Build booking API → Customers can book appointments online
<!-- vocab-ignore-end -->

JS / TS / TSX — use in .ts and .tsx files where HTML comments are invalid:

/* vocab-ignore-start */
const painPoints = [
  { title: "Sprints waste time", desc: "..." },
];
/* vocab-ignore-end */

Two canonical exemption cases:

1. Anti-pattern callouts. The "❌ Build booking API → ✅ Customers can book appointments online" pattern in OUTCOMES.md needs to show the banned word ("Build booking API") in order to teach the rewrite. Wrap the bad-side examples.

2. Third-party tool names. When quoting "Jira ticket", "Linear issue", "Scrum sprint" as proper nouns referring to the external tool, wrap the quote. Do not silently rewrite proper nouns; just exempt them.

Fenced code blocks (```...```) are skipped automatically — literal code samples do not need vocabulary discipline.

Two files are self-exempt and never checked: VOCABULARY.md (contains the banned terms in the banned-terms column by design) and PORTFOLIO.md (may quote third-party tool names without ceremony).

How It's Enforced

A custom Node script (scripts/check-vocabulary.cjs) reads this file's ## Banned Terms table, derives a regex set, walks docs/methodology/ and apps/site/app/, and exits non-zero on hits. Run locally:

npm run check:vocab

The same script runs in CI as the docs↔site drift gate (one CI step, two purposes). If you add a new banned term and existing docs trip it, fix the docs in the same commit — the gate never ships broken to main.

No external linter (Vale, alex) — yet. The custom regex is sufficient for v1. When the rule set outgrows regex, revisit.

Adding a New Banned Term

1. Add a row to ## Banned Terms above. Include the preferred equivalent and a one-line "Why".
2. Ensure the preferred equivalent appears in ## Preferred Terms above. If it is a new concept, add it.
3. Run npm run check:vocab to verify no existing docs trip the new rule. If they do, fix them in the same commit. Do not land a banned-term addition with existing violations — the gate must stay green.

Source of truth: this file. If METHOD.md or any other doc contradicts what is here, this file wins for the vocabulary question. For methodology semantics, METHOD.md still wins.