@seasonkoh/webaz 0.1.25 → 0.1.27

package/dist/layer2-business/L2-9-contribution/task-proposal-ai-store.js

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+import { generateId } from '../../layer0-foundation/L0-1-database/schema.js';
+export function initTaskProposalAiSchema(db) {
+    // CREATE only (no ALTER) — additive, never blocks an existing fresh-DB boot.
+    db.exec(`CREATE TABLE IF NOT EXISTS task_proposal_ai_suggestions (
+    id            TEXT PRIMARY KEY,
+    proposal_id   TEXT NOT NULL,
+    reviewer_type TEXT NOT NULL DEFAULT 'ai',
+    model         TEXT,
+    provider      TEXT,
+    input_hash    TEXT,
+    input_summary TEXT,
+    output_json   TEXT NOT NULL,
+    created_at    TEXT NOT NULL DEFAULT (datetime('now'))
+  )`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_tpai_proposal ON task_proposal_ai_suggestions(proposal_id, created_at DESC)`);
+}
+/** Read the fields the recommender needs (keeps the route free of direct SQL). */
+export function getProposalLite(db, id) {
+    return db.prepare('SELECT id, title, summary, suggested_area, source_ref, expected_outcome FROM task_proposals WHERE id = ?').get(id) ?? null;
+}
+const CATEGORY_KEYWORDS = {
+    docs: ['doc', 'readme', '文档', 'guide'], i18n: ['i18n', 'translat', '翻译', 'locale'],
+    tests: ['test', '测试', 'spec'], ui: ['ui', 'page', 'button', '界面', 'pwa', 'css'],
+    api: ['api', 'endpoint', 'route'], schema: ['schema', 'migration', 'table', '字段'],
+    infra: ['ci', 'deploy', 'infra', 'pipeline', 'docker'], governance: ['governance', 'charter', '治理', 'rfc'],
+    audit: ['audit', 'security', '审计', '安全'], code: ['fix', 'bug', 'refactor', 'implement', '实现', '修复'],
+};
+const HIGH_RISK_KEYWORDS = ['wallet', 'withdraw', 'fund', 'money', 'settle', 'escrow', 'payment', 'reward', 'schema', 'migration', 'auth', 'admin', 'key', '资金', '钱包', '提现', '结算', '权限', '密钥'];
+const norm = (s) => s.toLowerCase().replace(/[^a-z0-9一-鿿]+/g, ' ').trim();
+/**
+ * Deterministic local heuristic recommendation (stub for a future model). Read-only; never decides.
+ */
+export function recommendForProposal(db, p) {
+    const text = norm(`${p.title} ${p.summary} ${p.suggested_area ?? ''}`);
+    // category
+    let category = 'other';
+    let best = 0;
+    for (const [cat, kws] of Object.entries(CATEGORY_KEYWORDS)) {
+        const hits = kws.filter(k => text.includes(k)).length;
+        if (hits > best) {
+            best = hits;
+            category = cat;
+        }
+    }
+    // risk
+    const risk = HIGH_RISK_KEYWORDS.some(k => text.includes(k)) ? 'high' : (p.summary.length > 400 ? 'medium' : 'low');
+    // effort by summary size
+    const effort = p.summary.length > 600 ? 'large' : p.summary.length > 200 ? 'medium' : 'small';
+    // missing info flags
+    const missing_info = [];
+    if (p.summary.trim().length < 40)
+        missing_info.push('summary too short — needs concrete scope / acceptance');
+    if (!p.source_ref)
+        missing_info.push('no source_ref (file / RFC / issue reference)');
+    if (!p.expected_outcome)
+        missing_info.push('no expected_outcome (definition of done)');
+    // duplicate likelihood: normalized-title overlap vs existing proposals + build_tasks
+    const titleNorm = norm(p.title);
+    const titleWords = new Set(titleNorm.split(' ').filter(w => w.length >= 3));
+    let dupScore = 0;
+    if (titleWords.size > 0) {
+        const others = db.prepare(`SELECT title FROM task_proposals WHERE id != ? UNION ALL SELECT title FROM build_tasks`).all(p.id);
+        for (const o of others) {
+            const ow = new Set(norm(o.title).split(' ').filter(w => w.length >= 3));
+            let inter = 0;
+            for (const w of titleWords)
+                if (ow.has(w))
+                    inter++;
+            const jac = inter / (titleWords.size + ow.size - inter || 1);
+            if (jac > dupScore)
+                dupScore = jac;
+        }
+    }
+    const duplicate_likelihood = dupScore >= 0.6 ? 'high' : dupScore >= 0.3 ? 'medium' : 'low';
+    const recommendation = {
+        category, risk, effort, missing_info, duplicate_likelihood,
+        suggested: {
+            title: p.title,
+            area: p.suggested_area ?? category,
+            description: p.summary,
+            acceptance_criteria: p.expected_outcome ? [String(p.expected_outcome).slice(0, 500)] : [],
+            verification_commands: [],
+        },
+    };
+    return { recommendation, model: 'heuristic-v1', provider: 'local' };
+}
+/** Persist an AI suggestion as evidence (accountability metadata). Returns the row id. */
+export function insertAiSuggestion(db, args) {
+    const id = generateId('tpai');
+    const inputHash = createHash('sha256').update(args.inputSummary).digest('hex');
+    db.prepare(`INSERT INTO task_proposal_ai_suggestions (id, proposal_id, reviewer_type, model, provider, input_hash, input_summary, output_json)
+    VALUES (?,?,?,?,?,?,?,?)`).run(id, args.proposalId, args.reviewerType ?? 'ai', args.model ?? null, args.provider ?? null, inputHash, args.inputSummary.slice(0, 1000), args.outputJson);
+    return { id };
+}
+export function listAiSuggestions(db, proposalId) {
+    return db.prepare(`SELECT id, proposal_id, reviewer_type, model, provider, input_summary, output_json, created_at
+    FROM task_proposal_ai_suggestions WHERE proposal_id = ? ORDER BY created_at DESC LIMIT 20`).all(proposalId);
+}

package/dist/layer2-business/L2-9-contribution/task-proposal-draft.js

@@ -0,0 +1,360 @@
+import { createBuildTask, logTaskEvent, releaseExpiredClaims } from './build-tasks-engine.js';
+import { insertBuildTaskAgentMetadata, getBuildTaskAgentMetadata, setBuildTaskAudience, setBuildTaskEstimate, RISK_LEVELS, TASK_TYPES, CONTEXT_SIZES, AGENT_BUDGETS } from './build-task-agent-metadata-store.js';
+import { reviewTaskProposal } from './task-proposal-store.js';
+/** Source-proposal ↔ draft-task link (lets a draft preserve its origin WITHOUT marking the proposal terminal). */
+export function initTaskProposalDraftLinkSchema(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS task_proposal_draft_links (
+    task_id      TEXT PRIMARY KEY,
+    proposal_id  TEXT NOT NULL,
+    created_by   TEXT NOT NULL,
+    status       TEXT NOT NULL DEFAULT 'active',
+    discarded_by TEXT,
+    discarded_at TEXT,
+    created_at   TEXT NOT NULL DEFAULT (datetime('now'))
+  )`);
+    // Additive migration for pre-existing DBs (ALTER after CREATE; fresh DBs already have these columns).
+    // status = 'active' | 'discarded'. A discarded link is SOFT-deleted: the row is retained for provenance
+    // (retroactive reward / anchor-side traceability / dispute), and it frees the proposal's draft slot.
+    try {
+        const cols = db.prepare('PRAGMA table_info(task_proposal_draft_links)').all();
+        if (!cols.some(c => c.name === 'status'))
+            db.exec("ALTER TABLE task_proposal_draft_links ADD COLUMN status TEXT NOT NULL DEFAULT 'active'");
+        if (!cols.some(c => c.name === 'discarded_by'))
+            db.exec('ALTER TABLE task_proposal_draft_links ADD COLUMN discarded_by TEXT');
+        if (!cols.some(c => c.name === 'discarded_at'))
+            db.exec('ALTER TABLE task_proposal_draft_links ADD COLUMN discarded_at TEXT');
+    }
+    catch { /* best-effort additive migration */ }
+    // PARTIAL UNIQUE: at most one ACTIVE draft per proposal (discarded links are retained but excluded), so a
+    // discarded draft truly frees the slot. Replaces the old full unique index on proposal_id.
+    try {
+        db.exec('DROP INDEX IF EXISTS idx_tpdl_proposal');
+    }
+    catch { /* noop */ }
+    db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_tpdl_proposal_active ON task_proposal_draft_links(proposal_id) WHERE status = 'active'");
+}
+/**
+ * case_id threads a case end to end: proposal → task → PR. For a task converted from a proposal it is that
+ * source proposal id (so proposer + contributor + PR all quote the same id); for a directly-created task it
+ * is the task id itself. Guarded: the link table may be absent in minimal setups → fall back to the task id.
+ */
+export function caseIdForTask(db, taskId) {
+    try {
+        const link = db.prepare('SELECT proposal_id FROM task_proposal_draft_links WHERE task_id = ?').get(taskId);
+        if (link?.proposal_id)
+            return link.proposal_id;
+    }
+    catch { /* link table absent → case_id is the task id */ }
+    return taskId;
+}
+const strList = (v) => Array.isArray(v) ? v.slice(0, 50).map(s => String(s).slice(0, 500)).filter(s => s.trim()) : [];
+const txt = (v) => (v ?? '').trim();
+/** Handoff fields an executable agent task must carry. Returns the list of missing ones (empty = complete). */
+function missingHandoff(f) {
+    const missing = [];
+    if (!txt(f.title))
+        missing.push('title');
+    if (!txt(f.description))
+        missing.push('summary/description (reason)');
+    if (f.allowed_paths.length === 0)
+        missing.push('allowed_paths (execution boundary)');
+    if (f.prohibited_actions.length === 0)
+        missing.push('forbidden_actions');
+    if (f.acceptance_criteria.length === 0)
+        missing.push('acceptance_criteria');
+    if (f.verification_commands.length === 0)
+        missing.push('verification_commands');
+    if (f.deliverables.length === 0)
+        missing.push('deliverables');
+    if (!txt(f.expected_results))
+        missing.push('expected_results');
+    if (!txt(f.definition_of_done))
+        missing.push('definition_of_done');
+    return missing;
+}
+/**
+ * Create an UNPUBLISHED draft (internal build_task) from a non-terminal proposal and record the
+ * source-proposal ↔ draft link. Does NOT mark the proposal 'converted' (acceptance happens at publish).
+ * Returns the new draft task id.
+ */
+export function createDraftFromProposal(db, a) {
+    // 1) proposal must exist + be non-terminal (only new / needs_info → draft). Pre-check before creating anything.
+    const prop = db.prepare('SELECT id, status FROM task_proposals WHERE id = ?').get(a.proposalId);
+    if (!prop)
+        return { error: 'proposal not found', error_code: 'PROPOSAL_NOT_FOUND' };
+    if (prop.status === 'rejected' || prop.status === 'converted')
+        return { error: `proposal already ${prop.status}`, error_code: 'PROPOSAL_TERMINAL' };
+    // one ACTIVE draft per proposal (a discarded draft is soft-deleted and frees the slot; not terminal-status based)
+    const existingLink = db.prepare("SELECT task_id FROM task_proposal_draft_links WHERE proposal_id = ? AND status != 'discarded'").get(a.proposalId);
+    if (existingLink)
+        return { error: `a task draft already exists for this proposal (${existingLink.task_id})`, error_code: 'PROPOSAL_HAS_DRAFT' };
+    // draft risk stays low/medium (high/critical metadata rules are out of scope for this PR)
+    const riskLevel = (a.riskLevel === 'medium') ? 'medium' : 'low';
+    if (a.riskLevel && !RISK_LEVELS.includes(a.riskLevel))
+        return { error: 'invalid risk_level', error_code: 'BAD_RISK_LEVEL' };
+    if (a.riskLevel === 'high' || a.riskLevel === 'critical')
+        return { error: 'draft risk_level must be low or medium (high/critical deferred)', error_code: 'RISK_TOO_HIGH_FOR_DRAFT' };
+    const taskType = (a.taskType && TASK_TYPES.includes(a.taskType)) ? a.taskType : 'other';
+    // (a) #34/#5: an OPTIONAL real effort estimate. Provided → validated + stored; omitted → 0–0 placeholder
+    // (draft stays internal/unclaimable, and publishDraftBuildTask fails closed until a real estimate exists).
+    let durMin = 0, durMax = 0;
+    if (a.estimatedDurationMinMinutes !== undefined || a.estimatedDurationMaxMinutes !== undefined) {
+        const mn = Number(a.estimatedDurationMinMinutes), mx = Number(a.estimatedDurationMaxMinutes);
+        if (!Number.isInteger(mn) || !Number.isInteger(mx) || mn < 0 || mx < mn || mx < 1)
+            return { error: 'estimated_duration must be integer minutes with max >= min and max >= 1 (a real, non-zero estimate)', error_code: 'BAD_ESTIMATE' };
+        durMin = mn;
+        durMax = mx;
+    }
+    if (a.estimatedAgentBudget !== undefined && !AGENT_BUDGETS.includes(a.estimatedAgentBudget))
+        return { error: 'invalid estimated_agent_budget', error_code: 'BAD_AGENT_BUDGET' };
+    if (a.estimatedContextSize !== undefined && !CONTEXT_SIZES.includes(a.estimatedContextSize))
+        return { error: 'invalid estimated_context_size', error_code: 'BAD_CONTEXT_SIZE' };
+    // 2) assemble the agent-handoff fields and VALIDATE completeness BEFORE creating anything — the existing
+    //    task model requires these to be executable, so we never create an incomplete/orphan task.
+    const allowed = strList(a.allowedPaths);
+    const prohibited = strList(a.forbiddenActions);
+    const accept = strList(a.acceptanceCriteria);
+    const verify = strList(a.verificationCommands);
+    const deliver = strList(a.deliverables);
+    const description = txt(a.description);
+    const dod = txt(a.definitionOfDone).slice(0, 1000);
+    const expected = (txt(a.expectedResults) || description).slice(0, 1000);
+    const missing = missingHandoff({ title: txt(a.title), description, allowed_paths: allowed, prohibited_actions: prohibited, acceptance_criteria: accept, verification_commands: verify, deliverables: deliver, expected_results: expected, definition_of_done: dod });
+    if (missing.length > 0)
+        return { error: `draft incomplete — provide: ${missing.join(', ')}`, error_code: 'DRAFT_INCOMPLETE', missing };
+    // 3) create the formal task via the trusted path (creator = admin → accountability)
+    const created = createBuildTask(db, { creatorId: a.adminId, title: a.title, area: a.area ?? undefined, description: a.description ?? undefined, rfcRef: a.sourceRef ?? undefined });
+    if ('error' in created)
+        return created;
+    const taskId = created.id;
+    // 4) attach agent_metadata as an INTERNAL draft (hidden + unclaimable via the existing read/participation
+    //    guards). auto_claimable defaults TRUE so once published the task enters the normal agent claim flow
+    //    (maintainer may opt human-only with autoClaimable:false). While audience='internal' it is unclaimable.
+    const caps = strList(a.requiredCapabilities);
+    if (caps.length === 0)
+        caps.push('general');
+    const meta = {
+        task_type: taskType,
+        source_ref: a.sourceRef ?? null,
+        allowed_paths: allowed,
+        forbidden_paths: strList(a.forbiddenPaths),
+        prohibited_actions: prohibited,
+        risk_level: riskLevel,
+        audience: 'internal',
+        agent_autonomy: 'human_in_the_loop',
+        auto_claimable: a.autoClaimable !== false,
+        required_capabilities: caps,
+        acceptance_criteria: accept,
+        verification_commands: verify,
+        expected_results: expected,
+        deliverables: deliver,
+        definition_of_done: dod,
+        estimated_duration_min_minutes: durMin,
+        estimated_duration_max_minutes: durMax,
+        estimated_context_size: a.estimatedContextSize ?? 'small',
+        estimated_agent_budget: a.estimatedAgentBudget ?? 'minimal',
+        value_state: 'uncommitted',
+        contribution_type: 'task',
+        accountable_party_required: true,
+    };
+    insertBuildTaskAgentMetadata(db, taskId, meta);
+    // 5) record the source-proposal ↔ draft link (accountability) — WITHOUT marking the proposal converted;
+    //    the proposal stays non-terminal until an explicit human publish.
+    db.prepare('INSERT INTO task_proposal_draft_links (task_id, proposal_id, created_by) VALUES (?,?,?)').run(taskId, a.proposalId, a.adminId);
+    return { draft_task_id: taskId };
+}
+/** Admin list of UNPUBLISHED drafts (internal, open) + their source proposal id (via the draft-link table). */
+export function listDraftBuildTasks(db) {
+    return db.prepare(`
+    SELECT t.id, t.title, t.area, t.description, t.rfc_ref, t.status, t.created_by, t.created_at,
+           m.risk_level, m.audience, m.auto_claimable,
+           l.proposal_id AS source_proposal_id
+    FROM build_tasks t
+    JOIN build_task_agent_metadata m ON m.task_id = t.id
+    LEFT JOIN task_proposal_draft_links l ON l.task_id = t.id
+    WHERE m.audience = 'internal' AND t.status = 'open' AND (l.status IS NULL OR l.status != 'discarded')
+    ORDER BY t.created_at DESC LIMIT 200
+  `).all();
+}
+/**
+ * Validate that a draft carries enough agent-handoff info to be executed by another participant's agent.
+ * Returns the list of missing fields (empty = complete). Gate for publish — never publish an incomplete task.
+ */
+export function validateDraftForPublish(task, meta) {
+    return missingHandoff({
+        title: txt(task.title), description: txt(task.description),
+        allowed_paths: meta.allowed_paths ?? [], prohibited_actions: meta.prohibited_actions ?? [],
+        acceptance_criteria: meta.acceptance_criteria ?? [], verification_commands: meta.verification_commands ?? [],
+        deliverables: meta.deliverables ?? [], expected_results: txt(meta.expected_results), definition_of_done: txt(meta.definition_of_done),
+    });
+}
+/**
+ * PUBLISH a draft → audience 'public' (now on the board / claimable via the existing flow). Explicit
+ * human/admin action only; validates agent-handoff completeness first (never publishes an incomplete task).
+ * This is also where the source proposal is marked 'converted' (converted_ref=task id, reviewer=actor) —
+ * acceptance happens at publish, not at draft creation. The canonical repo / PR target is the protocol-wide
+ * canonical contribution target enforced by the existing submit path — it is not stored per-task.
+ *
+ * Evidence-chain guard: the linked proposal is validated BEFORE anything is published. If it was rejected (or
+ * converted to a different task) since draft creation, publish is refused (409) and the task stays internal —
+ * so a public, claimable task can never coexist with a rejected source proposal. The audience flip + proposal
+ * conversion run in one transaction (both or neither).
+ */
+export function publishDraftBuildTask(db, taskId, adminId, estimate) {
+    const meta = getBuildTaskAgentMetadata(db, taskId);
+    if (!meta)
+        return { error: 'task has no draft metadata', error_code: 'NOT_A_DRAFT' };
+    if (meta.audience !== 'internal')
+        return { error: 'task is not an internal draft', error_code: 'NOT_DRAFT_AUDIENCE' };
+    const t = db.prepare('SELECT status, title, description FROM build_tasks WHERE id = ?').get(taskId);
+    if (!t)
+        return { error: 'task not found', error_code: 'NOT_FOUND' };
+    const missing = validateDraftForPublish(t, meta);
+    if (missing.length > 0)
+        return { error: `draft incomplete — fill before publish: ${missing.join(', ')}`, error_code: 'DRAFT_INCOMPLETE', missing };
+    // validate the linked proposal FIRST — do not publish on top of a rejected / elsewhere-converted proposal.
+    const link = db.prepare('SELECT proposal_id, status FROM task_proposal_draft_links WHERE task_id = ?').get(taskId);
+    let proposalToConvert = null;
+    if (link) {
+        if (link.status === 'discarded')
+            return { error: 'draft was discarded — cannot publish', error_code: 'DRAFT_DISCARDED' };
+        const prop = db.prepare('SELECT status, converted_ref FROM task_proposals WHERE id = ?').get(link.proposal_id);
+        if (prop) {
+            if (prop.status === 'rejected')
+                return { error: 'source proposal was rejected — cannot publish', error_code: 'PROPOSAL_REJECTED' };
+            if (prop.status === 'converted' && prop.converted_ref !== taskId)
+                return { error: 'source proposal already converted to a different task', error_code: 'PROPOSAL_CONVERTED_ELSEWHERE' };
+            if (prop.status === 'new' || prop.status === 'needs_info')
+                proposalToConvert = link.proposal_id;
+        }
+    }
+    // (a) #34/#5: FAIL-CLOSED on a placeholder estimate (checked AFTER proposal validity, so a dead/rejected
+    // source surfaces its own error first). A published task must carry a REAL effort estimate (non 0–0 /
+    // non-null duration), else the claim guard would correctly refuse it as manual_review forever ("published
+    // but unclaimable"). The maintainer may supply the estimate here; otherwise the draft's stored estimate must
+    // already be real. The override is validated + persisted inside the publish transaction below.
+    const overrideEstimate = !!estimate && (estimate.minMinutes !== undefined || estimate.maxMinutes !== undefined);
+    let effMin = meta.estimated_duration_min_minutes;
+    let effMax = meta.estimated_duration_max_minutes;
+    if (overrideEstimate) {
+        const mn = Number(estimate.minMinutes), mx = Number(estimate.maxMinutes);
+        if (!Number.isInteger(mn) || !Number.isInteger(mx) || mn < 0 || mx < mn || mx < 1)
+            return { error: 'estimated_duration must be integer minutes with max >= min and max >= 1 (a real, non-zero estimate)', error_code: 'BAD_ESTIMATE' };
+        effMin = mn;
+        effMax = mx;
+    }
+    if (estimate?.budget !== undefined && !AGENT_BUDGETS.includes(estimate.budget))
+        return { error: 'invalid estimated_agent_budget', error_code: 'BAD_AGENT_BUDGET' };
+    if (estimate?.contextSize !== undefined && !CONTEXT_SIZES.includes(estimate.contextSize))
+        return { error: 'invalid estimated_context_size', error_code: 'BAD_CONTEXT_SIZE' };
+    const estimateReal = effMin != null && effMax != null && !(effMin === 0 && effMax === 0);
+    if (!estimateReal)
+        return { error: 'a real effort estimate is required before publishing (the draft still has the 0–0 placeholder); supply estimate {minMinutes, maxMinutes}', error_code: 'DRAFT_ESTIMATE_REQUIRED' };
+    // all validation passed → publish atomically: persist any estimate override + flip audience + (if
+    // applicable) mark the proposal converted. All-or-nothing.
+    db.transaction(() => {
+        if (overrideEstimate || estimate?.budget !== undefined || estimate?.contextSize !== undefined) {
+            setBuildTaskEstimate(db, taskId, { minMinutes: effMin, maxMinutes: effMax, budget: estimate?.budget, contextSize: estimate?.contextSize });
+        }
+        setBuildTaskAudience(db, taskId, 'public');
+        logTaskEvent(db, taskId, adminId, t.status, t.status, 'published from draft (audience → public)');
+        if (proposalToConvert) {
+            const rv = reviewTaskProposal(db, proposalToConvert, adminId, 'converted', `published as formal task ${taskId}`, taskId);
+            if ('error' in rv)
+                throw new Error(`proposal conversion failed: ${rv.code}`); // rollback the audience flip
+        }
+    })();
+    return { ok: true, task_id: taskId };
+}
+/**
+ * DISCARD an unpublished internal draft — SOFT-delete (status='discarded'); the link row is RETAINED for
+ * provenance (retroactive reward / anchor-side traceability / dispute). Discarding frees the proposal's draft
+ * slot (createDraftFromProposal counts only non-discarded links), so a fresh draft can be created.
+ *
+ * Fail-closed: ONLY an internal, unpublished, unclaimed draft may be discarded. A published draft (audience
+ * flipped to public), a claimed task, or an already-converted source proposal is REFUSED — discard never
+ * touches anything that's live on the board or already accepted. Scope is discard only (NOT a generic edit).
+ */
+export function discardDraft(db, taskId, adminId) {
+    const link = db.prepare('SELECT proposal_id, status FROM task_proposal_draft_links WHERE task_id = ?').get(taskId);
+    if (!link)
+        return { error: 'no draft link for this task', error_code: 'NOT_FOUND' };
+    if (link.status === 'discarded')
+        return { ok: true, task_id: taskId, already_discarded: true }; // idempotent
+    // fail-closed guards — only an internal, unpublished, unclaimed draft of a non-converted proposal
+    const meta = getBuildTaskAgentMetadata(db, taskId);
+    if (!meta)
+        return { error: 'task has no draft metadata', error_code: 'NOT_A_DRAFT' };
+    if (meta.audience !== 'internal')
+        return { error: 'task is published (audience is not internal) — cannot discard', error_code: 'ALREADY_PUBLISHED' };
+    const t = db.prepare('SELECT status, claimer_id FROM build_tasks WHERE id = ?').get(taskId);
+    if (!t)
+        return { error: 'task not found', error_code: 'NOT_FOUND' };
+    if (t.claimer_id)
+        return { error: 'task is claimed — cannot discard', error_code: 'DRAFT_CLAIMED' };
+    const prop = db.prepare('SELECT status FROM task_proposals WHERE id = ?').get(link.proposal_id);
+    if (prop && prop.status === 'converted')
+        return { error: 'source proposal already converted — cannot discard', error_code: 'ALREADY_CONVERTED' };
+    db.prepare("UPDATE task_proposal_draft_links SET status = 'discarded', discarded_by = ?, discarded_at = datetime('now') WHERE task_id = ?").run(adminId, taskId);
+    return { ok: true, task_id: taskId };
+}
+/**
+ * Full stored body of an UNPUBLISHED internal draft — for pre-publish PREVIEW so a maintainer publishes
+ * against the exact content that will go live (not a blind button). Returns null unless the task is an
+ * internal-audience draft (getBuildTaskWithAgentMetadata's member/public scopes deliberately hide internal,
+ * so this admin-only read exists). Read-only — does not change publish behavior.
+ */
+export function getDraftBuildTaskDetail(db, taskId) {
+    const meta = getBuildTaskAgentMetadata(db, taskId);
+    if (!meta || meta.audience !== 'internal')
+        return null; // only unpublished internal drafts are previewable here
+    const t = db.prepare('SELECT id, title, area, description, rfc_ref, status, created_by, created_at FROM build_tasks WHERE id = ?').get(taskId);
+    if (!t)
+        return null;
+    const link = db.prepare('SELECT proposal_id, status FROM task_proposal_draft_links WHERE task_id = ?').get(taskId);
+    return {
+        ...t,
+        source_proposal_id: link?.proposal_id ?? null,
+        draft_link_status: link?.status ?? null,
+        agent_metadata: meta, // full body: allowed/forbidden paths, prohibited_actions, acceptance_criteria, verification_commands, deliverables, definition_of_done, expected_results, risk_level, auto_claimable, …
+    };
+}
+/**
+ * Recovery: WITHDRAW a published task that was converted from a proposal — pull it off the public board and
+ * REOPEN the source proposal so a corrected draft can be built. Fail-closed: only an UNCLAIMED, open,
+ * published task (audience='public') may be withdrawn (a claimed / in_review / done task is refused).
+ *
+ * Soft-delete semantics (provenance retained): the build_task is set status='abandoned' (off the board, row
+ * kept), the draft link is marked 'discarded' (kept, frees the slot), and the proposal is un-converted
+ * (status='new', converted_ref cleared) so createDraftFromProposal works again. Scope = recovery only.
+ */
+export function withdrawPublishedTask(db, taskId, adminId) {
+    releaseExpiredClaims(db); // an expired claim is effectively unclaimed
+    const meta = getBuildTaskAgentMetadata(db, taskId);
+    if (!meta)
+        return { error: 'task not found', error_code: 'NOT_FOUND' };
+    if (meta.audience !== 'public')
+        return { error: 'task is not published (use discard for an internal draft)', error_code: 'NOT_PUBLISHED' };
+    const t = db.prepare('SELECT status, claimer_id FROM build_tasks WHERE id = ?').get(taskId);
+    if (!t)
+        return { error: 'task not found', error_code: 'NOT_FOUND' };
+    if (t.claimer_id || t.status !== 'open')
+        return { error: `task is ${t.status}${t.claimer_id ? ' (claimed)' : ''} — only an UNCLAIMED open task can be withdrawn`, error_code: 'TASK_CLAIMED' };
+    const link = db.prepare('SELECT proposal_id, status FROM task_proposal_draft_links WHERE task_id = ?').get(taskId);
+    let reopened = null;
+    db.transaction(() => {
+        db.prepare("UPDATE build_tasks SET status = 'abandoned', updated_at = datetime('now') WHERE id = ?").run(taskId);
+        logTaskEvent(db, taskId, adminId, t.status, 'abandoned', 'withdrawn by admin — published task pulled off the board (recovery)');
+        if (link) {
+            if (link.status !== 'discarded')
+                db.prepare("UPDATE task_proposal_draft_links SET status = 'discarded', discarded_by = ?, discarded_at = datetime('now') WHERE task_id = ?").run(adminId, taskId);
+            const prop = db.prepare('SELECT status, converted_ref FROM task_proposals WHERE id = ?').get(link.proposal_id);
+            if (prop && prop.status === 'converted' && prop.converted_ref === taskId) {
+                db.prepare("UPDATE task_proposals SET status = 'new', converted_ref = NULL, reviewer_id = NULL, review_note = ?, updated_at = datetime('now') WHERE id = ?")
+                    .run(`reopened: published task ${taskId} withdrawn by admin`, link.proposal_id);
+                reopened = link.proposal_id;
+            }
+        }
+    })();
+    return { ok: true, task_id: taskId, reopened_proposal_id: reopened };
+}

