@geraldmaron/construct 1.0.18 → 1.0.20

package/templates/docs/incident-report.md

@@ -3,44 +3,60 @@
 - **Incident ID**: {INC-NNNN}
 - **Date**: {YYYY-MM-DD}
 - **Severity**: SEV-1 | SEV-2 | SEV-3
-- **Duration**: {start} → {end} ({total})
-- **Authors**: {names}
+- **Duration**: {detection} → {all-clear} ({total}; time-to-detect {ttd}, time-to-mitigate {ttm})
+- **Authors**: {names — include everyone who responded}
 - **Status**: draft | final
 
+<!--
+Blameless postmortem. Describe systems and decisions, not people. Neutral, factual
+language — no dramatic or animated descriptions. Publish within days while detail is
+fresh, and share widely. See Google SRE postmortem culture:
+https://sre.google/workbook/postmortem-culture/
+-->
+
 ## Summary
-<!-- Two to four sentences. What happened, who was affected, how it was resolved. Blameless tone. -->
+<!-- Two to four sentences: what happened, who was affected, how it was resolved. Blameless tone. -->
+
+## Severity rationale
+<!-- Why this severity and not one higher or lower? State the criteria (user impact, data integrity, duration, blast radius). If it was reclassified mid-incident, say when and why. -->
 
 ## Impact
-<!-- Users affected, requests failed, revenue lost, data integrity consequences. Quantify. -->
+<!-- Quantify: users affected, requests failed, error rate, revenue, data-integrity consequences. "Unknown" is acceptable; a guess is not. -->
 
 ## Timeline
-<!-- Times in UTC. Key events: detection, diagnosis, mitigation, resolution, all-clear. One line per event. -->
+<!-- Times in UTC, one line per event. Mark the key transitions explicitly: detection, diagnosis, mitigation start, resolution, all-clear. The gaps between them are the response story. -->
 
-| Time (UTC) | Event |
-|------------|-------|
-| {HH:MM}    | {what happened or what was done} |
+| Time (UTC) | Event | Phase |
+|------------|-------|-------|
+| {HH:MM}    | {what happened or was done} | detection / diagnosis / mitigation / resolution |
+
+## Trigger
+<!-- The proximate cause — the specific change, event, or input that set the incident off (a deploy, a traffic spike, a dependency failure). Distinct from the root cause. -->
 
 ## Root cause
-<!-- The underlying cause, not just the proximate trigger. The five-whys, condensed. -->
+<!-- The underlying system condition that let the trigger cause harm. The five-whys, condensed. A root cause is a system/design gap, never a person. -->
 
 ## Contributing factors
-<!-- Conditions that made the incident possible, worse, or harder to resolve. Include process gaps, not just code. -->
+<!-- Conditions that made the incident possible, worse, or harder to resolve: missing alerts, brittle dependencies, process gaps, absent runbook. Not the root cause, but they shaped the outcome. -->
 
-## What went well
-<!-- Detection, response, communication, tooling. Keep this honest. -->
+## Mitigators
+<!-- What went right and reduced blast radius — a circuit breaker that tripped, a canary that caught it, a fast rollback. These are as instructive as the failures; preserve them. -->
 
-## What went poorly
-<!-- Be specific. Blameless, not blameless-to-the-point-of-vague. -->
+## Detection and response
+<!-- How was it detected (alert, customer report, dashboard)? Was detection fast enough? What slowed diagnosis or mitigation? Be specific and blameless. -->
 
-## Corrective actions
-<!-- Each action: owner, deadline, ticket link. Prefer systemic fixes over "be more careful". -->
+## Action items
+<!-- Each action: systemic fix preferred over "be more careful". Owner, priority, and tracking ID required. Priority: P0 (prevents recurrence, do now) → P2 (hardening). -->
 
