@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/lanes/tracker-report.js

@@ -0,0 +1,522 @@
+import { LanesError } from "./errors.js";
+import { normalizeIsoTimestamp } from "./timestamp.js";
+function reportError(error, message, details = {}) {
+    throw new LanesError(error, message, details);
+}
+function validTimestamp(value, field, sourcePath, details = {}) {
+    const normalized = normalizeIsoTimestamp(value);
+    if (normalized === null) {
+        return reportError("tracker_report_record_invalid", `${field} must be a valid ISO timestamp`, { field, path: sourcePath, ...details });
+    }
+    return normalized;
+}
+function requireString(record, field) {
+    const value = record[field];
+    if (typeof value !== "string" || value.trim() === "") {
+        return reportError("tracker_report_record_invalid", `${field} must be a non-empty string`, { id: record.id, path: record.source_path, field });
+    }
+    return value;
+}
+function requireNumber(record, field) {
+    const value = record[field];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return reportError("tracker_report_record_invalid", `${field} must be a finite number`, { id: record.id, path: record.source_path, field });
+    }
+    return value;
+}
+function recordInProject(record, company, projectId) {
+    return record.company === company && record.project_id === projectId;
+}
+function approvalState(record) {
+    if (record.status === "approved")
+        return "approved";
+    if (record.status === "proposed")
+        return "proposal";
+    return reportError("tracker_report_record_invalid", "status must be proposed or approved", { id: record.id, path: record.source_path, field: "status" });
+}
+function reportQuestion(question) {
+    const { record, body } = question;
+    if (typeof body.question !== "string" || !body.question.trim()) {
+        return reportError("tracker_report_question_invalid", "Question text must be a non-empty string", { question_id: record.question_id, path: question.source_path });
+    }
+    if (!Array.isArray(body.options) || body.options.some((option) => typeof option !== "string" || !option.trim())) {
+        return reportError("tracker_report_question_invalid", "Question options must be non-empty strings", { question_id: record.question_id, path: question.source_path });
+    }
+    if (body.recommended !== undefined && (typeof body.recommended !== "string" || !body.recommended.trim())) {
+        return reportError("tracker_report_question_invalid", "Question recommendation must be a non-empty string", { question_id: record.question_id, path: question.source_path });
+    }
+    const output = {
+        question_id: record.question_id,
+        question: body.question,
+        asked_at: validTimestamp(record.asked_at, "asked_at", question.source_path),
+        audience: question.current_audience,
+        options: [...body.options],
+    };
+    if (body.recommended !== undefined)
+        output.recommended = body.recommended;
+    if (record.status === "answered") {
+        if (!record.answer || typeof record.answer.choice !== "string" || !record.answer.choice.trim() || typeof record.answer.answered_by !== "string" || !record.answer.answered_by.trim()) {
+            return reportError("tracker_report_question_invalid", "Answered question is missing its answer", { question_id: record.question_id, path: question.source_path });
+        }
+        output.answer = {
+            choice: record.answer.choice,
+            answered_at: validTimestamp(record.answer.answered_at, "answered_at", question.source_path),
+            answered_by: record.answer.answered_by,
+        };
+    }
+    return output;
+}
+function projectQuestions(team, company) {
+    return team.questions.filter(({ record }) => record.company?.slug === company && record.project_id === team.project_id);
+}
+function openBlockers(team, company, throughTime) {
+    return team.blockers
+        .filter((record) => recordInProject(record, company, team.project_id))
+        .filter((record) => {
+        if (record.resolved_at === null)
+            return true;
+        if (typeof record.resolved_at !== "string") {
+            return reportError("tracker_report_record_invalid", "resolved_at must be null or an ISO timestamp", { id: record.id, path: record.source_path, field: "resolved_at" });
+        }
+        return Date.parse(validTimestamp(record.resolved_at, "resolved_at", record.source_path)) > throughTime;
+    })
+        .map((record) => ({
+        id: record.id,
+        story_id: requireString(record, "story_id"),
+        what: requireString(record, "what"),
+        waiting_on: requireString(record, "waiting_on"),
+        next_step: requireString(record, "next_step"),
+        opened_at: validTimestamp(record.opened_at, "opened_at", record.source_path),
+    }))
+        .filter((blocker) => Date.parse(blocker.opened_at) <= throughTime)
+        .sort((a, b) => a.opened_at.localeCompare(b.opened_at) || a.id.localeCompare(b.id));
+}
+function kpiValuesSince(record, sinceTime, throughTime) {
+    const name = requireString(record, "name");
+    const unit = requireString(record, "unit");
+    if (!Array.isArray(record.values)) {
+        return reportError("tracker_report_record_invalid", "values must be an array", { id: record.id, path: record.source_path, field: "values" });
+    }
+    return record.values
+        .map((raw) => {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+            return reportError("tracker_report_record_invalid", "KPI value must be an object", { id: record.id, path: record.source_path, field: "values" });
+        }
+        const value = raw;
+        const at = validTimestamp(value.at, "values[].at", record.source_path);
+        if (typeof value.value !== "number" || !Number.isFinite(value.value) || typeof value.source !== "string") {
+            return reportError("tracker_report_record_invalid", "KPI value needs a finite value and source", { id: record.id, path: record.source_path, field: "values" });
+        }
+        return { at, value: value.value, source: value.source };
+    })
+        .filter((value) => Date.parse(value.at) >= sinceTime && Date.parse(value.at) <= throughTime)
+        .map((value) => ({ kpi_id: record.id, name, at: value.at, value: value.value, unit, source: value.source }))
+        .sort((a, b) => a.at.localeCompare(b.at) || a.kpi_id.localeCompare(b.kpi_id));
+}
+function directiveDecisions(team, company, sinceTime, throughTime) {
+    return team.directives
+        .filter((record) => recordInProject(record, company, team.project_id))
+        .flatMap((record) => {
+        if (!Array.isArray(record.teams) || record.teams.some((item) => typeof item !== "string")) {
+            return reportError("tracker_report_record_invalid", "teams must be an array of team slugs", { id: record.id, path: record.source_path, field: "teams" });
+        }
+        if (!record.teams.includes(team.team))
+            return [];
+        if (!Array.isArray(record.acknowledgements)) {
+            return reportError("tracker_report_record_invalid", "acknowledgements must be an array", { id: record.id, path: record.source_path, field: "acknowledgements" });
+        }
+        const acknowledgements = record.acknowledgements.map((raw) => {
+            if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+                return reportError("tracker_report_record_invalid", "Directive acknowledgement must be an object", { id: record.id, path: record.source_path, field: "acknowledgements" });
+            }
+            const ack = raw;
+            if (typeof ack.team !== "string" || typeof ack.lane_id !== "string") {
+                return reportError("tracker_report_record_invalid", "Directive acknowledgement needs team and lane_id", { id: record.id, path: record.source_path, field: "acknowledgements" });
+            }
+            return { team: ack.team, lane_id: ack.lane_id, at: validTimestamp(ack.at, "acknowledgements[].at", record.source_path) };
+        }).filter((ack) => ack.team === team.team && Date.parse(ack.at) >= sinceTime && Date.parse(ack.at) <= throughTime);
+        const date = requireString(record, "date");
+        const parsedDate = new Date(`${date}T00:00:00.000Z`);
+        if (!/^\d{4}-\d\d-\d\d$/.test(date) || !Number.isFinite(parsedDate.getTime()) || parsedDate.toISOString().slice(0, 10) !== date) {
+            return reportError("tracker_report_record_invalid", "date must be a calendar date in YYYY-MM-DD form", { id: record.id, path: record.source_path, field: "date" });
+        }
+        const createdAt = validTimestamp(record.created_at, "created_at", record.source_path);
+        if (Date.parse(createdAt) > throughTime)
+            return [];
+        if (Date.parse(createdAt) < sinceTime && acknowledgements.length === 0)
+            return [];
+        return {
+            id: record.id,
+            text: requireString(record, "text"),
+            date,
+            acknowledgements: acknowledgements.sort((a, b) => a.at.localeCompare(b.at) || a.lane_id.localeCompare(b.lane_id)),
+        };
+    })
+        .sort((a, b) => a.date.localeCompare(b.date) || a.id.localeCompare(b.id));
+}
+function storyActivity(team, sinceTime, throughTime) {
+    return team.stories
+        .filter((story) => story.status === "done")
+        .map((story) => ({ story, at: validTimestamp(story.updated_at, "updated_at", story.source_path, { story_id: story.id }) }))
+        .filter(({ at }) => Date.parse(at) >= sinceTime && Date.parse(at) <= throughTime)
+        .map(({ story, at }) => ({ id: story.id, title: story.title, at, references: [...(story.references ?? [])] }))
+        .sort((a, b) => a.at.localeCompare(b.at) || a.id.localeCompare(b.id));
+}
+function pullRequestActivity(team, sinceTime, throughTime) {
+    return team.pull_requests
+        .map((pr) => ({ ...pr, merged_at: validTimestamp(pr.merged_at, "merged_at", pr.source_path) }))
+        .filter((pr) => Date.parse(pr.merged_at) >= sinceTime && Date.parse(pr.merged_at) <= throughTime)
+        .map(({ number, title, merged_at }) => ({ number, title, merged_at }))
+        .sort((a, b) => a.merged_at.localeCompare(b.merged_at) || a.number.localeCompare(b.number));
+}
+function releaseActivity(team, sinceTime, throughTime) {
+    return team.releases
+        .map((release) => ({ ...release, released_at: validTimestamp(release.released_at, "released_at", release.source_path) }))
+        .filter((release) => Date.parse(release.released_at) >= sinceTime && Date.parse(release.released_at) <= throughTime)
+        .map(({ version, released_at }) => ({ version, released_at }))
+        .sort((a, b) => a.released_at.localeCompare(b.released_at) || a.version.localeCompare(b.version));
+}
+function teamOwnerReport(team, company, sinceTime, throughTime) {
+    const questions = projectQuestions(team, company);
+    const answeredQuestions = questions
+        .filter(({ record }) => record.status === "answered")
+        .map(reportQuestion)
+        .filter((question) => question.answer !== undefined && Date.parse(question.answer.answered_at) >= sinceTime && Date.parse(question.answer.answered_at) <= throughTime)
+        .sort((a, b) => a.answer.answered_at.localeCompare(b.answer.answered_at) || a.question_id.localeCompare(b.question_id));
+    const waitingQuestions = questions
+        .filter(({ record, current_audience }) => record.status === "pending" && current_audience === "owner")
+        .map(reportQuestion)
+        .filter((question) => Date.parse(question.asked_at) <= throughTime)
+        .sort((a, b) => a.asked_at.localeCompare(b.asked_at) || a.question_id.localeCompare(b.question_id));
+    const kpiValues = team.kpis
+        .filter((record) => recordInProject(record, company, team.project_id))
+        .flatMap((record) => kpiValuesSince(record, sinceTime, throughTime));
+    return {
+        team: team.team,
+        project_id: team.project_id,
+        errors: [...(team.errors ?? [])],
+        progress: {
+            stories_moved_to_done: storyActivity(team, sinceTime, throughTime),
+            pull_requests_merged: pullRequestActivity(team, sinceTime, throughTime),
+            releases: releaseActivity(team, sinceTime, throughTime),
+            kpi_values: kpiValues.sort((a, b) => a.at.localeCompare(b.at) || a.kpi_id.localeCompare(b.kpi_id)),
+        },
+        questions_waiting_on_owner: waitingQuestions,
+        open_blockers: openBlockers(team, company, throughTime),
+        decisions: {
+            directives: directiveDecisions(team, company, sinceTime, throughTime),
+            answered_questions: answeredQuestions,
+        },
+    };
+}
+function validateTeamIdentity(team) {
+    if (!team.team.trim() || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(team.team)) {
+        reportError("tracker_report_team_invalid", "Team slug must be a safe path segment", { team: team.team });
+    }
+    if (!team.project_id.trim() || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(team.project_id)) {
+        reportError("tracker_report_team_invalid", "Project slug must be a safe path segment", { team: team.team, project_id: team.project_id });
+    }
+}
+function validatedWindow(input) {
+    const sourcePath = "<report arguments>";
+    const generatedAt = validTimestamp(input.generated_at, "generated_at", sourcePath);
+    const since = validTimestamp(input.since, "since", sourcePath);
+    const generatedAtTime = Date.parse(generatedAt);
+    const sinceTime = Date.parse(since);
+    if (sinceTime > generatedAtTime) {
+        reportError("tracker_report_window_invalid", "since must not be later than generated_at", { since, generated_at: generatedAt });
+    }
+    if (!input.company.trim() || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(input.company)) {
+        reportError("tracker_report_company_invalid", "Company slug must be a safe path segment", { company: input.company });
+    }
+    return { generatedAt, since, sinceTime, generatedAtTime };
+}
+function removeInvalidEntity(team, err) {
+    if (!(err instanceof LanesError))
+        return null;
+    const details = err.details;
+    const path = typeof details.path === "string" ? details.path : "<unknown tracker record>";
+    const field = typeof details.field === "string" ? details.field : "record";
+    const message = err.message;
+    const storyId = typeof details.story_id === "string" ? details.story_id : undefined;
+    const recordId = typeof details.id === "string" ? details.id : undefined;
+    const questionId = typeof details.question_id === "string" ? details.question_id : undefined;
+    let next = team;
+    if (storyId) {
+        const stories = team.stories.filter((story) => story.id !== storyId || (path !== "<unknown tracker record>" && story.source_path !== path));
+        if (stories.length === team.stories.length)
+            return null;
+        next = { ...next, stories };
+    }
+    else if (questionId) {
+        const questions = team.questions.filter(({ record, source_path }) => record.question_id !== questionId || source_path !== path);
+        if (questions.length === team.questions.length)
+            return null;
+        next = { ...next, questions };
+    }
+    else if (recordId) {
+        const remove = (records) => records.filter((record) => record.id !== recordId || record.source_path !== path);
+        const blockers = remove(team.blockers);
+        const kpis = remove(team.kpis);
+        const okrs = remove(team.okrs);
+        const directives = remove(team.directives);
+        if ([blockers, kpis, okrs, directives].every((records, index) => records.length === [team.blockers, team.kpis, team.okrs, team.directives][index].length))
+            return null;
+        next = { ...next, blockers, kpis, okrs, directives };
+    }
+    else if (err.error === "tracker_report_record_invalid" && path !== "<unknown tracker record>") {
+        const pullRequests = team.pull_requests.filter((record) => record.source_path !== path);
+        const releases = team.releases.filter((record) => record.source_path !== path);
+        if (pullRequests.length === team.pull_requests.length && releases.length === team.releases.length)
+            return null;
+        next = { ...next, pull_requests: pullRequests, releases };
+    }
+    else {
+        return null;
+    }
+    return {
+        team: next,
+        issue: {
+            path,
+            field,
+            message,
+            ...(storyId ? { story_id: storyId } : {}),
+            ...(recordId ? { record_id: recordId } : {}),
+            ...(questionId ? { question_id: questionId } : {}),
+        },
+    };
+}
+function withRecoverableTeamErrors(team, project) {
+    let current = team;
+    const errors = [...(team.errors ?? [])];
+    const attempts = team.stories.length + team.questions.length + team.blockers.length + team.kpis.length + team.okrs.length + team.directives.length + team.pull_requests.length + team.releases.length + 1;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        try {
+            return project({ ...current, errors });
+        }
+        catch (err) {
+            const recovery = removeInvalidEntity(current, err);
+            if (!recovery)
+                throw err;
+            errors.push(recovery.issue);
+            current = recovery.team;
+        }
+    }
+    return reportError("tracker_report_recovery_exhausted", "Could not isolate malformed tracker records", { path: "<team report>", field: "record" });
+}
+/** Pure report projection. The caller owns loading, tenant checks, body reads and report-time persistence. */
+export function buildTrackerOwnerReport(input) {
+    const window = validatedWindow(input);
+    const eligibleTeams = input.teams.filter((team) => team.company === input.company);
+    const seen = new Set();
+    for (const team of eligibleTeams) {
+        validateTeamIdentity(team);
+        if (seen.has(team.team)) {
+            reportError("tracker_report_team_ambiguous", "More than one report input maps to the same team", { team: team.team });
+        }
+        seen.add(team.team);
+    }
+    return {
+        schema_version: "hq-lanes-owner-report.v1",
+        company: input.company,
+        generated_at: window.generatedAt,
+        since: window.since,
+        since_source: input.since_source,
+        teams: eligibleTeams
+            .map((team) => withRecoverableTeamErrors(team, (safeTeam) => teamOwnerReport(safeTeam, input.company, window.sinceTime, window.generatedAtTime)))
+            .sort((a, b) => a.team.localeCompare(b.team)),
+    };
+}
+function teamKpis(team, company, throughTime) {
+    return team.kpis
+        .filter((record) => recordInProject(record, company, team.project_id))
+        .map((record) => {
+        const name = requireString(record, "name");
+        const definition = requireString(record, "definition");
+        const unit = requireString(record, "unit");
+        const target = requireNumber(record, "target");
+        if (record.direction !== "up" && record.direction !== "down") {
+            return reportError("tracker_report_record_invalid", "direction must be up or down", { id: record.id, path: record.source_path, field: "direction" });
+        }
+        const direction = record.direction;
+        if (!Array.isArray(record.values)) {
+            return reportError("tracker_report_record_invalid", "values must be an array", { id: record.id, path: record.source_path, field: "values" });
+        }
+        const values = record.values.map((raw) => {
+            if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+                return reportError("tracker_report_record_invalid", "KPI value must be an object", { id: record.id, path: record.source_path, field: "values" });
+            }
+            const value = raw;
+            if (typeof value.value !== "number" || !Number.isFinite(value.value) || typeof value.source !== "string") {
+                return reportError("tracker_report_record_invalid", "KPI value needs a finite value and source", { id: record.id, path: record.source_path, field: "values" });
+            }
+            return { at: validTimestamp(value.at, "values[].at", record.source_path), value: value.value, source: value.source };
+        }).filter((value) => Date.parse(value.at) <= throughTime).sort((a, b) => a.at.localeCompare(b.at));
+        const recent = values.slice(-3);
+        const previous = recent.length > 1 ? recent[recent.length - 2].value : null;
+        const latest = recent[recent.length - 1] ?? null;
+        const change = latest && previous !== null ? latest.value - previous : null;
+        const progress = change === null ? null : direction === "up" ? change : -change;
+        const trend = progress === null ? "insufficient_data" : progress > 0 ? "improving" : progress < 0 ? "regressing" : "flat";
+        return {
+            id: record.id,
+            name,
+            definition,
+            unit,
+            target,
+            direction,
+            status: approvalState(record),
+            latest_value: latest,
+            recent_values: recent,
+            trend,
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+}
+function teamOkrs(team, company) {
+    return team.okrs
+        .filter((record) => recordInProject(record, company, team.project_id))
+        .map((record) => {
+        const objective = requireString(record, "objective");
+        const period = requireString(record, "period");
+        if (!Array.isArray(record.key_results)) {
+            return reportError("tracker_report_record_invalid", "key_results must be an array", { id: record.id, path: record.source_path, field: "key_results" });
+        }
+        const keyResults = record.key_results.map((raw) => {
+            if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+                return reportError("tracker_report_record_invalid", "OKR key result must be an object", { id: record.id, path: record.source_path, field: "key_results" });
+            }
+            const result = raw;
+            if (typeof result.text !== "string" || typeof result.kpi_id !== "string" || typeof result.target !== "number" || !Number.isFinite(result.target)) {
+                return reportError("tracker_report_record_invalid", "OKR key result needs text, kpi_id and finite target", { id: record.id, path: record.source_path, field: "key_results" });
+            }
+            return { text: result.text, kpi_id: result.kpi_id, target: result.target };
+        });
+        return { id: record.id, objective, period, status: approvalState(record), key_results: keyResults };
+    })
+        .sort((a, b) => a.period.localeCompare(b.period) || a.id.localeCompare(b.id));
+}
+function pendingTeamQuestions(team, company, throughTime) {
+    return projectQuestions(team, company)
+        .filter(({ record }) => record.status === "pending")
+        .map(reportQuestion)
+        .filter((question) => Date.parse(question.asked_at) <= throughTime)
+        .sort((a, b) => a.asked_at.localeCompare(b.asked_at) || a.question_id.localeCompare(b.question_id));
+}
+/** Pure team page projection for already loaded, company-checked records. */
+export function buildTrackerTeamPage(team, company, sinceValue, generatedAtValue) {
+    const since = validTimestamp(sinceValue, "since", "<report arguments>");
+    const generatedAt = validTimestamp(generatedAtValue, "generated_at", "<report arguments>");
+    const sinceTime = Date.parse(since);
+    const generatedAtTime = Date.parse(generatedAt);
+    if (sinceTime > generatedAtTime) {
+        reportError("tracker_report_window_invalid", "since must not be later than generated_at", { since, generated_at: generatedAt });
+    }
+    return withRecoverableTeamErrors(team, (safeTeam) => {
+        if (safeTeam.company !== company) {
+            reportError("tracker_company_mismatch", "Team page data does not belong to the resolved company", { active_company: company, record_company: safeTeam.company });
+        }
+        validateTeamIdentity(safeTeam);
+        const workInProgress = safeTeam.stories
+            .filter((story) => story.status !== "done" && story.status !== "dropped")
+            .map((story) => {
+            if (!["queued", "in_progress", "review"].includes(story.status)) {
+                return reportError("tracker_report_story_invalid", "Story status is not in the tracker vocabulary", { story_id: story.id, path: story.source_path, field: "status", status: story.status });
+            }
+            return {
+                id: story.id,
+                title: story.title,
+                status: story.status,
+                references: [...(story.references ?? [])],
+                updated_at: story.updated_at,
+                source_path: story.source_path,
+            };
+        })
+            .filter((story) => story.updated_at === undefined || Date.parse(validTimestamp(story.updated_at, "updated_at", story.source_path, { story_id: story.id })) <= generatedAtTime)
+            .map(({ id, title, status, references }) => ({ id, title, status, references }))
+            .sort((a, b) => a.id.localeCompare(b.id));
+        return {
+            schema_version: "hq-lanes-team-page.v1",
+            company,
+            team: safeTeam.team,
+            project_id: safeTeam.project_id,
+            since,
+            errors: [...(safeTeam.errors ?? [])],
+            okrs: teamOkrs(safeTeam, company),
+            kpis: teamKpis(safeTeam, company, generatedAtTime),
+            work_in_progress: workInProgress,
+            work_done_since: storyActivity(safeTeam, sinceTime, generatedAtTime),
+            blockers: openBlockers(safeTeam, company, generatedAtTime),
+            questions: pendingTeamQuestions(safeTeam, company, generatedAtTime),
+        };
+    });
+}
+function listOrNone(items, render) {
+    return items.length ? items.map((item) => `  - ${render(item)}`) : ["  - none"];
+}
+/** Human-readable owner report, rendered without editing after the command runs. */
+export function renderTrackerOwnerReportText(report) {
+    const lines = [
+        `Owner report for ${report.company}`,
+        `Reporting window: ${report.since} through ${report.generated_at} (${report.since_source.replaceAll("_", " ")})`,
+    ];
+    for (const team of report.teams) {
+        lines.push("", `${team.team} (${team.project_id})`, "Progress:", "  Stories moved to done:");
+        lines.push(...listOrNone(team.progress.stories_moved_to_done, (story) => `${story.id} — ${story.title} (${story.at})${story.references.length ? `; references: ${story.references.join(", ")}` : ""}`));
+        lines.push("  Pull requests merged:");
+        lines.push(...listOrNone(team.progress.pull_requests_merged, (pr) => `#${pr.number} — ${pr.title} (${pr.merged_at})`));
+        lines.push("  Releases:");
+        lines.push(...listOrNone(team.progress.releases, (release) => `${release.version} (${release.released_at})`));
+        lines.push("  KPI values recorded:");
+        lines.push(...listOrNone(team.progress.kpi_values, (value) => `${value.name}: ${value.value} ${value.unit} (${value.at}; source: ${value.source})`));
+        lines.push("Questions waiting on the owner:");
+        lines.push(...listOrNone(team.questions_waiting_on_owner, (question) => {
+            const recommendation = question.recommended ? `; recommendation: ${question.recommended}` : "";
+            return `${question.question_id} — ${question.question}; options: ${question.options.join(" | ")}${recommendation}`;
+        }));
+        lines.push("Open blockers:");
+        lines.push(...listOrNone(team.open_blockers, (blocker) => `${blocker.id} — ${blocker.what}; waiting on ${blocker.waiting_on}; next: ${blocker.next_step}`));
+        lines.push("Decisions taken:");
+        const decisions = [
+            ...team.decisions.directives.map((directive) => {
+                const acknowledgements = directive.acknowledgements.length
+                    ? directive.acknowledgements.map((ack) => `${ack.team}/${ack.lane_id} (${ack.at})`).join(", ")
+                    : "none";
+                return `Directive ${directive.id} (${directive.date}): ${directive.text}; acknowledgements: ${acknowledgements}`;
+            }),
+            ...team.decisions.answered_questions.map((question) => `Question ${question.question_id} answered ${question.answer.choice} by ${question.answer.answered_by} (${question.answer.answered_at}): ${question.question}`),
+        ];
+        lines.push(...(decisions.length ? decisions.map((decision) => `  - ${decision}`) : ["  - none"]));
+        lines.push("Errors:");
+        lines.push(...listOrNone(team.errors, (issue) => `${issue.path} — ${issue.story_id ? `story ${issue.story_id}` : issue.record_id ? `record ${issue.record_id}` : issue.question_id ? `question ${issue.question_id}` : "record"}; ${issue.field}: ${issue.message}`));
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Human-readable team page, with proposal status visible beside each objective and KPI. */
+export function renderTrackerTeamPageText(page) {
+    const lines = [`Team page for ${page.team}`, `Company: ${page.company}`, `Work completed since: ${page.since}`, "OKRs:"];
+    lines.push(...listOrNone(page.okrs, (okr) => {
+        const label = okr.status === "proposal" ? "Proposal: " : "";
+        const results = okr.key_results.map((result) => `${result.text} (target ${result.target}; KPI ${result.kpi_id})`).join("; ");
+        return `${label}${okr.objective} [${okr.period}]${results ? ` — ${results}` : ""}`;
+    }));
+    lines.push("KPIs:");
+    lines.push(...listOrNone(page.kpis, (kpi) => {
+        const label = kpi.status === "proposal" ? "Proposal: " : "";
+        const latest = kpi.latest_value ? `${kpi.latest_value.value} ${kpi.unit}` : "no values";
+        const values = kpi.recent_values.map((value) => `${value.value} (${value.at})`).join(" → ") || "none";
+        return `${label}${kpi.name}: ${latest} / target ${kpi.target} ${kpi.unit}; trend ${kpi.trend} (${values})`;
+    }));
+    lines.push("Work in progress:");
+    lines.push(...listOrNone(page.work_in_progress, (story) => `${story.id} — ${story.title} [${story.status}]${story.references.length ? `; references: ${story.references.join(", ")}` : ""}`));
+    lines.push("Work done since the last report:");
+    lines.push(...listOrNone(page.work_done_since, (story) => `${story.id} — ${story.title} (${story.at})${story.references.length ? `; references: ${story.references.join(", ")}` : ""}`));
+    lines.push("Open blockers:");
+    lines.push(...listOrNone(page.blockers, (blocker) => `${blocker.id} — ${blocker.what}; next: ${blocker.next_step}`));
+    lines.push("Open questions:");
+    lines.push(...listOrNone(page.questions, (question) => `${question.question_id} — ${question.question} [${question.audience}]`));
+    lines.push("Errors:");
+    lines.push(...listOrNone(page.errors, (issue) => `${issue.path} — ${issue.story_id ? `story ${issue.story_id}` : issue.record_id ? `record ${issue.record_id}` : issue.question_id ? `question ${issue.question_id}` : "record"}; ${issue.field}: ${issue.message}`));
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=tracker-report.js.map

package/dist/lib/lanes/tracker-store.d.ts

@@ -0,0 +1,18 @@
+export type TrackerKind = "blocker" | "kpi" | "okr" | "directive";
+export interface TrackerRecord {
+    schema_version: "hq-lanes-tracker-record.v1";
+    kind: TrackerKind;
+    id: string;
+    company: string;
+    project_id: string;
+    version: number;
+    created_at: string;
+    updated_at: string;
+    [key: string]: unknown;
+}
+export interface LocalTrackerStore {
+    read(kind: TrackerKind, id: string): TrackerRecord | null;
+    list(kind: TrackerKind): TrackerRecord[];
+}
+export declare function createLocalTrackerStore(projectDirectory: string): LocalTrackerStore;
+//# sourceMappingURL=tracker-store.d.ts.map

package/dist/lib/lanes/tracker-store.js

@@ -0,0 +1,106 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { LanesError } from "./errors.js";
+const KIND_SET = new Set(["blocker", "kpi", "okr", "directive"]);
+const ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+function storeError(error, message, details = {}) {
+    return new LanesError(error, message, details);
+}
+function validateId(id) {
+    if (!ID_RE.test(id) || id === "." || id === "..") {
+        throw storeError("tracker_id_invalid", "Tracker record id must be a safe path segment", { id });
+    }
+}
+function recordPath(root, kind, id) {
+    validateId(id);
+    if (!KIND_SET.has(kind))
+        throw storeError("tracker_kind_invalid", "Unknown tracker record kind", { kind });
+    return path.join(root, kind, `${id}.json`);
+}
+function existingKindDirectory(root, kind) {
+    try {
+        const rootStat = fs.lstatSync(root);
+        if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+            throw storeError("tracker_store_path_invalid", "Tracker storage path must be a real directory", { path: root });
+        }
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    const directory = path.join(root, kind);
+    try {
+        const kindStat = fs.lstatSync(directory);
+        if (!kindStat.isDirectory() || kindStat.isSymbolicLink()) {
+            throw storeError("tracker_store_path_invalid", "Tracker kind path must be a real directory", { path: directory });
+        }
+        return directory;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+function parseRecord(text, expectedKind, id, file) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw storeError("tracker_record_malformed", "Tracker record contains invalid JSON", { kind: expectedKind, id, path: file });
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw storeError("tracker_record_invalid", "Tracker record must be a JSON object", { kind: expectedKind, id, path: file });
+    }
+    const record = value;
+    if (record.schema_version !== "hq-lanes-tracker-record.v1" ||
+        record.kind !== expectedKind ||
+        record.id !== id ||
+        typeof record.company !== "string" || !record.company ||
+        typeof record.project_id !== "string" || !record.project_id ||
+        !Number.isSafeInteger(record.version) || (record.version ?? 0) < 1 ||
+        typeof record.created_at !== "string" || typeof record.updated_at !== "string") {
+        throw storeError("tracker_record_invalid", "Tracker record is missing valid common fields", { kind: expectedKind, id, path: file });
+    }
+    return record;
+}
+export function createLocalTrackerStore(projectDirectory) {
+    const root = path.join(projectDirectory, "tracker");
+    const read = (kind, id) => {
+        const file = recordPath(root, kind, id);
+        let text;
+        try {
+            const stat = fs.lstatSync(file);
+            if (!stat.isFile() || stat.isSymbolicLink()) {
+                throw storeError("tracker_record_invalid", "Tracker record path must be a regular file", { kind, id, path: file });
+            }
+            text = fs.readFileSync(file, "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        return parseRecord(text, kind, id, file);
+    };
+    return {
+        read,
+        list(kind) {
+            const directory = existingKindDirectory(root, kind);
+            if (directory === null)
+                return [];
+            return fs.readdirSync(directory)
+                .filter((name) => name.endsWith(".json"))
+                .sort()
+                .map((name) => {
+                const id = name.slice(0, -5);
+                return read(kind, id);
+            })
+                .filter((record) => record !== null)
+                .sort((a, b) => b.updated_at.localeCompare(a.updated_at) || a.id.localeCompare(b.id));
+        },
+    };
+}
+//# sourceMappingURL=tracker-store.js.map