package/dist/layer2-business/L2-9-contribution/task-proposal-store.js

@@ -15,6 +15,7 @@ const CREATE_TABLE = `
     status                TEXT NOT NULL DEFAULT 'new' CHECK (status IN ('new','needs_info','rejected','converted')),
     reviewer_id           TEXT,
     review_note           TEXT CHECK (review_note IS NULL OR length(review_note) <= 2000),
+    public_reply          TEXT CHECK (public_reply IS NULL OR length(public_reply) <= 2000),
     converted_ref         TEXT CHECK (converted_ref IS NULL OR length(converted_ref) <= 500),
     created_at            TEXT NOT NULL DEFAULT (datetime('now')),
     updated_at            TEXT NOT NULL DEFAULT (datetime('now'))
@@ -24,6 +25,14 @@ const CREATE_INDEX = `CREATE INDEX IF NOT EXISTS idx_task_proposals_status ON ta
 export function initTaskProposalSchema(db) {
     db.exec(CREATE_TABLE);
     db.exec(CREATE_INDEX);
+    // Additive migration for pre-existing DBs (ALTER after CREATE; fresh DBs already have the column via CREATE_TABLE).
+    // public_reply = the proposer-facing reply (distinct from the admin-internal review_note).
+    try {
+        const cols = db.prepare('PRAGMA table_info(task_proposals)').all();
+        if (!cols.some(c => c.name === 'public_reply'))
+            db.exec('ALTER TABLE task_proposals ADD COLUMN public_reply TEXT');
+    }
+    catch { /* best-effort additive migration */ }
 }
 /** Validate a public submission — fail-closed: bad/oversized fields are rejected, never silently truncated. */
 export function validateProposalInput(body) {
@@ -102,9 +111,21 @@ export function listTaskProposals(db, filter = {}) {
         params.push(filter.status);
     }
     return db.prepare(`SELECT id, title, summary, suggested_area, expected_outcome, source_ref, proposer_account_id,
-    proposer_github_login, status, reviewer_id, review_note, converted_ref, created_at, updated_at FROM task_proposals
+    proposer_github_login, status, reviewer_id, review_note, public_reply, converted_ref, created_at, updated_at FROM task_proposals
     ${where.length ? 'WHERE ' + where.join(' AND ') : ''} ORDER BY created_at DESC LIMIT 200`).all(...params);
 }