-| Action | Owner | Deadline | Ticket |
-|--------|-------|----------|--------|
-| {what} | {who} | {date}   | {link} |
+| Action | Type (prevent/detect/mitigate) | Owner | Priority | Tracking |
+|--------|--------------------------------|-------|----------|----------|
+| {what} | {prevent/detect/mitigate}      | {who} | P0/P1/P2 | {bd or ticket} |
 
 ## Lessons learned
-<!-- What this incident revealed about the system or the organization. -->
+<!-- Organized by theme. What did this reveal about the system or the organization that generalizes beyond this incident? -->
+
+## Glossary
+<!-- Define domain-specific terms, service names, and acronyms used above so a reader outside the team can follow the report. -->
 
 ## References
-<!-- Logs, dashboards, traces, related incidents, PRs that caused or fixed the issue. -->
+<!-- Logs, dashboards, traces (with IDs preserved), related incidents, the PRs that caused and that fixed the issue. -->

package/templates/docs/prfaq.md

@@ -16,13 +16,13 @@ or directly from evidence, but it must not invent customer demand.
 <!-- Two or three paragraphs grounded in evidence. Explain the customer problem, why now, and what is missing today. -->
 
 ## Press release
-<!-- Write as if the capability has shipped. Focus on customer outcome, not implementation. -->
+<!-- Write as if the capability has shipped. Focus on customer outcome, not implementation. Include a spokesperson quote and a customer quote — mark a hypothetical quote as such; never invent an attributed one (rules/common/no-fabrication.md). -->
 
 ## External FAQ
 <!-- Customer-facing questions and answers. Keep answers concrete and honest about limits. -->
 
 ## Internal FAQ
-<!-- Questions from engineering, sales, support, security, finance, and leadership. Include unknowns as TBD with what would resolve them. -->
+<!-- Questions from engineering, sales, support, security, finance, and leadership. Include unknowns as TBD with what would resolve them. Cover the launch/success metrics: what target defines success and by when. -->
 
 ## Evidence appendix
 <!-- Source links, customer quotes, related issues, research, and PRDs. -->

package/templates/docs/product-intelligence-report.md

@@ -13,7 +13,7 @@ without becoming a backlog dump.
 <!-- Two or three paragraphs. What changed, what matters, and what decision should follow. -->
 
 ## Evidence base
-<!-- Summary of source types, coverage, recency, and known gaps. -->
+<!-- Source types, coverage, recency, and known gaps. Grade the evidence (rules/common/research.md §10); for community/sentiment sources note corroboration. Each theme below inherits the strength of the evidence under it — do not report a strong theme on weakly-graded sources. -->
 
 ## Themes
 <!-- Each theme should include evidence strength, affected personas, representative sources, and counter-signal. -->

package/templates/docs/research-brief.md

@@ -23,14 +23,16 @@
 
 ## Sources
 
-| Title / Path | Class | Date | URL | Verified | Relevance |
-|---|---|---|---|---|---|
-| {source title or file path} | primary / secondary / tertiary | {YYYY-MM-DD} | {URL or path} | yes / no / n/a | {one-line} |
+| Title / Path | Class | Reliability | Credibility | Date | URL | Verified | Relevance |
+|---|---|---|---|---|---|---|---|
+| {source title or file path} | primary / secondary / tertiary | A–F | 1–6 | {YYYY-MM-DD} | {URL or path} | yes / no / n/a | {one-line} |
 
-<!-- Class definitions:
-  - primary: peer-reviewed papers, official docs at exact version, raw source code, standards, company announcements, SEC filings
+<!-- Class is relative to the claim (rules/common/research.md §2): community/forum content is
+  primary for sentiment/experience claims, tertiary for factual ones.
+  - primary: peer-reviewed papers, official docs at exact version, raw source code, standards, company announcements, SEC filings; first-hand accounts for the attitude they express
   - secondary: changelogs, migration guides, tracked issues, maintainer posts, conference talks by authors
