@hanmariyang/drafting 1.6.2

package/api/dist/lib/handoff.js

@@ -0,0 +1,283 @@
+// Development handoff = a COMPILED deliverable (§6). Gate: the lint set (E+W
+// minus waived) must be empty. The skeleton (scope/reqs/features/screens/
+// non-scope) is deterministic; only the §1 summary is AI-generated and it comes
+// in as a proposal (accept to confirm). Handoff is a `documents` row of a new
+// type 'handoff', so the existing section editor + export/share are reused.
+import * as repo from "../db/repos.js";
+import { resolveProvider } from "../providers/index.js";
+import { getModelConfig } from "./ai.js";
+import { effectiveViolations } from "./lint-service.js";
+export class HandoffGateError extends Error {
+    violations;
+    constructor(violations) {
+        super('정합성 검사 위반이 남아 있어 지시서를 생성할 수 없습니다.');
+        this.name = 'HandoffGateError';
+        this.violations = violations;
+    }
+}
+function meta(i) {
+    try {
+        return JSON.parse(i.meta || '{}');
+    }
+    catch {
+        return {};
+    }
+}
+export function getHandoffDoc(projectId) {
+    return repo.listDocuments(projectId).find((d) => d.type === 'handoff') ?? null;
+}
+/** Build the deterministic handoff body from a project's ACCEPTED items. */
+export function compileHandoffBody(projectId) {
+    const project = repo.getProject(projectId);
+    const items = repo.listProjectItems(projectId).filter((i) => i.status === 'accepted');
+    const reqs = repo.reqIdsForProject(projectId);
+    const features = items.filter((i) => i.kind === 'feature');
+    const groups = items.filter((i) => i.kind === 'feature-group');
+    const pages = items.filter((i) => i.kind === 'page');
+    const flows = items.filter((i) => i.kind === 'flow');
+    const p0 = features.filter((f) => meta(f).priority === 'P0').length;
+    const p1 = features.filter((f) => meta(f).priority === 'P1').length;
+    const p2 = features.filter((f) => meta(f).priority === 'P2').length;
+    const groupRefs = groups.map((g) => g.ref_id);
+    const scope = `**${project?.name ?? '프로젝트'}** — 수락된 기능 ${features.length}개를 구현한다.\n\n` +
+        `범위: ${groupRefs.join(' · ') || '—'} (P0 ${p0} · P1 ${p1} · P2 ${p2}).`;
+    const reqsBody = reqs.length
+        ? reqs.map((r) => `- ${r.id} ${r.heading}`).join('\n')
+        : '- (PRD 수락 섹션 없음)';
+    const featuresBody = features.length
+        ? features
+            .map((f) => {
+            const m = meta(f);
+            const crit = f.body.split('\n').map((l) => l.replace(/^[·\-*]\s*/, '').trim()).filter(Boolean)[0];
+            const links = [...(m.links?.reqs ?? []), ...(m.links?.flows ?? [])].join(', ');
+            return `- ${f.ref_id} ${f.title} (${m.priority ?? 'P?'}${links ? ' · ' + links : ''})` +
+                (crit ? `\n  - 수용 기준: ${crit}` : '');
+        })
+            .join('\n')
+        : '- (수락된 기능 없음)';
+    const screens = pages.length
+        ? pages
+            .map((pg) => {
+            const m = meta(pg);
+            return `- ${pg.ref_id} ${pg.title} [${m.page_type ?? 'GENERIC'}] · 기능 ${(m.links?.features ?? []).join(', ') || '—'}`;
+        })
+            .join('\n') +
+            '\n\n플로우:\n' +
+            (flows.length ? flows.map((fl) => `- ${fl.ref_id} ${fl.title}`).join('\n') : '- (없음)')
+        : '- (화면 없음)';
+    const nonScope = 'PRD 비범위 항목은 이번 지시서에서 제외한다. 수락하지 않은 항목은 지시서에 없습니다.';
+    const summaryPrompt = `아래 스코프를 한 문단으로 요약하는 개요 문장을 한국어로 써라. 섹션 제목: 개요\n\n${scope}\n\n` +
+        `요구 ${reqs.length}개, 기능 ${features.length}개, 화면 ${pages.length}개, 플로우 ${flows.length}개.`;
+    return { scope, reqs: reqsBody, features: featuresBody, screens, nonScope, summaryPrompt };
+}
+/**
+ * 개발 티켓(GitHub-flavored 체크리스트) — 수락된 기능 하나 = 티켓, 수용 기준 = 체크박스.
+ * 게이트와 무관하게 언제든 내보낼 수 있다(현재 수락분의 실행 목록).
+ */
+export function handoffTickets(projectId) {
+    const project = repo.getProject(projectId);
+    const items = repo.listProjectItems(projectId).filter((i) => i.status === 'accepted');
+    const groups = items.filter((i) => i.kind === 'feature-group');
+    const features = items.filter((i) => i.kind === 'feature');
+    const lines = [
+        `# ${project?.name ?? '프로젝트'} — 개발 티켓`,
+        '',
+        `> 수락된 기능 ${features.length}개. 각 기능 = 티켓, 수용 기준 = 체크리스트.`,
+        '',
+    ];
+    const ticketFor = (f) => {
+        const m = meta(f);
+        const pri = m.priority ?? 'P?';
+        const links = [...(m.links?.reqs ?? []), ...(m.links?.pages ?? []), ...(m.links?.flows ?? [])];
+        lines.push(`### ${f.ref_id} ${f.title}  \`${pri}\``);
+        if (links.length)
+            lines.push(`연결: ${links.join(' · ')}`);
+        const crit = f.body.split('\n').map((l) => l.replace(/^[·\-*]\s*/, '').trim()).filter(Boolean);
+        if (crit.length) {
+            lines.push('', '수용 기준:');
+            for (const c of crit)
+                lines.push(`- [ ] ${c}`);
+        }
+        lines.push('');
+    };
+    for (const g of groups) {
+        const feats = features.filter((f) => f.parent_id === g.id);
+        if (!feats.length)
+            continue;
+        lines.push(`## ${g.ref_id} ${g.title}`, '');
+        for (const f of feats)
+            ticketFor(f);
+    }
+    const orphans = features.filter((f) => !groups.some((g) => g.id === f.parent_id));
+    if (orphans.length) {
+        lines.push('## 기타 기능', '');
+        for (const f of orphans)
+            ticketFor(f);
+    }
+    if (features.length === 0)
+        lines.push('_(수락된 기능이 없습니다. 기능명세에서 수락 후 다시 내보내세요.)_', '');
+    return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+/**
+ * Compile (or recompile) the handoff document for a project. Throws
+ * HandoffGateError (→ 409) if the effective lint set is non-empty. The §1 개요
+ * section is AI-generated and left 'proposed' with an 'add' suggestion; the rest
+ * of the deterministic skeleton is written directly as 'accepted'.
+ */
+export async function compileHandoff(projectId) {
+    const violations = effectiveViolations(projectId);
+    if (violations.length > 0)
+        throw new HandoffGateError(violations);
+    const body = compileHandoffBody(projectId);
+    // one AI summary sentence (proposal). Stub-capable (no network).
+    const cfg = getModelConfig('handoff');
+    const provider = resolveProvider(cfg.provider);
+    let summary = '';
+    try {
+        for await (const delta of provider.streamChat({
+            model: cfg.model,
+            maxTokens: cfg.maxTokens,
+            messages: [
+                { role: 'system', content: '개발 지시서의 개요 문단만 간결히 쓴다. 한국어.' },
+                { role: 'user', content: body.summaryPrompt },
+            ],
+        })) {
+            summary += delta;
+        }
+    }
+    catch {
+        summary = body.scope;
+    }
+    let doc = getHandoffDoc(projectId);
+    if (!doc)
+        doc = repo.createDocument({ projectId, type: 'handoff', title: '개발 지시서' });
+    // rebuild sections deterministically; §1 개요 is a fresh proposal
+    repo.replaceSections(doc.id, [
+        { heading: '§1 개요', body: summary.trim() || body.scope },
+        { heading: '§2 스코프', body: body.scope },
+        { heading: '§3 요구 (REQ)', body: body.reqs },
+        { heading: '§4 기능 목록', body: body.features },
+        { heading: '§5 화면 · 플로우', body: body.screens },
+        { heading: '§6 비범위', body: body.nonScope },
+    ], 'accepted');
+    // §1 개요 back to proposed (the only AI-authored part) + a proposal card
+    const sections = repo.listSections(doc.id);
+    const overview = sections[0];
+    repo.setSectionStatus(overview.id, 'proposed');
+    repo.createSuggestion({
+        documentId: doc.id,
+        sectionId: overview.id,
+        kind: 'add',
+        title: '지시서 초안 v1',
+        body: '검사를 통과해 지시서를 컴파일했어요. 개요를 수락하면 지시서가 확정됩니다.',
+        quoteAfter: overview.body,
+        source: '수락분 컴파일',
+    });
+    repo.setDocumentStatus(doc.id, 'ready');
+    return { documentId: doc.id };
+}
+/**
+ * Prompt pack for agent hand-off (§6 출구 ①): the full handoff (accepted
+ * sections only) with an "implement only accepted items" header. Markdown.
+ */
+/**
+ * AI 코딩 에이전트가 바로 실행 가능한 발주서. 지시서 섹션 덤프가 아니라, 수락된 항목에서
+ * 역할·요구·기능(수용 기준 체크박스)·화면·플로우·비범위·작업 순서를 구조적으로 조립한다.
+ */
+export function promptPack(projectId) {
+    const doc = getHandoffDoc(projectId);
+    if (!doc)
+        return '# 개발 지시서\n\n아직 컴파일되지 않았습니다. 정합성 검사를 통과한 뒤 생성하세요.\n';
+    const project = repo.getProject(projectId);
+    const items = repo.listProjectItems(projectId).filter((i) => i.status === 'accepted');
+    const reqs = repo.reqIdsForProject(projectId);
+    const groups = items.filter((i) => i.kind === 'feature-group');
+    const features = items.filter((i) => i.kind === 'feature');
+    const pages = items.filter((i) => i.kind === 'page');
+    const flows = items.filter((i) => i.kind === 'flow');
+    const steps = items.filter((i) => i.kind === 'step');
+    // 수락된 지시서 §개요(있으면) — AI 생성 요약
+    const overview = repo
+        .listAcceptedSections(doc.id)
+        .find((s) => /개요|overview|배경/i.test(s.heading))?.body.trim();
+    const L = [];
+    L.push(`# ${project?.name ?? '프로젝트'} — 구현 발주 (AI 에이전트용)`, '');
+    L.push('## 역할과 규칙');
+    L.push('너는 이 제품의 구현을 맡은 시니어 엔지니어다. 아래를 지켜라:');
+    L.push('- **수락된 명세만 구현한다.** 여기 없는 것은 만들지 않는다(범위 확장 금지).');
+    L.push('- 각 기능의 **수용 기준을 모두 충족**해야 그 기능이 완료다.');
+    L.push('- 화면은 IA 명세를, 화면 전환은 유저 플로우를 따른다.');
+    L.push('- 불명확한 점은 임의로 정하지 말고 **질문으로 남겨라**.', '');
+    if (overview)
+        L.push('## 제품 개요', overview, '');
+    L.push('## 요구사항 (REQ)');
+    if (reqs.length)
+        for (const r of reqs)
+            L.push(`- **${r.id}** ${r.heading}`);
+    else
+        L.push('- (PRD 수락 섹션 없음)');
+    L.push('');
+    L.push('## 구현할 기능 (수락분)');
+    const prioRank = (f) => ({ P0: 0, P1: 1, P2: 2 }[meta(f).priority ?? 'P2'] ?? 3);
+    const byGroup = (g) => features.filter((f) => f.parent_id === g.id).sort((a, b) => prioRank(a) - prioRank(b));
+    const emit = (f) => {
+        const m = meta(f);
+        const links = [...(m.links?.reqs ?? []), ...(m.links?.pages ?? []), ...(m.links?.flows ?? [])];
+        L.push(`### [${m.priority ?? 'P?'}] ${f.ref_id} ${f.title}`);
+        if (links.length)
+            L.push(`- 연결: ${links.join(' · ')}`);
+        const crit = f.body.split('\n').map((l) => l.replace(/^[·\-*]\s*/, '').trim()).filter(Boolean);
+        if (crit.length) {
+            L.push('- 수용 기준:');
+            for (const c of crit)
+                L.push(`  - [ ] ${c}`);
+        }
+        L.push('');
+    };
+    for (const g of groups.sort((a, b) => a.ref_id.localeCompare(b.ref_id))) {
+        const feats = byGroup(g);
+        if (!feats.length)
+            continue;
+        L.push(`#### ${g.ref_id} ${g.title}`, '');
+        for (const f of feats)
+            emit(f);
+    }
+    const orphanFeats = features.filter((f) => !groups.some((g) => g.id === f.parent_id)).sort((a, b) => prioRank(a) - prioRank(b));
+    if (orphanFeats.length) {
+        L.push('#### 기타', '');
+        for (const f of orphanFeats)
+            emit(f);
+    }
+    if (pages.length) {
+        L.push('## 화면 (IA)');
+        for (const pg of pages) {
+            const m = meta(pg);
+            L.push(`- **${pg.ref_id}** ${pg.title} [${m.page_type ?? 'GENERIC'}]` + (m.links?.features?.length ? ` · 기능 ${m.links.features.join(', ')}` : ''));
+        }
+        L.push('');
+    }
+    if (flows.length) {
+        L.push('## 유저 플로우');
+        for (const fl of flows) {
+            const flSteps = steps.filter((s) => s.parent_id === fl.id).sort((a, b) => a.position - b.position);
+            const chain = flSteps
+                .map((s) => {
+                const sm = meta(s);
+                const pg = sm.page ? `[${sm.page}] ` : '';
+                const br = sm.branch?.label ? ` (${sm.branch.label})` : '';
+                return `${pg}${s.title}${br}`;
+            })
+                .join(' → ');
+            L.push(`- **${fl.ref_id}** ${fl.title}: ${chain || '(스텝 없음)'}`);
+        }
+        L.push('');
+    }
+    L.push('## 비범위 (구현 금지)');
+    L.push('- PRD 비범위 및 수락하지 않은 항목은 이번 구현에서 제외한다.', '');
+    L.push('## 작업 순서');
+    L.push('1. **P0 기능**부터 순서대로 구현한다. 각 기능은 수용 기준 체크박스를 모두 충족해야 완료.');
+    L.push('2. 화면(IA)과 플로우 명세대로 연결한다.');
+    L.push('3. 범위 확장·임의 기능 추가 금지. 불명확하면 질문으로 남긴다.');
+    L.push('4. 완료 시 각 수용 기준을 어떻게 충족했는지 근거와 함께 요약한다.', '');
+    return L.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}

package/api/dist/lib/items-gen.js

@@ -0,0 +1,211 @@
+// AI generation for the three STRUCTURE documents (§2). The LLM returns CONTENT
+// ONLY ({groups|pages|flows}) — never ref_ids (server-numbered §1.2). Output is
+// always 'proposed' with a per-item suggestion carrying its basis (§0.1/§0.3).
+// AI_STUB=1 short-circuits to deterministic fixtures (§2 last bullet).
+import { config } from "./config.js";
+import { resolveProvider } from "../providers/index.js";
+import { getModelConfig } from "./ai.js";
+import { getTemplateForType } from "./templates.js";
+import * as repo from "../db/repos.js";
+import { SPEC_FIXTURE, IA_FIXTURE, FLOW_FIXTURE, } from "./fixtures.js";
+export function isStructureType(t) {
+    return t === 'feature-spec' || t === 'ia' || t === 'user-flow';
+}
+// ── lenient JSON parsing (§2) ────────────────────────────────────────────────
+export function extractJson(text) {
+    let t = text.trim();
+    // drop a leading ```json / ``` fence and a trailing ``` fence
+    t = t.replace(/^```[a-zA-Z]*\s*/, '').replace(/\s*```$/, '').trim();
+    const first = t.indexOf('{');
+    const last = t.lastIndexOf('}');
+    if (first >= 0 && last > first)
+        return t.slice(first, last + 1);
+    return t;
+}
+export function parseItemsJson(text) {
+    return JSON.parse(extractJson(text));
+}
+// ── prompt (non-stub path) ───────────────────────────────────────────────────
+function buildItemsMessages(doc) {
+    const template = getTemplateForType(doc.type);
+    const session = repo.getSessionByDocument(doc.id);
+    const answers = session?.answers ?? [];
+    const ctx = repo.getParentContext(doc.id);
+    const parentBlock = ctx
+        ? `상위 문서(${ctx.parentType} "${ctx.parentTitle}"):\n` +
+            ctx.sections.map((s) => `### ${s.heading}\n${s.body}`).join('\n\n') +
+            '\n\n---\n'
+        : '';
+    const answerBlock = answers.length
+        ? answers.map((a) => `Q: ${a.question}\nA: ${a.answer}`).join('\n\n')
+        : '(답변 없음 — 합리적 기본값)';
+    const shape = SHAPE_HINT[doc.type];
+    const system = `${template?.draftGuidance ?? '구조 문서를 작성한다.'}\n\n` +
+        `반드시 JSON 하나만 출력하라. 코드펜스·설명 문장 금지. ` +
+        `id·번호(F-/PG-/FLOW-)는 절대 넣지 마라 — 번호는 서버가 매긴다.\n${shape}`;
+    const user = `${parentBlock}인터뷰 답변:\n\n${answerBlock}\n\n위 계약대로 JSON 을 출력하라.`;
+    return [
+        { role: 'system', content: system },
+        { role: 'user', content: user },
+    ];
+}
+const SHAPE_HINT = {
+    'feature-spec': '형태: {"groups":[{"title":str,"features":[{"title":str,"body":str,"priority":"P0|P1|P2","source":str,"links":{"reqs":[str],"pages":[str],"flows":[str]}}]}]}',
+    ia: '형태: {"pages":[{"title":str,"section":str,"page_type":"LIST|DETAIL|FORM|DASH|SETTINGS|GENERIC","links":{"features":[str]}}]}. ' +
+        'section 은 사이트맵 계층 그룹(예: "예약","내 정보","관리자") — 관련 화면끼리 같은 section 으로 묶어라.',
+    'user-flow': '형태: {"flows":[{"title":str,"source":str,"links":{"features":[str]},"steps":[{"title":str,"page":str|null,"node":"start|screen|decision|end","branch":{"label":str,"from_step":str}|null,"note":str}]}]}',
+};
+export function materializeSpec(documentId, data, opts) {
+    const status = opts.status ?? 'proposed';
+    for (const g of data.groups) {
+        const group = repo.createItem({
+            documentId,
+            kind: 'feature-group',
+            title: g.title,
+            meta: {},
+            status,
+        });
+        opts.onItem?.(group);
+        if (opts.withSuggestions !== false)
+            addSuggestion(documentId, group, 'PRD');
+        for (const f of g.features) {
+            const feat = repo.createItem({
+                documentId,
+                kind: 'feature',
+                parentId: group.id,
+                title: f.title,
+                body: f.body,
+                meta: { priority: f.priority, source: f.source, links: f.links },
+                status,
+            });
+            opts.onItem?.(feat);
+            if (opts.withSuggestions !== false)
+                addSuggestion(documentId, feat, f.source);
+        }
+    }
+}
+export function materializeIa(documentId, data, opts) {
+    const status = opts.status ?? 'proposed';
+    for (const p of data.pages) {
+        const page = repo.createItem({
+            documentId,
+            kind: 'page',
+            title: p.title,
+            meta: { page_type: p.page_type, section: p.section, source: p.source, links: p.links },
+            status,
+        });
+        opts.onItem?.(page);
+        if (opts.withSuggestions !== false)
+            addSuggestion(documentId, page, p.source ?? 'IA');
+    }
+}
+export function materializeFlow(documentId, data, opts) {
+    const status = opts.status ?? 'proposed';
+    for (const fl of data.flows) {
+        const flow = repo.createItem({
+            documentId,
+            kind: 'flow',
+            title: fl.title,
+            meta: { source: fl.source, links: fl.links },
+            status,
+        });
+        opts.onItem?.(flow);
+        if (opts.withSuggestions !== false)
+            addSuggestion(documentId, flow, fl.source);
+        for (const st of fl.steps) {
+            const step = repo.createItem({
+                documentId,
+                kind: 'step',
+                parentId: flow.id,
+                title: st.title,
+                meta: { page: st.page ?? null, branch: st.branch ?? null, note: st.note, node: st.node },
+                status,
+            });
+            opts.onItem?.(step);
+            // steps are part of a flow proposal — no separate card (keeps queue readable)
+        }
+    }
+}
+function addSuggestion(documentId, item, source) {
+    repo.createSuggestion({
+        documentId,
+        targetItemId: item.id,
+        kind: 'add',
+        title: `${item.ref_id} "${item.title}"`,
+        body: '인터뷰·상위 문서를 바탕으로 제안된 항목입니다. 수락하면 문서에 반영됩니다.',
+        source: source || item.kind,
+    });
+}
+// ── data acquisition (stub vs provider) ──────────────────────────────────────
+async function acquireData(doc) {
+    if (config.aiStub || config.managedTier)
+        return fixtureFor(doc.type);
+    const cfg = getModelConfig(doc.type);
+    const provider = resolveProvider(cfg.provider);
+    const messages = buildItemsMessages(doc);
+    const run = async () => {
+        let text = '';
+        for await (const delta of provider.streamChat({
+            model: cfg.model,
+            maxTokens: cfg.maxTokens,
+            messages,
+        })) {
+            text += delta;
+        }
+        return text;
+    };
+    // lenient parse with one retry (§2)
+    const first = await run();
+    try {
+        return parseItemsJson(first);
+    }
+    catch {
+        const second = await run();
+        return parseItemsJson(second); // throws on second failure → surfaced as error
+    }
+}
+export function fixtureFor(type) {
+    if (type === 'feature-spec')
+        return SPEC_FIXTURE;
+    if (type === 'ia')
+        return IA_FIXTURE;
+    return FLOW_FIXTURE;
+}
+/**
+ * Generate items for a structure document, replacing any prior generated set.
+ * Streams an event per created item, then 'done'. Items land as 'proposed'.
+ */
+export async function* streamItemsGeneration(documentId) {
+    const doc = repo.getDocument(documentId);
+    if (!doc) {
+        yield { type: 'error', message: 'document not found' };
+        return;
+    }
+    if (!isStructureType(doc.type)) {
+        yield { type: 'error', message: `document type ${doc.type} has no item generation` };
+        return;
+    }
+    repo.setDocumentStatus(documentId, 'streaming');
+    try {
+        const data = await acquireData({ id: doc.id, type: doc.type });
+        // fresh generation replaces prior generated items for this document
+        for (const it of repo.listItems(documentId))
+            repo.deleteItem(it.id);
+        const created = [];
+        const opts = { status: 'proposed', withSuggestions: true, onItem: (i) => created.push(i) };
+        if (doc.type === 'feature-spec')
+            materializeSpec(documentId, data, opts);
+        else if (doc.type === 'ia')
+            materializeIa(documentId, data, opts);
+        else
+            materializeFlow(documentId, data, opts);
+        for (const it of created)
+            yield { type: 'item', item: it };
+        repo.setDocumentStatus(documentId, 'ready');
+        yield { type: 'done', documentId, count: created.length };
+    }
+    catch (e) {
+        repo.setDocumentStatus(documentId, 'draft');
+        yield { type: 'error', message: e.message };
+    }
+}

package/api/dist/lib/lint-service.js

@@ -0,0 +1,118 @@
+// Project-level lint orchestration over the DB (§4.2/§4.3). The pure rules live
+// in lint.ts; this layer resolves items, turns violations into suggestions
+// (proposal regression), honours waives, and computes the handoff gate set.
+import * as repo from "../db/repos.js";
+import { lintProject, violationKey } from "./lint.js";
+function projectItemsAndReqs(projectId) {
+    const items = repo.listProjectItems(projectId);
+    const reqIds = repo.reqIdsForProject(projectId).map((r) => r.id);
+    return { items, reqIds };
+}
+/** All violations for a project. */
+export function projectViolations(projectId) {
+    const { items, reqIds } = projectItemsAndReqs(projectId);
+    return lintProject(items, reqIds);
+}
+/** Waived violation keys = lint suggestions rejected by the user (§4.3). */
+export function waivedKeys(projectId) {
+    const keys = new Set();
+    for (const doc of repo.listDocuments(projectId)) {
+        for (const s of repo.listLintSuggestions(doc.id, 'rejected')) {
+            if (s.quote_before)
+                keys.add(s.quote_before);
+        }
+    }
+    return keys;
+}
+/** Violations that still block the handoff gate (all minus waived). */
+export function effectiveViolations(projectId) {
+    const waived = waivedKeys(projectId);
+    return projectViolations(projectId).filter((v) => !waived.has(violationKey(v)));
+}
+export function lintReport(projectId) {
+    const waived = waivedKeys(projectId);
+    const violations = projectViolations(projectId).map((v) => {
+        const key = violationKey(v);
+        return { ...v, key, waived: waived.has(key) };
+    });
+    const effectiveCount = violations.filter((v) => !v.waived).length;
+    return {
+        violations,
+        effectiveCount,
+        waivedCount: violations.length - effectiveCount,
+        gatePasses: effectiveCount === 0,
+    };
+}
+/** Which document should own a lint suggestion — the doc of its subject ref. */
+function ownerDocId(projectId, refs) {
+    const items = repo.listProjectItems(projectId);
+    for (const ref of refs) {
+        const it = items.find((i) => i.ref_id === ref);
+        if (it)
+            return it.document_id;
+    }
+    // fall back to the feature-spec document
+    const spec = repo.listDocuments(projectId).find((d) => d.type === 'feature-spec');
+    return spec?.id ?? repo.listDocuments(projectId)[0]?.id ?? null;
+}
+// Code -> the two-choice card copy (초안이 voice, §4.2).
+const FIX_COPY = {
+    'E-BROKEN-REF': '끊긴 참조가 있어요. 대상 항목을 되살리거나 이 항목을 정리하세요.',
+    'E-DUP-REF': '번호가 겹쳤어요. 항목을 정리하면 번호가 다시 정렬돼요.',
+    'W-ORPHAN-SPEC': '이 기능이 어느 요구에도 연결되지 않았어요. 요구를 잇거나 기능을 정리하세요.',
+    'W-UNREACHED-PAGE': '이 화면에 도달하는 플로우가 없어요. 플로우에 넣거나 화면을 정리하세요.',
+    'W-EMPTY-PAGE': '이 화면에 연결된 기능이 없어요. 기능을 잇거나 화면을 정리하세요.',
+    'W-NO-FLOW': '이 P0 기능이 어느 플로우에도 없어요. 플로우에 넣거나 우선순위를 낮추세요.',
+};
+/**
+ * Regression (§4.2): create a lint suggestion for each current violation that
+ * doesn't already have one (dedupe by code+refs → stored in quote_before). Skips
+ * waived ones (their rejected suggestion already exists). Returns created rows.
+ */
+export function suggestLint(projectId) {
+    const existing = new Set();
+    for (const doc of repo.listDocuments(projectId)) {
+        for (const s of repo.listLintSuggestions(doc.id)) {
+            if (s.quote_before)
+                existing.add(s.quote_before);
+        }
+    }
+    let created = 0;
+    for (const v of projectViolations(projectId)) {
+        const key = violationKey(v);
+        if (existing.has(key))
+            continue; // dedupe (open or already-resolved)
+        const docId = ownerDocId(projectId, v.refs);
+        if (!docId)
+            continue;
+        repo.createSuggestion({
+            documentId: docId,
+            kind: 'lint',
+            title: `${v.refs[0]} · ${v.code}`,
+            body: FIX_COPY[v.code] ?? v.message,
+            quoteBefore: key, // dedupe / waive key
+            quoteAfter: v.message,
+            source: v.code,
+        });
+        existing.add(key);
+        created++;
+    }
+    return created;
+}
+/**
+ * Apply the default remediation when a lint suggestion is ACCEPTED (§4.2): the
+ * subject item (refs[0]) is rejected, which deterministically clears the
+ * violation on the next lint. REQ-only subjects have no item — nothing to do.
+ */
+export function applyLintFix(projectId, subjectRef) {
+    const items = repo.listProjectItems(projectId);
+    const subject = items.find((i) => i.ref_id === subjectRef);
+    if (subject)
+        repo.setItemStatus(subject.id, 'rejected');
+}
+/** Same, resolved by violation key (code::sortedRefs) — used on suggestion accept. */
+export function applyLintFixByKey(projectId, key) {
+    const v = projectViolations(projectId).find((x) => violationKey(x) === key);
+    if (v)
+        applyLintFix(projectId, v.refs[0]);
+}