+/**
+ * Proposer-facing read: returns ONLY the caller's own proposals, and ONLY proposer-safe fields.
+ * Deliberately excludes the admin-internal `review_note`, `reviewer_id`, and never returns other users' rows
+ * (least-privilege; the proposer sees status + the proposer-facing `public_reply` + converted_ref).
+ */
+export function listMyProposals(db, accountId) {
+    if (!accountId)
+        return [];
+    return db.prepare(`SELECT id, title, summary, suggested_area, expected_outcome, source_ref, status,
+    public_reply, converted_ref, created_at, updated_at FROM task_proposals
+    WHERE proposer_account_id = ? ORDER BY created_at DESC LIMIT 100`).all(accountId);
+}
 /**
  * Review a proposal: needs_info / rejected / converted. NO build_task is created here (conversion is a
  * later manual maintainer step — deferred). Terminal states (rejected/converted) cannot be re-reviewed.
@@ -112,18 +133,22 @@ export function listTaskProposals(db, filter = {}) {
  * product decision — the non-code contribution evidence chain { proposer → reviewer → converted_ref }.
  * Recording only; no reward/score is computed.
  */
-export function reviewTaskProposal(db, id, reviewerId, status, note, convertedRef) {
+export function reviewTaskProposal(db, id, reviewerId, status, note, convertedRef, publicReply) {
     if (!REVIEW_TARGETS.includes(status))
         return { error: 'status must be needs_info | rejected | converted', code: 'BAD_STATUS' };
     if (convertedRef != null && (typeof convertedRef !== 'string' || convertedRef.length > CONVERTED_REF_MAX))
         return { error: 'converted_ref invalid/too long', code: 'CONVERTED_REF_TOO_LONG' };
+    if (publicReply != null && typeof publicReply !== 'string')
+        return { error: 'public_reply must be a string', code: 'PUBLIC_REPLY_INVALID' };
     const cur = db.prepare('SELECT status FROM task_proposals WHERE id = ?').get(id);
     if (!cur)
         return { error: 'proposal not found', code: 'NOT_FOUND' };
     if (cur.status === 'rejected' || cur.status === 'converted')
         return { error: `proposal already ${cur.status}`, code: 'ALREADY_TERMINAL' };
     const ref = status === 'converted' && typeof convertedRef === 'string' && convertedRef.trim() ? convertedRef.trim() : null;
-    db.prepare(`UPDATE task_proposals SET status = ?, reviewer_id = ?, review_note = ?, converted_ref = ?, updated_at = datetime('now') WHERE id = ?`)
-        .run(status, reviewerId, note ? String(note).slice(0, NOTE_MAX) : null, ref, id);
+    // public_reply: update only when provided (COALESCE keeps a prior reply if this review omits it).
+    const reply = publicReply != null ? String(publicReply).slice(0, NOTE_MAX) : null;
+    db.prepare(`UPDATE task_proposals SET status = ?, reviewer_id = ?, review_note = ?, public_reply = COALESCE(?, public_reply), converted_ref = ?, updated_at = datetime('now') WHERE id = ?`)
+        .run(status, reviewerId, note ? String(note).slice(0, NOTE_MAX) : null, reply, ref, id);
     return { id, status, converted_ref: ref };
 }

package/dist/ledger.js

@@ -42,7 +42,7 @@ export function debitStakeThenBalance(db, userId, amountU) {
 }
 /**
  * 通用基金/池表的【绝对值】入账(整数 base-units):读当前→加 delta→写 toDecimal。
- *   用于 global_fund / management_bonus_pool / commission_reserve / charity_fund 等单行池表。
+ *   用于 global_fund / protocol_reserve_pool / commission_reserve / charity_fund 等单行池表。
  *   table / 列名 / whereClause 均为【代码字面量】(非用户输入)→ 无 SQL 注入面。
  *   行不存在 → UPDATE 影响 0 行(与历史相对更新一致)。
  */

package/dist/pwa/admin-audit.js

@@ -0,0 +1,38 @@
+import { generateId } from '../layer0-foundation/L0-1-database/schema.js';
+/** Default context for an action logged without explicit accountability — NOT contribution-eligible. */
+function normalizeContext(ctx) {
+    return {
+        actor_type: ctx?.actorType ?? 'unknown_agent',
+        actor_ref: ctx?.actorRef ?? null,
+        agent_mode: ctx?.agentMode ?? 'unknown_agent',
+        human_authorization_id: ctx?.humanAuthorizationId ?? null,
+        mandate_id: ctx?.mandateId ?? null,
+        approval_kind: ctx?.approvalKind ?? null,
+        conflict_disclosure: ctx?.conflictDisclosure ?? 'unknown',
+        provenance: ctx?.provenance ?? null,
+    };
+}
+/**
+ * Write one admin_audit_log row (with `detail._ctx` accountability context) and return its id. The id
+ * is what the coordination ingestion engine references as `admin_audit_log_id`.
+ */
+export function logAdminAction(db, input) {
+    const id = generateId('audit');
+    const detail = JSON.stringify({ ...(input.detail ?? {}), _ctx: normalizeContext(input.context) });
+    db.prepare(`INSERT INTO admin_audit_log (id, admin_id, action, target_type, target_id, detail) VALUES (?,?,?,?,?,?)`)
+        .run(id, input.adminId, input.action, input.targetType ?? null, input.targetId ?? null, detail);
+    return id;
+}
+/** Read back the accountability context of an audit row. Absent `_ctx` → unknown / not eligible. */
+export function readAdminActionContext(detailJson) {
+    if (!detailJson)
+        return normalizeContext();
+    try {
+        const parsed = JSON.parse(detailJson);
+        const ctx = parsed && typeof parsed === 'object' ? parsed._ctx : undefined;
+        return ctx && typeof ctx === 'object' ? ctx : normalizeContext();
+    }
+    catch {
+        return normalizeContext();
+    }
+}

package/dist/pwa/admin-bearer-auth.js

@@ -0,0 +1,21 @@
+export function resolveBearerProtocolAdmin(db, req, isProtocolAdmin) {
+    const authz = req?.headers?.authorization;
+    if (typeof authz !== 'string' || !authz.startsWith('Bearer '))
+        return null; // Bearer only — NOT req.body.api_key
+    const key = authz.slice('Bearer '.length).trim();
+    if (!key)
+        return null;
+    const u = db.prepare('SELECT * FROM users WHERE api_key = ?').get(key);
+    if (!u)
+        return null;
+    const mod = db.prepare('SELECT suspended FROM user_moderation WHERE user_id = ?').get(u.id);
+    if (mod?.suspended)
+        return null; // suspended admin cannot approve
+    const session = db.prepare('SELECT revoked_at FROM user_sessions WHERE api_key = ? ORDER BY created_at DESC LIMIT 1')
+        .get(key);
+    if (session?.revoked_at)
+        return null; // remotely logged-out session cannot approve
+    if (!isProtocolAdmin(u))
+        return null; // admin role + protocol permission (caller-supplied, central logic)
+    return u;
+}