-  - tertiary: blog posts, forums, Q&A, analyst summaries: for discovery only, never as evidence
+  - tertiary: blog posts, forums, Q&A, analyst summaries: for factual claims, discovery only
+  Reliability (A–F) and Credibility (1–6) are the Admiralty grade (research.md §10); record both, e.g. B2.
   Mark Verified = yes only after fetching the URL and confirming content matches. -->
 
 ## Findings

package/templates/docs/research-finding.md

@@ -1,26 +1,51 @@
 ---
 kind: research-finding
 topic: "<short topic line>"
-confidence: inferred
+confidence: high | medium | low
 sources: []
 created: <ISO timestamp set by construct knowledge add>
-expiresAt: <ISO timestamp, default created + 90d>
+expiresAt: <ISO timestamp, default created + 90d; shorten for fast-moving topics>
 profile: <active profile id>
 ---
 
+<!--
+A lightweight but rigorous knowledge-store entry. Same evidence standard as a
+research brief, condensed: observation separated from inference, every finding
+cited, confidence tied to source grade, an explicit refresh trigger. See
+rules/common/research.md.
+-->
+
+## SOURCES
+
+| Title / Path | Class | Reliability | Credibility | Date | URL | Verified |
+|---|---|---|---|---|---|---|
+| {source} | primary / secondary / tertiary | A–F | 1–6 | {YYYY-MM-DD} | {url} | yes / no |
+
 ## FINDINGS
 
-- <Finding 1 with citation>
-- <Finding 2 with citation>
+<!-- Observation only: what the source states. Each finding cites a source row above. -->
+
+- <Finding 1 [source: …]>
+- <Finding 2 [source: …]>
 
 ## INFERENCES
 
-- <Inference labeled as such>
+<!-- What is concluded beyond what any single source says. Labeled as inference, not fact. -->
+
+- <Inference, with the findings it rests on>
+
+## CONFIDENCE
+
+<!-- high / medium / low, with the reasoning: tie it to the Admiralty grade of the sources (research.md §10). high only on A1/A2/B1. Name the strongest counter-evidence. -->
 
 ## GAPS
 
-- <What we could not confirm>
+- <What could not be confirmed and would change the conclusion if known>
 
 ## RECOMMENDATION
 
-- <Next action based on the evidence available>
+- <Next action based on the evidence available, and the threshold that would change it>
+
+## REFRESH
+
+<!-- When this finding should be re-verified: the expiresAt date, or the event that would invalidate it (a new release, a superseding paper). -->

package/templates/docs/rfc.md

@@ -22,7 +22,19 @@ contract, API, schema, or protocol consumed by other systems.
 <!-- What problem or limitation drives this proposal? Include evidence: incidents, performance data, support tickets, developer friction. Explain why the status quo is not acceptable. -->
 
 ## Proposed design
