@drafthq/draft 2.7.0

package/core/templates/guardrails.md

@@ -0,0 +1,143 @@
+---
+project: "{PROJECT_NAME}"
+module: "root"
+generated_by: "draft:init"
+generated_at: "{ISO_TIMESTAMP}"
+---
+
+# Guardrails
+
+| Field | Value |
+|-------|-------|
+| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
+| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
+| **Generated** | {ISO_TIMESTAMP} |
+| **Synced To** | `{FULL_SHA}` |
+
+---
+
+This file defines project-level guardrails and learned coding patterns. All quality commands (`/draft:bughunt`, `/draft:deep-review`, `/draft:review`) read this file and enforce its rules.
+
+- **Hard Guardrails** — Human-defined constraints. Violations are always flagged.
+- **Learned Conventions** — Auto-discovered patterns that are intentional. Quality commands skip these.
+- **Learned Anti-Patterns** — Auto-discovered patterns that are problematic. Quality commands always flag these.
+
+Run `/draft:learn` to scan the codebase and update learned patterns. Quality commands also update this file incrementally after each run.
+
+---
+
+## Hard Guardrails
+
+<!-- Hard constraints that must never be violated. Check [x] to enable enforcement. -->
+
+### Git & Version Control
+- [ ] No direct commits to main/master
+- [ ] No force push to shared branches
+- [ ] PR required for all changes
+
+### Code Quality
+- [ ] No console.log/print statements in production code
+- [ ] No commented-out code blocks
+- [ ] No TODO comments without linked issue
+
+### Security
+- [ ] No secrets/credentials in code
+- [ ] No disabled security checks without documented exception
+- [ ] Dependencies must pass security audit
+
+### Testing
+- [ ] Tests required before merge
+- [ ] No skipped tests without documented reason
+- [ ] Coverage must not decrease
+
+### C++/Systems — Object Lifecycle & Memory Safety
+<!-- From core/guardrails.md — C++ Hard Guardrails. Pre-checked for all C++ projects. -->
+- [x] G1.1: No temporary `.c_str()` in Printf-style trace APIs (dangling pointer)
+- [x] G1.2: No dangling references/pointers after object destruction
+- [x] G1.3: No capture-all-by-reference `[&]` in async lambdas
+- [x] G1.4: Every async functor must be wrapped with `callback_muter_`
+- [x] G1.5: Never wrap op's own `done_cb` in ClosureRunner when extracting result via raw pointer
+- [x] G1.6: ClosureRunner/CallbackMuter must be wrapped in correct order (`callback_muter_` first, then `cr_`)
+- [x] G1.7: Every async functor must be wrapped with `cr_`
+- [x] G1.8: No op member access after potential op destruction in loops
+- [x] G1.9: Always return immediately after `Finish()` — no code execution post-Finish
+- [x] G1.10: No unintended deep copies via `auto` (use `auto&` or `const auto&` for map lookups)
+- [x] G1.11: std::move discipline — always move expensive objects; never use after move
+- [x] G1.12: No `shared_ptr` binding to non-trivial objects (EventDriver holders) in callbacks
+
+### C++/Systems — Concurrency & Locking
+- [x] G2.1: No mutable operations under shared/read locks
+- [x] G2.2: Always release spinlock before invoking callbacks or `Finish()`
+- [x] G2.3: No expensive object destruction under spinlock protection
+- [x] G2.4: Never sacrifice locking correctness for performance optimization
+- [x] G2.5: No synchronous waits (`Trigger::Wait`) in async code paths
+
+### C++/Systems — Control Flow & Error Handling
+- [x] G3.1: Always `return` after `Finish()` in conditional blocks
+- [x] G3.2: CHECKs for internal consistency only — never for external input validation
+- [x] G3.3: No side-effecting expressions inside DCHECK
+- [x] G3.4: CHECK/DCHECK/LOG(DFATAL) selection per severity matrix
+
+### C++/Systems — Format & API Correctness
+- [x] G4.1: Printf format specifiers must match argument types
+- [x] G4.2: MemTracer Print vs Printf selection (lazy construction vs immediate materialization)
+- [x] G4.3: Use Maybe-prefixed MemTracer variants only when op may be finished
+- [x] G4.4: No string + integer (pointer arithmetic, not concatenation) — use `StringPrintf`
+- [x] G4.5: `boost::optional<bool>` tests presence, not value — use `*xx` or `.value_or()`
+
+### C++/Systems — GFlags & Runtime Configuration
+- [x] G5.1: Snapshot gflag values at op start — never depend on flag stability mid-op
+
+### C++/Systems — Performance
+- [x] G6.1: Avoid `ByteSize()` on proto objects in hot paths
+- [x] G6.2: Prefer repeated fields over map fields in proto for serialization-sensitive paths
+- [x] G6.3: No inline execution in `SpawnWorkersAndJoin` `done_cb`
+
+> Check the guardrails that apply to this project. Unchecked items are not enforced. Quality commands flag violations of checked guardrails only.
+> **C++/Systems guardrails** are pre-checked and enforced by default. See `core/guardrails.md` for full descriptions and fix guidance. Uncheck only if the project does not contain C++ code.
+
+---
+
+## Learned Conventions
+
+<!-- Auto-discovered coding patterns verified as intentional. Quality commands skip these. -->
+<!-- Each entry is added by /draft:learn or by quality commands during post-analysis. -->
+<!-- Format: pattern name, category, confidence, evidence, description. -->
+
+<!-- No learned conventions yet. Run /draft:learn or a quality command to discover patterns. -->
+
+---
+
+## Learned Anti-Patterns
+
+<!-- Auto-discovered patterns verified as problematic. Quality commands always flag these. -->
+<!-- Each entry is added by /draft:learn or by quality commands during post-analysis. -->
+<!-- Entry format:
+### [Anti-Pattern Name]
+- **Category:** security | reliability | performance | correctness | concurrency
+- **Severity:** critical | high | medium
+- **graph_severity:** critical | high | medium | low | unresolved (fanIn-derived; "unresolved" if no graph data)
+- **high_fanin_files:** `path/file.go` (fanIn:12) (omit if none meet fanIn ≥ 5)
+- **Evidence:** Found in N files — `path/file.ext:line`
+- **Discovered at:** YYYY-MM-DD
+- **Established at:** YYYY-MM-DD
+- **Last verified:** YYYY-MM-DD
+- **Last active:** YYYY-MM-DD
+- **Discovered by:** draft:[command] on YYYY-MM-DD
+- **Description:** [What the pattern is and why it's problematic]
+- **Suggested fix:** [Brief description of the correct approach]
+-->
+
+<!-- No learned anti-patterns yet. Run /draft:learn or a quality command to discover patterns. -->
+
+---
+
+## Pattern Promotion
+
+Learned patterns with `confidence: high` and consistent evidence across multiple quality runs are candidates for promotion:
+
+- **Convention → Accepted Pattern**: Promote to `tech-stack.md ## Accepted Patterns` for technology-level decisions
+- **Convention → Hard Guardrail**: Promote to Hard Guardrails above if the team wants enforcement
+- **Anti-Pattern → Hard Guardrail**: Promote to Hard Guardrails above for mandatory enforcement
+
+Run `/draft:learn promote` to review candidates.

package/core/templates/hld.md

@@ -0,0 +1,327 @@
+---
+project: "{PROJECT_NAME}"
+module: "root"
+track_id: "{TRACK_ID}"
+generated_by: "draft:decompose"
+generated_at: "{ISO_TIMESTAMP}"
+# Stable frontmatter only (WS-8). Ephemeral fields live in metadata.json
+# and render via <!-- META:<key> --> directives.
+links:
+  spec: "./spec.md"
+  plan: "./plan.md"
+  lld: "./lld.md"
+  project_architecture: "../../architecture.md"
+---
+
+# {TRACK_TITLE} — HLD
+
+**_TBD_author_** (_TBD_email_) <!-- REQUIRED -->
+
+**Status:** <!-- META:status --> <!-- REQUIRED -->
+
+> Track ID: `{TRACK_ID}` — generated by `draft:decompose`. Requirements live in [`./spec.md`](./spec.md); implementation tasks in [`./plan.md`](./plan.md); detailed design in [`./lld.md`](./lld.md). For project-wide architecture, see [`../../architecture.md`](../../architecture.md).
+
+## Scope <!-- OPTIONAL -->
+
+- **Includes:** <!-- META:scope_includes -->
+- **Excludes:** <!-- META:scope_excludes -->
+
+> Conflicts surfaced by `scripts/tools/check-scope-conflicts.sh`.
+
+---
+
+## Approvals
+
+> **Pre-fill:** Pulled from `spec.md` frontmatter `approvers.*`. Replace `{...}` with actual names; capture sign-off date and comments per row. Draft gates `git upload` on this table being populated for `criticality ∈ {high, mission-critical}` tracks.
+
+| Role | Approver | Date | Comments | <!-- REQUIRED for criticality ∈ {high, mission-critical} -->
+|------|----------|------|----------|
+| Technical Leads | _TBD_approver_tech_leads_ | _TBD_date_ | _TBD_comments_ |
+| Architecture Review Board | _TBD_approver_arb_ | _TBD_date_ | _TBD_comments_ |
+| Cloud Operations (For SaaS deployments) | _TBD_approver_cloudops_ | _TBD_date_ | _TBD_comments_ |
+| Quality Assurance (For on-prem services) | _TBD_approver_qa_ | _TBD_date_ | _TBD_comments_ |
+| Product Management | _TBD_approver_pm_ | _TBD_date_ | _TBD_comments_ |
+
+---
+
+## Table of Contents
+
+1. [Background](#background)
+2. [Requirements](#requirements)
+3. [High Level Design](#high-level-design)
+4. [Detailed Design](#detailed-design)
+5. [Dependencies](#dependencies)
+6. [Intellectual Property](#intellectual-property)
+7. [Checklist](#checklist)
+8. [Deployment](#deployment)
+9. [Observability](#observability)
+
+---
+
+## Background
+
+<Describe the background - current state, why>
+
+**Ideal Length:** ½ to 1 page
+
+> **Source:** auto-pulled from `spec.md` §Problem Statement and §Background & Why Now. Tighten as needed for HLD audience.
+
+---
+
+## Requirements
+
+> **Source:** [`./spec.md`](./spec.md) is the requirements scorecard. Do not duplicate content here — link to the spec sections.
+
+- **Blackbox (feature/service-level) requirements:** see [`./spec.md` §Requirements / Functional](./spec.md#requirements)
+- **Whitebox (technical, per-component) requirements:** see [`./lld.md` §Requirements](./lld.md#requirements)
+- **Acceptance Criteria:** see [`./spec.md` §Acceptance Criteria](./spec.md#acceptance-criteria)
+- **Non-Functional Requirements:** see [`./spec.md` §Requirements / Non-Functional](./spec.md#requirements)
+
+<If requirements warrant changes in UX or a new UX, include UX mock here>
+
+---
+
+## High Level Design
+
+### Architecture
+
+**Primary goal:** Explain various components and their interactions at a very high level
+
+<!-- GRAPH:track-component-diagram:START -->
+<!-- Rendered by draft:decompose Step 5a from track module set + integration edges.
+     Mermaid flowchart TD with three subgraphs: Track (modules in scope),
+     Existing (existing modules this track touches), External (DB/queue/3P APIs).
+     Edges labeled with transport (HTTP, RPC, queue, direct call) when non-obvious. -->
+<!-- GRAPH:track-component-diagram:END -->
+
+**Architecture narrative** (≤300 words). Explain how the blackbox requirements are translated into the architecture — name the architectural style (hexagonal / layered / pipeline / event-driven), justify from observable evidence, and call out the dominant interaction pattern (sync RPC, async event, batch).
+
+### UI Architecture Changes
+
+**Primary goal:** Explain UI changes necessary for the feature / service
+
+- Is it MFE based, or is factored into existing service UI?
+- Are there changes to the UI infra libraries, components?
+- Tradeoffs between implementing business logic in backend vs UI
+
+_If no UI changes: write `N/A — backend-only track.`_
+
+### Key Design Decisions
+
+<Discuss key design choices. This is a summary of the design choices in the architecture>
+
+- **Decision 1:** {one-sentence statement} — _Why:_ {observable constraint, not aesthetic}
+- **Decision 2:** {one-sentence statement} — _Why:_ {observable constraint, not aesthetic}
+
+### Alternatives Considered
+
+<Alternative architectures and design choices considered and reasons for decisions>
+
+| Alternative | Rejected Because | promote_to_adr | <!-- REQUIRED -->
+|-------------|------------------|----------------|
+| _TBD_alt_1_ | _TBD_alt_1_reason_ | _TBD_alt_1_promote_to_adr_ (yes / no — if yes, run `/draft:adr`) |
+
+#### Notes for HLD Sections
+
+- Try not to use examples to illustrate the design here
+- Don't include detailed design aspects here (e.g. Sequence diagrams for workflows — those go in [`./lld.md`](./lld.md))
+
+---
+
+## Detailed Design
+
+### Component Level Design
+
+**Primary goal:** Zoom into each component and explain its design in detail
+
+<!-- GRAPH:track-component-table:START -->
+<!-- Rendered by draft:decompose Step 5a — one row per module in scope.
+     Columns: Module, Status (New/Modified/Existing), Files, Public API count,
+     Fan-In, Fan-Out, Complexity, Primary Deps, concurrency_model,
+     aggregate_resource_cap, parallel_flag_interaction, Citation. -->
+<!-- WS-7 required columns: concurrency_model, aggregate_resource_cap,
+     parallel_flag_interaction. Use "n/a" when truly inapplicable. -->
+<!-- GRAPH:track-component-table:END -->
+
+For each component, populate one subsection:
+
+#### [Component Name]
+
+**Responsibility:** {one sentence — what this module owns}
+**Status:** `New` | `Modified` | `Existing`
+**Entry point:** `{path:line}` → `{symbol}`
+**Public API:** see [`./lld.md` §Classes and Interfaces — {component}](./lld.md#classes-and-interfaces)
+**Whitebox requirements addressed:** {list AC IDs from spec.md} <!-- back-link to discovery.md Hotspot rows -->
+**Discovery hotspots addressed:** {list Hotspot-row IDs from `./discovery.md`} <!-- REQUIRED -->
+
+**Design notes** (≤200 words). How this component translates whitebox requirements into structure. Cite `path:line` for non-obvious decisions.
+
+#### Key Design Decisions
+
+<Discuss key design choices that are relevant at the component level>
+
+#### Alternatives Considered
+
+<Alternative designs considered for the component if any, and reasons for decisions>
+
+#### Notes for Detailed Sections
+
+- Include APIs, sequence diagrams for important workflows in the components — sequence diagrams live in [`./lld.md` §Key Algorithms and Workflows](./lld.md#key-algorithms-and-workflows)
+- Don't include data structures, protobuf definitions, class level interfaces here (they belong in [`./lld.md`](./lld.md))
+
+---
+
+## Dependencies
+
+<Identify all components dependent on your design proposal. It is important to review this list to identify alternatives, which would minimize/eliminate the impact to other components. It is also important to highlight this list during the design review discussion to raise awareness of the dependent component changes that need to be planned.>
+
+<!-- GRAPH:track-dependencies:START -->
+<!-- Rendered by draft:decompose Step 5a from cross-module integration edges.
+     Columns: Dependent Component, Edge Kind (call/import/event/shared-schema),
+     Impact Assessment (Small/Medium/Large), Description, Citation. -->
+<!-- GRAPH:track-dependencies:END -->
+
+| Dependent Component | Impact Assessment | Description | Citation |
+|---|---|---|---|
+| [Component Name] | Small / Medium / Large | Detailed description of the impacted functionality. | `path:line` |
+
+---
+
+## Intellectual Property
+
+### Inventions
+
+Provide a brief list and summary of all inventions associated with the proposed design.
+
+1. 
+2. 
+3. 
+
+**Were Invention Disclosure Forms (IDFs) submitted for the inventions listed?**
+
+- [ ] Yes
+- [ ] No
+
+> If No, submit an Invention Disclosure Form through your company's standard IP process.
+
+### Third Party Technology (TPT)
+
+**TPT includes:**
+- **Open Source Software (OSS):** Software licensed under an Open Source License (e.g., MIT, BSD, GPL, Apache)
+- **Commercial (non-OSS) Technology:** Non- software, documentation, content, APIs, SDKs, logos, artwork, data, GUIs, Tools, databases, and other intellectual property NOT licensed under an Open Source License
+
+#### List All NEW TPT Used
+
+| TPT | Where/How? |
+|---|---|
+| | |
+
+**Note:** As noted in the TPT Policy, prior to downloading/onboarding any new TPT, you must do the following:
+
+1. **For all new OSS:**
+   - Document the license and usage. Follow your organization's legal and security review process for Open Source.
+
+2. **For all new Commercial TPT:**
+   - Follow your organization's procurement and legal review process before onboarding any commercial technology or non-open-source assets.
+
+---
+
+## Checklist
+
+> **Draft integration:** `/draft:deploy-checklist` validates each row below is populated before allowing deploy of `criticality ∈ {high, mission-critical}` tracks.
+
+### Performance <!-- REQUIRED -->
+
+- Describe request QPS and 95th percentile latency
+
+| Budget | Value | Baseline source | <!-- REQUIRED -->
+|--------|-------|-----------------|
+| p50 latency | _TBD_p50_ | _TBD_p50_baseline_ |
+| p95 latency | _TBD_p95_ | _TBD_p95_baseline_ |
+| p99 latency | _TBD_p99_ | _TBD_p99_baseline_ |
+| Throughput target | _TBD_throughput_ | _TBD_throughput_baseline_ |
+| Resource budget (CPU / RAM / IO) | _TBD_resource_budget_ | _TBD_resource_baseline_ |
+
+### Scale <!-- REQUIRED -->
+
+- Does the service scale horizontally? What are the metrics used for this?
+- Is vertical scaling required?
+- Are there fundamental scaling bottlenecks? (e.g., single leader doing unbounded work)
+
+### Security <!-- REQUIRED -->
+
+- How are credentials protected?
+- Are there any firewall / ports implications?
+- Is there any resource level RBAC needed for this feature / service?
+- Are there any certificate management implications? (e.g., manual deployment etc.)
+- Is customer data protected with encryption?
+
+### Resiliency <!-- REQUIRED -->
+
+- Describe the kind and number of failures that may cause service unavailability
+- How is graceful degradation on a fault handled?
+
+### Multi-tenancy <!-- REQUIRED -->
+
+- Is the data / metadata isolated across tenants? In other words, even if datastore is shared, query correctness / partitioning should ensure no leaks should happen
+- Can the tenants expect predictable performance regardless of other tenants' workloads?
+- Can the data and state (config and runtime) of a tenant be migrated?
+
+### Upgrade <!-- REQUIRED -->
+
+- Is there any breakage in backward compatibility in API or data model?
+- What are the dependent services that need to be upgraded prior to this? (e.g., in SaaS, this service upgrade depends on a new ElasticSearch manager service version)
+- Does the impact of changes go beyond the upgraded cluster / service instance? (e.g., if this is a cluster change, will it break reporting or remote replication)
+
+### Flags and Controlled Rollout of Features <!-- REQUIRED -->
+
+- Does this change the persistent state? If yes, describe the flags used to protect the change
+- Is the feature going to be rolled out in a controlled manner? If yes, describe the targets and the feature flags here
+
+| Field | Value | <!-- REQUIRED -->
+|-------|-------|
+| `flag_name` | _TBD_flag_name_ |
+| `cluster_feature_gate` | _TBD_cluster_feature_gate_ |
+| `kill_switch_test_id` | _TBD_kill_switch_test_id_ |
+| `runbook_link` | _TBD_runbook_link_ |
+| `sunset_criteria` | _TBD_sunset_criteria_ |
+
+### Cost Implications <!-- REQUIRED -->
+
+*Primarily for SaaS deployments*
+
+- Include cloud cost calculation here
+- Is there any cost to the customer for cloud workloads?
+- Is there any sizing impact?
+
+---
+
+## Pre-Deploy Validation <!-- REQUIRED -->
+
+`scripts/tools/check-track-hygiene.sh` → hygiene clean
+`scripts/tools/verify-citations.sh` → citations clean (±5 lines tolerance)
+`scripts/tools/verify-doc-anchors.sh` → anchors and §-refs resolve
+`scripts/tools/check-graph-usage-report.sh` → Graph Usage Report present
+`scripts/tools/check-scope-conflicts.sh` → no overlap with adjacent tracks
+`scripts/tools/diff-templates-vs-tracks.sh` → no schema drift
+
+Result stored in `metadata.json:pre_deploy_status`
+(`unrun` / `passing` / `failing` / `bypassed`). Deploy is blocked unless
+`passing`.
+
+---
+
+## Deployment
+
+- Is there any dependency on the platform where this is deployed?
+  - For DP: on-prem vs customer managed cloud vs SaaS vs Services running in the cloud
+  - For CP: self managed on-prem vs SaaS vs IBM cloud
+
+---
+
+## Observability
+
+- List down the key metrics (don't list all metrics) that SREs need to look at to identify issues
+- List down alerting thresholds on those metrics
+
+> Per-component metrics + alert threshold tables live in [`./lld.md` §Observability](./lld.md#observability).