hstack 0.16.0 → 0.18.0

package/template/templates/eslint-clean-code.mjs

@@ -0,0 +1,322 @@
+/**
+ * hstack — clean-code ESLint reference config.
+ *
+ * The mechanical half of `hstack/context/code-standards.md`: everything a
+ * linter can measure lives here, at `error`, so `lint` fails instead of
+ * warning. A `warn` is a message an agent learns to scroll past; an `error`
+ * is a message it has to act on. Nothing here is a style preference — each
+ * rule maps to a way agent-written code has actually gone wrong.
+ *
+ * Usage, from the consumer's `eslint.config.mjs`:
+ *
+ *   import { defineConfig } from 'eslint/config'
+ *   import { cleanCode } from './hstack/templates/eslint-clean-code.mjs'
+ *
+ *   export default defineConfig([
+ *     ...yourFrameworkConfig,          // e.g. eslint-config-next, which registers
+ *                                      // the @typescript-eslint and import plugins
+ *     ...cleanCode({
+ *       typescript: true,              // rules that need @typescript-eslint registered
+ *       imports: true,                 // rules that need eslint-plugin-import registered
+ *       supabase: true,                // the unread-`error` rule (see below)
+ *       modules: {
+ *         logger: 'lib/observability/logger',
+ *         config: 'lib/env',
+ *         dbClient: 'lib/supabase',
+ *       },
+ *     }),
+ *   ])
+ *
+ * The ratchet. Turning these on against an existing codebase fails `lint`
+ * hundreds of times at once. Freeze the current violations once —
+ *
+ *   npx eslint --suppress-all
+ *
+ * — which writes `eslint-suppressions.json`. From then on only *new*
+ * violations fail; touching a file that carries old ones is the moment to
+ * pay them down (`npx eslint --prune-suppressions` drops the entries that no
+ * longer apply). Commit the suppressions file. The count only goes down.
+ *
+ * This file is framework-owned: `hstack update` overwrites it. Adjust
+ * thresholds through the `thresholds` option, not by editing here.
+ */
+
+const DEFAULT_FILES = ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}']
+const DEFAULT_TEST_FILES = [
+  '**/*.test.{ts,tsx,js,jsx}',
+  '**/*.spec.{ts,tsx,js,jsx}',
+  '**/__tests__/**',
+  '**/e2e/**',
+]
+const DEFAULT_SCRIPT_FILES = ['scripts/**']
+
+const DEFAULT_THRESHOLDS = {
+  /** Lines per function, blank lines and comments excluded. */
+  functionLines: 60,
+  /** Lines per file, blank lines and comments excluded. */
+  fileLines: 400,
+  /** Independent paths through a function (if / for / && / ?: each add one). */
+  complexity: 15,
+  /** Nested blocks. Four is already a function that wants splitting. */
+  depth: 4,
+  /** Positional parameters. Past three, pass a named object. */
+  params: 3,
+  /** Nested callbacks. */
+  callbacks: 3,
+}
+
+/**
+ * Supabase returns `{ data, error }` and never throws. Code that takes `data`
+ * and ignores `error` reads as correct and fails silently — an RLS denial
+ * becomes an HTTP 200 that lies. This rule flags an awaited query-builder
+ * chain (`.from(…)`, `.rpc(…)`, `.storage.from(…)`) whose result is
+ * discarded, destructured without `error`, or read through `.data` only.
+ * Chaining `.throwOnError()` turns the result into an exception and satisfies
+ * the rule.
+ */
+const supabaseUnreadErrorRule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require the `error` half of a Supabase `{ data, error }` result to be read.',
+    },
+    schema: [],
+    messages: {
+      unreadError:
+        'The Supabase client never throws; it returns `{ data, error }`. Read `error` here ' +
+        '(or chain `.throwOnError()`). An unread error is a silent failure.',
+      discardedResult:
+        'The result of this Supabase call is discarded, so a failed write goes unnoticed. ' +
+        'Read `error` (or chain `.throwOnError()`).',
+    },
+  },
+  create(context) {
+    const QUERY_ROOTS = new Set(['from', 'rpc'])
+
+    /** Walks a call chain and reports whether it starts a Supabase query and whether it throws on error. */
+    function describeChain(node) {
+      let startsQuery = false
+      let throwsOnError = false
+      let current = node
+      while (current) {
+        if (current.type === 'CallExpression') {
+          const callee = current.callee
+          if (callee.type === 'MemberExpression' && callee.property.type === 'Identifier') {
+            if (QUERY_ROOTS.has(callee.property.name)) startsQuery = true
+            if (callee.property.name === 'throwOnError') throwsOnError = true
+          }
+          current = callee
+        } else if (current.type === 'MemberExpression') {
+          current = current.object
+        } else {
+          break
+        }
+      }
+      return { startsQuery, throwsOnError }
+    }
+
+    function patternReadsError(pattern) {
+      return pattern.properties.some(
+        (property) =>
+          property.type === 'RestElement' ||
+          (property.key && property.key.type === 'Identifier' && property.key.name === 'error'),
+      )
+    }
+
+    return {
+      AwaitExpression(node) {
+        const { startsQuery, throwsOnError } = describeChain(node.argument)
+        if (!startsQuery || throwsOnError) return
+
+        const parent = node.parent
+        if (parent.type === 'ExpressionStatement') {
+          context.report({ node, messageId: 'discardedResult' })
+          return
+        }
+        if (parent.type === 'VariableDeclarator' && parent.id.type === 'ObjectPattern') {
+          if (!patternReadsError(parent.id)) {
+            context.report({ node, messageId: 'unreadError' })
+          }
+          return
+        }
+        if (
+          parent.type === 'MemberExpression' &&
+          parent.object === node &&
+          parent.property.type === 'Identifier' &&
+          parent.property.name === 'data'
+        ) {
+          context.report({ node, messageId: 'unreadError' })
+        }
+      },
+    }
+  },
+}
+
+export const hstackPlugin = {
+  meta: { name: 'hstack', version: '1.0.0' },
+  rules: {
+    'supabase-unread-error': supabaseUnreadErrorRule,
+  },
+}
+
+/**
+ * @param {object} [options]
+ * @param {string[]} [options.files]        Files the rules apply to.
+ * @param {string[]} [options.testFiles]    Files where size rules are relaxed.
+ * @param {string[]} [options.scriptFiles]  Operator CLIs, where stdout is the interface.
+ * @param {boolean}  [options.typescript]   Emit rules that need `@typescript-eslint` registered. Default true.
+ * @param {boolean}  [options.imports]      Emit rules that need `eslint-plugin-import` registered. Default false.
+ * @param {boolean}  [options.supabase]     Emit the unread-`error` rule. Default false.
+ * @param {Partial<typeof DEFAULT_THRESHOLDS>} [options.thresholds]
+ * @param {object}   [options.modules]      Where the one sanctioned path for each concern lives; used in messages.
+ * @param {string}   [options.modules.logger]    e.g. 'lib/observability/logger'
+ * @param {string}   [options.modules.config]    e.g. 'lib/env'
+ * @param {string}   [options.modules.dbClient]  e.g. 'lib/supabase'
+ * @returns {object[]} Flat-config objects to spread into `defineConfig([...])`.
+ */
+export function cleanCode(options = {}) {
+  const files = options.files ?? DEFAULT_FILES
+  const testFiles = options.testFiles ?? DEFAULT_TEST_FILES
+  const scriptFiles = options.scriptFiles ?? DEFAULT_SCRIPT_FILES
+  const typescript = options.typescript ?? true
+  const imports = options.imports ?? false
+  const supabase = options.supabase ?? false
+  const t = { ...DEFAULT_THRESHOLDS, ...(options.thresholds ?? {}) }
+  const modules = options.modules ?? {}
+
+  const loggerHint = modules.logger ? ` Use ${modules.logger}.` : ' Use the repo logger.'
+  const configHint = modules.config
+    ? ` Read it through ${modules.config}, which validates every variable once at boot.`
+    : ' Read it through the one config module that validates every variable at boot.'
+  const dbClientHint = modules.dbClient
+    ? ` Get a client from ${modules.dbClient}; a client built elsewhere can bypass RLS.`
+    : ' Get a client from the one sanctioned module; a client built elsewhere can bypass RLS.'
+
+  const sizeAndShape = {
+    'max-lines-per-function': [
+      'error',
+      { max: t.functionLines, skipBlankLines: true, skipComments: true, IIFEs: true },
+    ],
+    'max-lines': ['error', { max: t.fileLines, skipBlankLines: true, skipComments: true }],
+    complexity: ['error', t.complexity],
+    'max-depth': ['error', t.depth],
+    'max-params': ['error', t.params],
+    'max-nested-callbacks': ['error', t.callbacks],
+  }
+
+  const errorsAreHandled = {
+    'no-empty': ['error', { allowEmptyCatch: false }],
+    'prefer-promise-reject-errors': 'error',
+    'no-throw-literal': 'error',
+  }
+
+  // `no-console` carries no custom message; when the consumer names a logger,
+  // the restricted-global form says where to go instead.
+  const consoleRules = modules.logger
+    ? {
+        'no-console': 'off',
+        'no-restricted-globals': [
+          'error',
+          { name: 'console', message: `Do not log through console.${loggerHint}` },
+        ],
+      }
+    : { 'no-console': ['error', { allow: [] }] }
+  const consoleOff = { 'no-console': 'off', 'no-restricted-globals': 'off' }
+
+  const onePathPerConcern = {
+    ...consoleRules,
+    'no-restricted-syntax': [
+      'error',
+      {
+        selector: "MemberExpression[object.name='process'][property.name='env']",
+        message: `Do not read process.env here.${configHint}`,
+      },
+    ],
+    'no-restricted-imports': [
+      'error',
+      {
+        paths: [
+          {
+            name: '@supabase/supabase-js',
+            message: `Do not import @supabase/supabase-js directly.${dbClientHint}`,
+          },
+        ],
+      },
+    ],
+  }
+
+  const deadCode = {
+    // The core rule is replaced by its type-aware twin when TypeScript is on.
+    'no-unused-vars': typescript ? 'off' : 'error',
+    'no-duplicate-imports': 'error',
+    'no-unreachable': 'error',
+    'no-useless-return': 'error',
+  }
+
+  const typescriptRules = typescript
+    ? {
+        '@typescript-eslint/no-unused-vars': [
+          'error',
+          { argsIgnorePattern: '^_', varsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' },
+        ],
+        '@typescript-eslint/no-explicit-any': 'error',
+        '@typescript-eslint/no-non-null-assertion': 'error',
+        '@typescript-eslint/consistent-type-imports': [
+          'error',
+          { prefer: 'type-imports', fixStyle: 'inline-type-imports' },
+        ],
+        // Type-aware: needs `parserOptions.projectService` (or `project`) set by the consumer.
+        '@typescript-eslint/no-floating-promises': 'error',
+        '@typescript-eslint/only-throw-error': 'error',
+      }
+    : {}
+
+  const importRules = imports ? { 'import/no-cycle': ['error', { maxDepth: Infinity }] } : {}
+
+  const supabaseRules = supabase ? { 'hstack/supabase-unread-error': 'error' } : {}
+
+  const configs = [
+    {
+      name: 'hstack/clean-code',
+      files,
+      ...(supabase ? { plugins: { hstack: hstackPlugin } } : {}),
+      rules: {
+        ...sizeAndShape,
+        ...errorsAreHandled,
+        ...onePathPerConcern,
+        ...deadCode,
+        ...typescriptRules,
+        ...importRules,
+        ...supabaseRules,
+      },
+    },
+    {
+      // A long test is a normal test, and a test file reads the environment to
+      // decide what it can run against.
+      name: 'hstack/clean-code/tests',
+      files: testFiles,
+      rules: {
+        'max-lines-per-function': 'off',
+        'max-lines': 'off',
+        'max-nested-callbacks': 'off',
+        'no-restricted-syntax': 'off',
+        ...(typescript ? { '@typescript-eslint/no-non-null-assertion': 'off' } : {}),
+      },
+    },
+    {
+      // Operator-run CLIs: stdout is the interface, and the process reads its
+      // own environment.
+      name: 'hstack/clean-code/scripts',
+      files: scriptFiles,
+      rules: {
+        ...consoleOff,
+        'no-restricted-syntax': 'off',
+      },
+    },
+  ]
+
+  return configs
+}
+
+export default cleanCode

package/template/templates/infrastructure.md

@@ -1,190 +1,96 @@
----
-id: infrastructure
-type: infrastructure
-status: drafted                        # drafted | current | needs-refresh | archived
-owner: <git-handle>
-last-quarterly-review: <YYYY-MM-DD>
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
----
+_Where things run, why the couplings are what they are, and the traps. Operational truth, not policy — read it before touching env, deploy or dependencies (kernel § Context docs), and update it in the PR that makes it wrong. An honest "we don't have this yet" is the right answer whenever it is the true one._
 
-_Operational truth about how the consuming repo's product runs. Truth-gathering, not policy — `threat-model.md` and `hardening-checklist.md` carry the policy. This file is what `security-reviewer`, `data-specialist`, and any future `infra-specialist` read to ground change-time review in the system's actual shape. Length norm: 600–1500 lines once filled; shorter is honest for pre-prod, longer is a smell. Every H2 below must be present (validator rule INF-01); the Unknowns section must be present even when empty (INF-02); the Blast-Radius Matrix must list at least one row when status moves to `current` (INF-03); no MCP server may be wired with always-on write capability against prod (INF-04); LLM-driven sessions with a write-capable MCP active must not read user-generated content in the same session (INF-05)._
+## Where things run
 
-## Hosting & Compute
+_One row per distinct runtime — app, edge functions, workers, cron, queue consumers. Names copied from the provider console, not paraphrased._
 
-_Where each runtime lives. Provider, region(s), service tier/plan, instance class or function memory. Names must match the cloud console exactly — copy them, do not paraphrase. One row per distinct runtime (app, edge functions, workers, cron, queue consumers)._
-
-| Runtime | Provider | Region(s) | Tier / Plan | Notes |
+| Runtime | Provider | Region(s) | Plan / tier | Notes |
 |---|---|---|---|---|
 | | | | | |
 
-## Networking
-
-_DNS provider and zone, custom domains, TLS/SSL provisioning, CDN / edge cache, load balancing, ingress rules. Note which records are managed in code (IaC) vs the provider console._
-
-- **DNS provider.**
-- **Domains in use.**
-- **TLS provisioning.**
-- **CDN / edge.**
-- **Load balancing.**
-- **Egress controls.**
+- **Domains, DNS, TLS, CDN.**
+- **Declared in code vs clicked in a console.** List the clicked resources explicitly — each one is a load-bearing piece of tribal knowledge.
 
-## Data Layer
+## Data & storage
 
-_Database hosting, connection pooling, backup cadence, point-in-time recovery window, read replicas, retention policy. Defers schema and RLS to `data-architecture.md`; this section is operational (where and how, not what)._
+_Operational only. Schema, tenancy and RLS live in `data-architecture.md`._
 
-- **Primary database.**
-- **Connection pooling.**
-- **Backups.**
-- **Point-in-time recovery.**
+- **Primary database** — host, plan, connection pooling.
+- **Backups** — cadence, retention, point-in-time-recovery window.
+- **Last restore drill** — date, and what it proved. An untested backup is a wish.
 - **Replicas / failover.**
-- **Retention.**
-- **Vector / search infrastructure.**
-
-## Storage
-
-_Object storage, file uploads, presigned-URL flows, lifecycle and retention. One row per bucket / container._
-
-| Bucket | Provider | Purpose | Public? | Lifecycle | Notes |
-|---|---|---|---|---|---|
-| | | | | | |
-
-## Secrets & Configuration
-
-_Where secrets live, how they are injected at runtime, rotation cadence, who has access. **The runbook for rotation lives in `incident-runbook.md`; this section names the system, not the steps.**_
-
-- **Secret store.**
-- **Injection mechanism.**
-- **Rotation cadence.**
-- **Access control.**
-- **Audit trail.**
-
-## Environment Separation
-
-_What dev, staging (if present), and production look like, and what differs between them. Data-promotion rules (does prod data ever flow downstream? if so, with what redaction?). Connection-string isolation. **Test-against-prod is a kernel-level forbidden tool; flag any violation here as tech-debt.**_
-
-- **Dev.**
-- **Staging.**
-- **Production.**
-- **Data-promotion rules.**
-- **Cross-environment guardrails.**
-
-## IaC Inventory
-
-_What infrastructure is declared in code vs configured by click in a console. Path to IaC files. Tool (Terraform, Pulumi, CDK, OpenTofu, Supabase migrations, GitHub Actions YAML, Dockerfile). Who can apply. **Click-configured infra is not forbidden, but every clicked resource is a load-bearing tribal-knowledge item; list each one explicitly so it can be promoted to IaC over time.**_
-
-| Resource | Source-of-truth | Path / location | Applier(s) | Notes |
-|---|---|---|---|---|
-| | | | | |
-
-## Deploy Pipeline
-
-_How code reaches each environment. References `ci-cd.md` for the build pipeline; this section captures the deploy half — promotion mechanics, rollout strategy (instant cutover, canary, blue/green), rollback procedure, who can trigger a deploy._
-
-- **Build → deploy handoff.**
-- **Promotion path.**
-- **Rollout strategy.**
-- **Rollback procedure.**
-- **Deploy authorization.**
-
-## Observability
+- **Vector or search infrastructure.**
+- **Buckets** — one line each: purpose, public or not, lifecycle.
 
-_Logs, metrics, traces, error tracking, uptime monitoring. Where each lives, retention window, who reads them. Alert routing — which alerts wake whom, on which channel. **An observability gap is a production-readiness gap; an honest "we don't have this yet" entry is the right answer when true.**_
+## Environments
 
-- **Logs.**
-- **Metrics.**
-- **Traces.**
-- **Error tracking.**
-- **Uptime monitoring.**
-- **Alert routing.**
-
-## Cost & Capacity
-
-_Current monthly spend per service (approximate is fine). Budget alerts. Scaling triggers and ceilings. Rate-limiting posture (per-route, per-tenant). **Cost is a security and reliability concern, not just a finance concern: an unbounded scale ceiling is a billing-DoS vector.**_
+_What dev, preview and production are, and what actually differs between them._
 
-| Service | Monthly spend (approx) | Budget alert at | Scale ceiling | Notes |
+| Environment | App URL | Database it points at | Seed data | Notes |
 |---|---|---|---|---|
 | | | | | |
 
-- **Rate limits.**
-- **Per-tenant quotas.**
+- **Source of truth for environment variables**, and how they are scoped per environment.
+- **Does production data ever flow downstream?** If so, with what redaction.
+- **Cross-environment guardrails.** Testing against production is a kernel-forbidden path; a violation found here is a tech-debt file, not a footnote.
 
-## Disaster Recovery
-
-_Recovery Point Objective (RPO) and Recovery Time Objective (RTO) targets per critical resource. Backup restore procedure (high level — full steps live in `incident-runbook.md`). Drill cadence — when was the last successful restore test, and when is the next scheduled. **An untested backup is a wish, not a recovery plan.**_
-
-| Resource | RPO target | RTO target | Last drill | Next drill |
-|---|---|---|---|---|
-| | | | | |
+## Secrets
 
-## Blast-Radius Matrix
+- **Where they live.** The one store that is authoritative.
+- **How they reach the runtime.**
+- **Who has access**, and how that is reviewed.
+- **Rotation** — cadence, and where the steps are written down.
 
-_Per critical resource: what depends on it, what dies if it dies, and who is notified. This is the table that `security-reviewer` reads when scoring an infra-surface change; it must list at least one row when status moves to `current` (INF-03)._
+## Deploy Pipeline
 
-| Resource | Depends on | What dies if this dies | Notification path | Mitigation |
-|---|---|---|---|---|
-| | | | | |
+_How code reaches production, and the exact commands `/hstack-promote` will look for here. A command left blank halts the promotion — which is the correct outcome, because guessing a production command is how the wrong project gets migrated._
 
-## Access & Change Control
+| What `/hstack-promote` needs | Command |
+|---|---|
+| Apply a pending migration to production | |
+| List deployments and their state | |
+| Smoke-test a specific deployment URL | |
+| Read production logs | |
+| Promote a deployment | |
+| Roll back to the previous deployment | |
 
-_Who has production console access per provider. MFA enforcement. Audit log location and retention. Deploy authorization — who can push to prod, who can apply IaC, who can rotate secrets. **The principle of least privilege applies here; list humans by name and access scope, not role abstractions.**_
+- **Promotion path.** How a merge becomes an unpromoted production build, and what promotes it. Auto-assignment of the production domain must be off for the staged flow to exist at all.
+- **Who may promote.**
+- **Rollback.** What re-promoting the previous deployment does and does not undo — migrations are additive, so they stay.
 
-| Human | Provider | Scope | MFA enforced | Last access review |
-|---|---|---|---|---|
-| | | | | |
+## Observability
 
-- **Audit log location.**
-- **Audit log retention.**
-- **Access review cadence.**
+_Where `/hstack-promote` looks in its post-promotion window, and where a daily glance happens._
 
-## MCP Access Policy
+- **Logs** — where, retention.
+- **Error tracking** — tool, project, who watches it.
+- **Uptime monitoring.**
+- **Alert routing** — which alert reaches whom, on which channel. "Nobody is paged" is an answer; write it down rather than implying one.
 
-_Which MCP servers are wired, where they point, what they can do. MCP access is a security boundary equivalent to the access token it carries — an LLM-driven session with tool access to a project-scoped token has the project's full blast radius. The kernel already forbids `service_role` Supabase keys and `supabase db push` / `db reset` against remote environments; MCP write access against prod is the analogous capability and follows the same rule. One row per MCP server per project it points at._
+## Couplings & gotchas
 
-| MCP server | Wired at | Points at | Access mode | Token storage | Rotation cadence | Notes |
-|---|---|---|---|---|---|---|
-| | | | | | | |
+_The section that earns this file. Everything a newcomer — human or agent — would otherwise learn by breaking production: a region that must match another region, a version pinned because the next one broke us, a service that must be deployed before another, a quota that bites at a specific hour._
 
-**Rule (INF-04).** No MCP server may be wired with write capability against the production project. Read-only mode (the server's `--read-only` flag or equivalent) is the floor for any MCP that points at prod. When a write-capable MCP must exist against prod for an operational reason (one-off migration applied through the MCP, e.g.), the row above carries a `--write-justified-by: <change-spec-id or ADR id>` note and the MCP is disabled by default — enabled only inside the named change window, then immediately disabled. Always-on write-capable prod MCPs are forbidden.
+-
 
-**Rule (INF-05).** Any LLM-driven session that has a write-capable MCP tool active must not, in the same session, read user-generated content from a tenant-scoped table. This is the prompt-injection mitigation: prevents stored content (customer support rows, webhook payloads, user-submitted fields) from steering the LLM into destructive tool calls. List each session pattern below — subagent name, Skill, or ad-hoc — and which side of this boundary it sits on.
+_External services this depends on at runtime. Criticality: `hard` = the product is down, `soft` = degraded, `optional` = no user impact._
 
-| Session pattern | Write-capable MCP tools active? | Reads tenant-scoped content? | Compliant? |
+| Provider | Purpose | Criticality | What happens when it is down |
 |---|---|---|---|
 | | | | |
 
-**Per-MCP detail.**
-
-- **Supabase MCP.** Dev project, staging project, production project — each on its own row. "Not wired" is an acceptable and often preferred value, especially for production.
-- **Other MCPs** (Notion, GitHub, Linear, Figma, Slack, etc.). Each with its own access scope, token location, rotation. Notion and Slack MCPs in particular often surface external user-generated content into the session — flag them explicitly under INF-05.
-
-## Compliance & Data Residency
-
-_Regions where customer data lives at rest. GDPR-relevant flows (subject-access, deletion, export). Encryption at rest and in transit per data class. SOC 2 readiness gaps (this is honest enumeration, not a claim of posture). **v1 hstack does not by itself deliver SOC 2 or GDPR posture; the kernel says so explicitly. This section catalogs the gap, it does not close it.**_
+## MCP access
 
-- **Data residency.**
-- **GDPR flows.**
-- **Encryption at rest.**
-- **Encryption in transit.**
-- **Known compliance gaps.**
+_Which MCP servers are wired, where they point, what they can do. An MCP is a security boundary equivalent to the token it carries: a session with a project-scoped token has that project's full blast radius. The rules — no write-capable MCP against production outside `/hstack-promote`, and no write-capable MCP active in a session that reads user-generated tenant-scoped content — belong to the kernel § Stop conditions. This table is the inventory those rules are applied to._
 
-## Third-party Dependencies
-
-_External SaaS the system depends on at runtime. One row per provider. Criticality reflects what happens if the provider is unavailable: `hard` = product is down, `soft` = degraded, `optional` = no user impact._
-
-| Provider | Purpose | Criticality | Contractual SLO | Failure-mode behavior |
+| MCP server | Points at | Access mode | Token storage | Notes |
 |---|---|---|---|---|
 | | | | | |
 
-## Known Gaps
-
-_Open tech-debt items pointing to infrastructure shortcomings. Each entry is a link to a `hstack/tech-debt/TD-NNNN-<slug>.md` file. This section is the bridge between the operational truth captured above and the workflow's tech-debt machinery — every honest gap surfaced during the interview should land as a TD via `/hstack:tech-debt-new --origin <change-id>`._
-
--
+_"Not wired" is an acceptable value, and often the preferred one for production._
 
-## Unknowns
+## Known gaps
 
-_Challenge prompt: what infrastructure dependency does the team not yet have a documented mitigation for? Name the dependency, name the failure mode, name the gap. This section must be present even when empty, to make the absence explicit (validator rule INF-02)._
+_What is missing or unknown, named rather than implied. A gap with a shape is a file under `hstack/tech-debt/`; link it here. A gap without one — a dependency whose failure mode nobody has thought through — is a line here until someone does._
 
 -

package/template/templates/roadmap.md

@@ -1,18 +1,12 @@
 ---
-id: roadmap
-type: roadmap
-status: drafted                        # drafted | current | needs-refresh | archived
-owner: <git-handle>
-source: local                          # local | rhizome — who owns the truth; when rhizome, local edits are refused and the sync is authoritative
-reviewed-on: <YYYY-MM-DD>              # planner treats the roadmap as stale beyond 90 days
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
+reviewed-on: <YYYY-MM-DD>              # past 90 days, treat this roadmap as stale rather than current
 ---
 
+_Advisory only, never a gate (kernel § Context docs). It informs one-way-door decisions and the Forecloses / Enables section of an ADR; it never decides whether a change ships._
+
 ## Now
 
-_What we are committed to shipping. During the MVP phase, Now IS the MVP scope. Each item: one product line, one architectural-implication line. Implications are proposed by app-architect / data-architect and confirmed by the engineer — vague fortune-telling ("might need to scale") is worse than absence._
+_What we are committed to shipping. Each item: one product line, one architectural-implication line. Vague fortune-telling ("might need to scale") is worse than absence._
 
 - <item> — **architectural implication:** <one line>
 
@@ -30,12 +24,12 @@ _Plausible futures. These influence one-way-door decisions ONLY — never day-to
 
 ## Not on the path
 
-_Explicit renouncements, with the reason. Absorbs the old "Deferred" list._
+_Explicit renouncements, with the reason._
 
 - <item> — <why not>
 
 ## Success criteria for the current horizon
 
-_Concrete observable indicators that Now is done and Next gets promoted. Bullets._
+_Concrete observable indicators that Now is done and Next gets promoted._
 
 -

package/template/templates/story.md

@@ -1,20 +1,14 @@
 ---
-id: <STORE>:<store-native-id>          # one of NOTION:<id> | LINEAR:<key> | GH:<num> | REPO:<slug>
+id: NOTION:<page-id>
 type: story
-status: drafted                        # drafted | ready | in-flight | shipped | archived
-owner: <git-handle>
-persona: <persona-id>                  # single persona id
-job-to-be-done: <one-sentence summary; mirrors section 1>
-success-metric: <how shipping is measured>
-linked-change-specs: []                # required non-empty when status: in-flight
-created: <YYYY-MM-DD>
-updated: <YYYY-MM-DD>
-schema-version: 1
+persona: <persona-slug>                # the persona this story is written from
+job-to-be-done: <one sentence; mirrors section 1>
+success-metric: <how we know shipping it worked>
 ---
 
 ## Who and Why
 
-_Persona id (pointer, not duplicated) and the job-to-be-done. 1–2 sentences._
+_The persona (pointer, not duplicated) and the job to be done. 1–2 sentences._
 
 ## What Shipping Looks Like
 
@@ -22,11 +16,11 @@ _What the user sees, does, feels. One paragraph, 3–5 sentences._
 
 ## Success Metric
 
-_Pointer to the `success-metric` frontmatter field with a one-sentence explanation of how it is measured._
+_The `success-metric` above, with one sentence on how it is measured._
 
 ## Edge Cases the User Cares About
 
-_Challenge prompt: what does the user notice if this ships but is slightly broken? 2–5 bullets._
+_Challenge: what does the user notice if this ships but is slightly broken? 2–5 bullets._
 
 -