-<!-- The concrete proposal. Enough detail for reviewers to evaluate feasibility and tradeoffs. Diagrams, code sketches, and data models are appropriate here. -->
+<!-- The concrete proposal. Enough detail for reviewers to evaluate feasibility and tradeoffs. The sequence below shows the proposed behavior in context — include the happy path and at least one error path. -->
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant Service
+  participant Store
+  Client->>Service: request
+  Service->>Store: read or write
+  Store-->>Service: result
+  Service-->>Client: response
+  Note over Service,Store: error path — Store unavailable → Service returns degraded response
+```
 
 ## Tradeoffs and alternatives
 <!-- The other credible designs considered. For each: what it is, why it was not chosen, and under what conditions it would be preferred. No strawmen. -->

package/templates/docs/runbook.md

@@ -14,8 +14,27 @@
 ## Impact
 <!-- Who is affected and how badly. Data loss? Degraded performance? Complete outage? -->
 
+## Severity and response
+<!-- Map each severity to the response it triggers: page urgency, comms cadence, and error-budget consequence. A SEV-1 pages immediately and freezes related releases per the error-budget policy (https://sre.google/workbook/error-budget-policy/); a SEV-3 is handled in business hours. -->
+
+| Severity | Trigger condition | Page within | Comms | Error budget |
+|----------|-------------------|-------------|-------|--------------|
+| SEV-1 | {full outage / data loss / SLO breach} | 5 min | exec + status page | breach → freeze releases |
+| SEV-2 | {major degradation, workaround exists} | 15 min | team + stakeholders | partial spend |
+| SEV-3 | {minor / single-tenant / cosmetic} | business hours | team channel | none |
+
 ## Diagnostic steps
-<!-- Ordered checks from cheapest to most expensive. Each step: what to check, how to check it, what the answer means. -->
+<!-- Ordered checks from cheapest to most expensive. Each step: what to check, how to check it, what the answer means. Keep the decision tree below in sync with the steps. -->
+
+```mermaid
+flowchart TD
+  A[Alert fires] --> B{Error rate elevated?}
+  B -->|Yes| C[Check upstream dependency health]
+  B -->|No| D{User-visible impact?}
+  C --> E[Apply remediation]
+  D -->|Yes| C
+  D -->|No| F[Monitor and stand down]
+```
 
 ## Remediation
 <!-- The fix. Step-by-step, with exact commands or UI paths. Include expected output for each step. -->

package/templates/docs/signal-brief.md

@@ -13,7 +13,10 @@ without pretending the requirements are ready.
 <!-- One or two paragraphs. What appears to be happening, and where the signal came from. -->
 
 ## Evidence
-<!-- Cite the concrete notes, tickets, customer quotes, traces, or analytics that support the signal. -->
+<!-- Cite the concrete notes, tickets, customer quotes, traces, or analytics. Grade each source with its Admiralty reliability/credibility (rules/common/research.md §10); for community sources note corroboration and engagement. The signal strength above should follow from the grades, not precede them. -->
+
+## Counter-signal
+<!-- The strongest evidence against the signal, or its absence. A signal no one tried to disconfirm is weaker than it looks. -->
 
 ## Why it matters
 <!-- What product, customer, or business decision this could affect if the signal strengthens. -->

package/templates/docs/skill-artifact.md

@@ -1,9 +1,11 @@
 ---
 name: <verb-led-id>
 scope: "<one paragraph: what it covers, what it does not>"
-observable_outcome: <how someone outside the role tells this skill happened>
+observable_outcome: <how someone outside the role tells this skill happened — a concrete artifact, not "understands X">
+prerequisites:
+  - <skill-id or capability that must exist before this one is useful>
 provenance:
-  - <citation: post-mortem, public framework, competency model>
+  - <citation: post-mortem, public framework, competency model, with URL>
 roles:
   - <role-id that uses this skill>
 ---
@@ -12,16 +14,34 @@ roles:
 
 ## What this skill produces
 
-<Concrete output. Bloom-style: not "knows X" but "produces Y".>
+<Concrete output, Bloom-style: not "knows X" but "produces Y". Name the artifact and what makes it correct. Example: "a runbook whose diagnostic flowchart branches to a fix in ≤3 steps", not "understands incident response".>
 
 ## When to invoke it
 
-<Triggers. What the operator or the upstream persona is doing when this skill is the right call.>
+<Triggers. What the operator or upstream persona is doing when this skill is the right call. Include the signal that distinguishes it from adjacent skills.>
 
-## How it composes
+## Prerequisites and composition
 
-<Other skills typically chained before or after.>
+<What must be true or done first, and the skills typically chained before and after. A skill with unmet prerequisites produces confident-looking but wrong output.>
+
+## Competency rubric
+
+<What the skill looks like at each level. The author of an artifact should be able to place their work on this scale.>
+
+| Level | What it looks like |
+|-------|--------------------|
+| Novice | <produces the artifact but misses edge cases / evidence / failure paths> |
+| Competent | <covers the happy path and the common failure modes; cites sources> |
+| Expert | <anticipates the non-obvious failure, calibrates confidence, leaves the next person a reproducible trail> |
+
+## Failure modes
+
+<How this skill breaks when misapplied — distinct from anti-patterns. What does a wrong-but-plausible output look like, and what signal reveals it? When should the operator escalate or stop?>
 
 ## Anti-patterns
 
-<Ways this skill gets misapplied; what looks similar but is not this.>
+<Ways this skill gets misapplied; what looks similar but is not this skill.>
+
+## Worked example
+
+<A short, concrete instance: the trigger, the artifact produced, and why it meets the observable outcome. One real example removes more ambiguity than a page of guidance.>

package/templates/docs/strategy.md

@@ -15,8 +15,8 @@ Owning workflow: skills/docs/strategy-workflow.md.
 <!-- 1–3 sentences. Where are we going in 3–5 years? -->
 
 ## Bets
-<!-- Explicit choices. Each bet: what we're doing and why. -->
-- **Bet 1**: …
+<!-- Explicit choices. Each bet: what we're doing, why, the leading indicator that tells us early if it's working, and the kill criterion that ends it. A bet with no kill criterion is a belief, not a bet. -->
+- **Bet 1**: … **Why**: … **Leading indicator**: … **Kill criterion**: {what observation would make us stop}
 - **Bet 2**: …
 
 ## Non-bets
@@ -29,6 +29,27 @@ Owning workflow: skills/docs/strategy-workflow.md.
 ## North Star Metric
 <!-- Single measurable outcome. Format: Metric / Baseline / Target / Owner -->
 
+## Metrics
+<!-- The North Star is lagging. Name the leading indicators that move first and predict it, so a failing bet is visible before the lagging metric confirms it. -->
+
+| Metric | Type (leading/lagging) | Baseline | Target | Owner |
+|--------|------------------------|----------|--------|-------|
+| {name} | leading / lagging | {value} | {value} | {who} |
+
+## Milestones
+<!-- What must be true by when. Each milestone is a checkpoint that confirms or kills a bet. -->
+
+| Milestone | By when | Confirms / kills |
+|-----------|---------|------------------|
+| {what}    | {date}  | {which bet}      |
+
+## Risks
+<!-- What could invalidate the strategy. Risk register, not a worry list. -->
+
+| Risk | Likelihood | Impact | Mitigation / leading signal |
+|------|-----------|--------|------------------------------|
+| {what} | high/med/low | high/med/low | {response} |
+
 ## Competitive Positioning
 <!-- How we differentiate. 2–4 sentences. -->
 

package/lib/bootstrap/lazy-install.mjs

@@ -1,161 +0,0 @@
-/**
- * lib/bootstrap/lazy-install.mjs — on-demand resource installer with consent gating.
- *
- * When a runtime code path needs a resource that is not present, call
- * `lazyInstall(id)`. The function:
- *
- *   1. Reads cached operator consent from config.env (consent key set by the
- *      resource definition in `lib/bootstrap/resources.mjs`).
- *   2. If consent is 'never', returns { installed: false, fallback: <text> }
- *      without prompting or printing anything.
- *   3. If a TTY is available, prompts the user with the resource displayName,
- *      estimated download size, and [y/n/never].
- *   4. On 'y' or an existing 'yes' consent: calls resource.install(), waits
- *      for it to complete, updates config.env, and returns { installed: true }.
- *   5. On 'n': returns { installed: false, fallback: <text> } without saving.
- *   6. On 'never': writes 'never' to config.env and returns { installed: false }.
- *
- * Hooks that run without a TTY (most hook invocations) skip to step 2 and
- * use the fallback silently.
- *
- * Consent is cached per-resource in config.env so the prompt never repeats
- * across process restarts once the user has answered.
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import readline from 'node:readline';
-
-import { getResource, probeResource } from './resources.mjs';
-
-const CONFIG_ENV = path.join(os.homedir(), '.construct', 'config.env');
-
-function readConfigEnv() {
-  try {
-    return fs.readFileSync(CONFIG_ENV, 'utf8');
-  } catch {
-    return '';
-  }
-}
-
-function readConsentFromEnv(consentKey) {
-  const lines = readConfigEnv().split('\n');
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    const eq = trimmed.indexOf('=');
-    if (eq === -1) continue;
-    const k = trimmed.slice(0, eq).trim();
-    const v = trimmed.slice(eq + 1).trim().replace(/^['"]|['"]$/g, '');
-    if (k === consentKey) return v;
-  }
-  return null;
-}
-
-function writeConsentToEnv(consentKey, value) {
-  let content = readConfigEnv();
-  const regex = new RegExp(`^${consentKey}=.*$`, 'm');
-  const line = `${consentKey}=${value}`;
-  if (regex.test(content)) {
-    content = content.replace(regex, line);
-  } else {
-    content = content.trimEnd() + (content ? '\n' : '') + line + '\n';
-  }
-  fs.mkdirSync(path.dirname(CONFIG_ENV), { recursive: true });
-  fs.writeFileSync(CONFIG_ENV, content, { mode: 0o600 });
-}
-
-function hasTty() {
-  return Boolean(process.stdin.isTTY && process.stderr.isTTY);
-}
-
-function formatBytes(bytes) {
-  if (!bytes) return '';
-  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
-  return `${Math.round(bytes / (1024 * 1024))} MB`;
-}
-
-async function promptUser(question) {
-  return new Promise((resolve) => {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer.trim().toLowerCase());
-    });
-  });
-}
-
-/**
- * Attempt to install a resource lazily, respecting cached consent.
- *
- * @param {string} id - resource id from the registry
- * @param {object} [opts]
- * @param {boolean} [opts.silent] - skip TTY prompt, use cached consent only
- * @returns {{ installed: boolean, fallback?: string, error?: string }}
- */
-export async function lazyInstall(id, { silent = false } = {}) {
-  const resource = getResource(id);
-  if (!resource) {
-    return { installed: false, error: `unknown resource: ${id}` };
-  }
-
-  const probe = await probeResource(resource);
-  if (probe.present && probe.healthy) {
-    return { installed: true };
-  }
-
-  const { consentKey, displayName, downloadSize, fallback } = resource;
-  const fallbackMsg = typeof fallback === 'function' ? fallback() : (fallback || '');
-
-  const cached = readConsentFromEnv(consentKey);
-
-  if (cached === 'never') {
-    return { installed: false, fallback: fallbackMsg };
-  }
-
-  if (cached === 'yes') {
-    return await performInstall(resource, fallbackMsg);
-  }
-
-  if (silent || !hasTty()) {
-    return { installed: false, fallback: fallbackMsg };
-  }
-
-  const size = downloadSize ? ` (~${formatBytes(downloadSize)})` : '';
-  const answer = await promptUser(
-    `\n[construct] ${displayName} required${size}. Install now? [y/n/never] `
-  );
-
-  if (answer === 'y' || answer === 'yes') {
-    writeConsentToEnv(consentKey, 'yes');
-    return await performInstall(resource, fallbackMsg);
-  }
-
-  if (answer === 'never') {
-    writeConsentToEnv(consentKey, 'never');
-    process.stderr.write(
-      `[construct] "${displayName}" will not be prompted again. Using fallback: ${fallbackMsg}\n`
-    );
-    return { installed: false, fallback: fallbackMsg };
-  }
-
-  return { installed: false, fallback: fallbackMsg };
-}
-
-async function performInstall(resource, fallbackMsg) {
-  if (typeof resource.install !== 'function') {
-    return { installed: false, fallback: fallbackMsg, error: 'resource has no install()' };
-  }
-  try {
-    process.stderr.write(`[construct] Installing ${resource.displayName}...\n`);
-    const result = await resource.install();
-    if (result?.success) {
-      process.stderr.write(`[construct] ${resource.displayName} installed.\n`);
-      return { installed: true };
-    }
-    return { installed: false, fallback: fallbackMsg, error: result?.log };
-  } catch (err) {
-    return { installed: false, fallback: fallbackMsg, error: err?.message || String(err) };
-  }
-}