light-plan 0.0.0-stage → 0.1.0

package/dist/core/model/links.js

@@ -0,0 +1,114 @@
+/**
+ * id -> the ids that gate it, restricted to ids that actually exist.
+ *
+ * `depends_on` is the only gating edge: it says the work cannot start until
+ * something else is finished, and `nextTasks` withholds the issue while it is
+ * open. `relates_to` implies nothing and is deliberately absent — a loop of
+ * associations is not a stall.
+ */
+function adjacency(issues) {
+    const known = new Set(issues.map((issue) => issue.id));
+    const graph = new Map();
+    for (const issue of issues) {
+        graph.set(issue.id, issue.depends_on.filter((target) => known.has(target) && target !== issue.id));
+    }
+    return graph;
+}
+/** Rotate so the smallest id comes first, giving one stable key per cycle. */
+function canonicalKey(cycle) {
+    let pivot = 0;
+    for (let index = 1; index < cycle.length; index += 1) {
+        if (cycle[index] < cycle[pivot])
+            pivot = index;
+    }
+    return [...cycle.slice(pivot), ...cycle.slice(0, pivot)].join('>');
+}
+/**
+ * Every distinct cycle in a gating graph, each reported once. Members are
+ * listed in traversal order and do not repeat the entry point.
+ *
+ * Takes the graph rather than building one, because `check` runs it over the
+ * *inherited* edges (a story waits on what its feature waits on) while `link`
+ * runs it over the written ones. Same algorithm, two graphs, one implementation.
+ */
+export function findCyclesIn(graph, order) {
+    const state = new Map();
+    const stack = [];
+    const cycles = new Map();
+    const visit = (node) => {
+        state.set(node, 'open');
+        stack.push(node);
+        for (const next of graph.get(node) ?? []) {
+            const seen = state.get(next);
+            if (seen === 'open') {
+                const start = stack.indexOf(next);
+                if (start >= 0) {
+                    const cycle = stack.slice(start);
+                    const key = canonicalKey(cycle);
+                    if (!cycles.has(key))
+                        cycles.set(key, cycle);
+                }
+            }
+            else if (seen === undefined) {
+                visit(next);
+            }
+        }
+        stack.pop();
+        state.set(node, 'done');
+    };
+    for (const id of order) {
+        if (!state.has(id))
+            visit(id);
+    }
+    return [...cycles.values()];
+}
+/** Every distinct cycle in the edges as written, for `link` and for tests. */
+export function findDependencyCycles(issues) {
+    return findCyclesIn(adjacency(issues), issues.map((issue) => issue.id));
+}
+function findPath(graph, from, to) {
+    const previous = new Map();
+    const queue = [from];
+    const seen = new Set([from]);
+    while (queue.length) {
+        const node = queue.shift();
+        if (node === to) {
+            const path = [node];
+            let cursor = node;
+            while (previous.has(cursor)) {
+                cursor = previous.get(cursor);
+                path.unshift(cursor);
+            }
+            return path;
+        }
+        for (const next of graph.get(node) ?? []) {
+            if (seen.has(next))
+                continue;
+            seen.add(next);
+            previous.set(next, node);
+            queue.push(next);
+        }
+    }
+    return null;
+}
+/**
+ * The cycle that adding a gating edge from `from` to `to` would create, or null
+ * if it is safe. Lets `lpm link` reject a bad edge instead of writing it and
+ * having `lpm check` complain afterwards.
+ *
+ * Works against typed engine documents with a BFS through an adjacency graph.
+ * `src/shared/plans/reading.ts` carries the DTO-shaped copy, which works
+ * against the flat `BoardView` record with a recursive DFS. Both ask the same
+ * question; they differ in data shape and algorithm, which is why they stay
+ * duplicated. When one changes, the other must follow.
+ */
+export function wouldCycle(issues, from, to) {
+    if (from === to)
+        return [from];
+    const path = findPath(adjacency(issues), to, from);
+    return path ? [from, ...path.slice(0, -1)] : null;
+}
+export function formatCycle(cycle) {
+    return [...cycle, cycle[0]].join(' -> ');
+}
+//# sourceMappingURL=links.js.map

package/dist/core/model/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../../src/core/model/links.ts"],"names":[],"mappings":"AAWA;;;;;;;GAOG;AACH,SAAS,SAAS,CAAC,MAAwB;IACzC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC1C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,KAAK,CAAC,GAAG,CACP,KAAK,CAAC,EAAE,EACR,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,MAAM,KAAK,KAAK,CAAC,EAAE,CAAC,CAC9E,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,SAAS,YAAY,CAAC,KAAe;IACnC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACrD,IAAI,KAAK,CAAC,KAAK,CAAE,GAAG,KAAK,CAAC,KAAK,CAAE;YAAE,KAAK,GAAG,KAAK,CAAC;IACnD,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAA4B,EAAE,KAAe;IACxE,MAAM,KAAK,GAAG,IAAI,GAAG,EAA2B,CAAC;IACjD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE3C,MAAM,KAAK,GAAG,CAAC,IAAY,EAAQ,EAAE;QACnC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACzC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC7B,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;gBACpB,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAClC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;oBACf,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;oBACjC,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;oBAChC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;wBAAE,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;gBAC/C,CAAC;YACH,CAAC;iBAAM,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC9B,KAAK,CAAC,IAAI,CAAC,CAAC;YACd,CAAC;QACH,CAAC;QACD,KAAK,CAAC,GAAG,EAAE,CAAC;QACZ,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1B,CAAC,CAAC;IAEF,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,KAAK,CAAC,EAAE,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,oBAAoB,CAAC,MAAwB;IAC3D,OAAO,YAAY,CACjB,SAAS,CAAC,MAAM,CAAC,EACjB,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAChC,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,KAA4B,EAAE,IAAY,EAAE,EAAU;IACtE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC;IACrB,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAE7B,OAAO,KAAK,CAAC,MAAM,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;QAC5B,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;YAChB,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;YACpB,IAAI,MAAM,GAAG,IAAI,CAAC;YAClB,OAAO,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5B,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC;gBAC/B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACvB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACzC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC7B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACf,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACzB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,MAAwB,EAAE,IAAY,EAAE,EAAU;IAC3E,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;IACnD,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAe;IACzC,OAAO,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC3C,CAAC"}

package/dist/core/model/profile.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A developer's profile: who they are, and which part of the board is theirs.
+ *
+ * A profile is not board truth. It lives in a file outside `.lpm` that one
+ * person is handed, and it answers a question the board deliberately does not:
+ * of everything on it, what should be *offered* to this person. Nothing in
+ * `board/` or `validation/` may read one — a board that validated differently
+ * depending on who was looking would not be one board.
+ *
+ * Every field is optional and an absent field means "no opinion", which is why
+ * `under?: string[]` rather than `under: string[]`: a declared-but-empty list
+ * ("scope me to these zero epics") is a different claim from an absent one.
+ */
+export interface ProfileScope {
+    /** Only work at or below these documents. */
+    under?: string[];
+    /** Never these documents, nor anything below them. Wins over `under`. */
+    exclude?: string[];
+    /** Only issues of these types. */
+    types?: string[];
+    /** Only work scheduled in these periods, or in a period below one of them. */
+    periods?: string[];
+}
+export interface Profile {
+    /** The roster entry this developer acts as: an id or a name. */
+    user: string | null;
+    scope: ProfileScope;
+}
+export declare function emptyProfile(): Profile;
+/** True when a scope declares nothing, so the whole board is in it. */
+export declare function isEmptyScope(scope: ProfileScope): boolean;

package/dist/core/model/profile.js

@@ -0,0 +1,8 @@
+export function emptyProfile() {
+    return { user: null, scope: {} };
+}
+/** True when a scope declares nothing, so the whole board is in it. */
+export function isEmptyScope(scope) {
+    return !scope.under && !scope.exclude && !scope.types && !scope.periods;
+}
+//# sourceMappingURL=profile.js.map

package/dist/core/model/profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.js","sourceRoot":"","sources":["../../../src/core/model/profile.ts"],"names":[],"mappings":"AA8BA,MAAM,UAAU,YAAY;IAC1B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AACnC,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,YAAY,CAAC,KAAmB;IAC9C,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;AAC1E,CAAC"}

package/dist/core/model/types.d.ts

@@ -0,0 +1,441 @@
+import type { ParamDefs } from '../../shared/template-params.js';
+export { DERIVED_FLAG, isDerivedFlag } from '../../shared/flag-rollup.js';
+export type { ParamDef, ParamDefs } from '../../shared/template-params.js';
+/** Attribute value kinds a board config may declare. Deliberately small. */
+export declare const ATTRIBUTE_TYPES: readonly ["string", "text", "int", "float", "bool", "date", "enum", "array"];
+export type AttributeType = (typeof ATTRIBUTE_TYPES)[number];
+export interface AttributeDef {
+    type: AttributeType;
+    description?: string;
+    required?: boolean;
+    default?: unknown;
+    /** Allowed values, required for (and only for) `enum`. */
+    values?: string[];
+}
+/** Shared shape of an issue type, a period type and a resource type. */
+export interface TypeDef {
+    label: string;
+    attributes: Record<string, AttributeDef>;
+    /** Markdown scaffolding written into new documents of this type. */
+    body: string;
+    /**
+     * Resource types only: documents of this type are a pool ("a jr. developer"),
+     * not a named person. Whether a resource is generic is a property of its type,
+     * so no document has to declare it.
+     */
+    generic?: boolean;
+    /**
+     * Issue types only: work of this type is taken whole. It is offered by the
+     * queue even when it has children, and nothing nested inside it is offered
+     * separately -- the children are its checklist, not somebody else's ticket.
+     * Absent means the old rule: only issues with no children are work.
+     */
+    atomic?: boolean;
+}
+export interface StatusDef {
+    id: string;
+    label: string;
+    /** Marks a column as an end state (e.g. Done). */
+    terminal?: boolean;
+    /** Marks a column as work in progress, for `lpm task current` / `start`. */
+    active?: boolean;
+}
+/** Which way a remote syncs. `both` runs the two planners in turn. */
+export type RemoteDirection = 'both' | 'push' | 'pull';
+/**
+ * What to do when one side deletes a document the other side still mirrors.
+ * The single policy reads in both directions, with the value set the two
+ * directions need between them:
+ *
+ * - **Pull side** (the remote twin is confirmed gone — LP-365): `unlink`
+ *   decouples the local document (a tombstone, so the next sync never
+ *   re-files it); `close` moves it to the board's terminal status and
+ *   decouples it; `delete` removes it through the ordinary `remove`
+ *   operation; `restore` re-files it upstream under a new remote id and
+ *   re-links; `manual` moves neither side and reports the document as
+ *   conflicted for a human to settle.
+ *
+ * - **Push side** (the local document is deleted, or leaves the remote's
+ *   `scope:` — LP-351): `unlink` (the default) leaves the remote twin alone
+ *   and drops the link; `close` closes the twin and posts a comment saying
+ *   why; `delete` deletes the twin, only where the platform allows and only
+ *   with confirmation every run — it is never satisfied by a remembered
+ *   consent. `restore` and `manual` have no push-side meaning and fall back
+ *   to `unlink`, so a value meant for the pull side can never delete or close
+ *   upstream by surprise.
+ */
+export type RemoteOnDelete = 'unlink' | 'close' | 'delete' | 'restore' | 'manual';
+/** How a field both sides edited is resolved. */
+export type RemoteConflictPolicy = 'manual' | 'local' | 'remote';
+/**
+ * Which side wins a field both sides edited, declared as a per-field override
+ * (`fields: { status: { owner: remote } }`). A field with an owner never
+ * conflicts — the owner simply wins. `manual` is deliberately not one of
+ * these: an owner names a winner, and `manual` is the *absence* of one, which
+ * the remote's default `conflict` policy already expresses.
+ */
+export type RemoteFieldOwner = 'local' | 'remote';
+/**
+ * Where fields the remote cannot hold natively are encoded: a managed block
+ * in the issue body (the default), or a managed comment when the body is not
+ * writable. Core validates the spelling; `src/remote` acts on it.
+ */
+export type RemoteEncoding = 'block' | 'comment';
+/**
+ * How user comments sync (LP-316). `push` (the default) sends new local
+ * comments upstream and never pulls remote ones down; `both` does that and
+ * also appends remote comments to `_comments.md` on pull. Comment sync is a
+ * side channel — comments are not board state — so it follows the remote's
+ * `direction` (a `pull` remote never pushes comments, a `push` remote never
+ * pulls them) and the mode only widens what a direction already allows.
+ */
+export type RemoteCommentsMode = 'push' | 'both';
+/**
+ * One declared remote, as core stores it after validating the *frame*.
+ *
+ * Core knows a remote has a name, a provider, a scope, a direction and two
+ * policies — it never knows what a provider is. `connection` and `mapping` are
+ * opaque records here; the provider's own schema validates their contents when
+ * the remote is opened (`src/remote/remotes.ts`), exactly as `storage/views.ts`
+ * owns the contents of a view file while core owns the file itself.
+ */
+export interface RemoteConfig {
+    /** Provider name, resolved to an implementation when the remote is opened. */
+    provider: string;
+    /** Issue id at the root of the mirrored subtree; absent means the whole board. */
+    scope?: string;
+    /** Which direction the sync runs. Defaults to `both`. */
+    direction: RemoteDirection;
+    /** What to do when the remote twin disappears. */
+    on_delete: RemoteOnDelete;
+    /** How a field both sides edited is resolved. */
+    conflict: RemoteConflictPolicy;
+    /**
+     * The bulk guard (LP-364): a run where more than this fraction of linked
+     * twins is missing at once is treated as unreachable rather than as a wave
+     * of deletions. Absent means the default (0.5) applies; `1` disables the
+     * guard, since a fraction can never exceed 1.
+     */
+    bulk_guard?: number;
+    /**
+     * The write threshold (LP-350): a push whose plan creates or closes more
+     * than this many issues stops and requires `--yes`. Absent means the
+     * default (25) applies.
+     */
+    write_threshold?: number;
+    /**
+     * Per-field conflict overrides, keyed by board field name (a canonical
+     * field such as `status` or `depends_on`, or a declared attribute name):
+     * the field always takes the named owner and never conflicts.
+     * Defaults to `{}` — every field follows `conflict`.
+     */
+    fields: Record<string, RemoteFieldOwner>;
+    /**
+     * Where degraded fields are encoded: a managed block in the body, or a
+     * managed comment. Defaults to `block`; `comment` is the spelling of
+     * "the body is not writable" (LP-278).
+     */
+    encoding: RemoteEncoding;
+    /** How user comments sync: `push` (default) or `both` (LP-316). */
+    comments: RemoteCommentsMode;
+    /** Provider-specific connection settings. Opaque to core; the provider validates it. */
+    connection: Record<string, unknown>;
+    /** Provider-specific vocabulary mapping. Opaque to core; the provider validates it. */
+    mapping: Record<string, unknown>;
+}
+/**
+ * The one type the template registry adds to the issue vocabulary: a container
+ * that stands in for a level instead of templatizing it.
+ *
+ * A template of a feature has to sit at the feature's depth, so something has to
+ * occupy the epic's level above it — that is a folder. It is never instantiated
+ * and it holds nothing but other folders and the roots of templates.
+ *
+ * The name is reserved across every namespace (`config/schema.ts` refuses it),
+ * because the registry reuses the issue types by name and a board declaring its
+ * own `folder` would make "which folder?" unanswerable.
+ */
+export declare const TEMPLATE_FOLDER_TYPE = "folder";
+/** The definition the registry uses for its one own type. */
+export declare const TEMPLATE_FOLDER_DEF: TypeDef;
+export interface BoardConfig {
+    version: number;
+    key_prefix: string;
+    default_status: string;
+    statuses: StatusDef[];
+    issue_types: Record<string, TypeDef>;
+    /**
+     * Normalized issue hierarchy. Index is folder depth; each level lists the
+     * type names allowed at that depth. Level 0 types live at the board root.
+     */
+    hierarchy: string[][];
+    /** Prefix for period ids. Distinct from `key_prefix`. */
+    period_prefix: string;
+    /** Period types. Empty when the board does not use a time hierarchy. */
+    period_types: Record<string, TypeDef>;
+    /** Normalized period hierarchy, same shape as `hierarchy`. */
+    period_hierarchy: string[][];
+    /** Prefix for resource ids. Distinct from the other two prefixes. */
+    resource_prefix: string;
+    /** Resource types. Empty when the board does not use a team roster. */
+    resource_types: Record<string, TypeDef>;
+    /** Normalized resource hierarchy, same shape as `hierarchy`. */
+    resource_hierarchy: string[][];
+    /**
+     * Prefix for template ids. Distinct from the other prefixes.
+     *
+     * The registry has no `template_types` or `template_hierarchy` beside this,
+     * and never will: a template *is* an issue of one of the board's own types,
+     * so the namespace is derived from `issue_types` and `hierarchy` rather than
+     * declared a second time. @see templateTypes / templateHierarchy
+     */
+    template_prefix: string;
+    /** Prefix for squad ids. Distinct from the other three prefixes. */
+    squad_prefix: string;
+    /** Squad types. Empty when the board does not use squads. */
+    squad_types: Record<string, TypeDef>;
+    /** Normalized squad hierarchy, same shape as `hierarchy`. */
+    squad_hierarchy: string[][];
+    /**
+     * Name of the enum issue attribute that ranks work, most important value
+     * first. Empty when the board declares none.
+     */
+    priority_attribute: string;
+    /** Name of the numeric issue attribute that measures effort. Empty when unset. */
+    effort_attribute: string;
+    /**
+     * The remotes this board mirrors to, keyed by remote name. Empty when the
+     * board declares none. Core stores the frame of each entry and never acts on
+     * it; `src/remote` opens a remote and validates its provider-specific parts.
+     */
+    remotes: Record<string, RemoteConfig>;
+    /**
+     * Remotes that are declared but turned off, keyed by name — the same blocks
+     * `remotes` holds, moved aside. Nothing opens, pushes, pulls or reports on
+     * one; it exists so a mirror can be turned off (to share the board through
+     * git instead) and on again without being configured from scratch. Its link
+     * store and credentials under `.lpm/remotes/<name>/` are left exactly as they
+     * were. Read it with `remotesOffNames`; `operations/remotes-off.ts` moves a
+     * block between the two.
+     */
+    remotes_off: Record<string, RemoteConfig>;
+    /**
+     * How this board is shared through its own git repository, or null when it
+     * is not. Read it with `gitSyncOf`; `src/core/gitsync` is what acts on it.
+     * Exclusive with `remotes`: a board syncs through git or mirrors onto
+     * trackers, never both.
+     */
+    git_sync: GitSyncConfig | null;
+}
+/**
+ * The board's git remote: which remote of the `.lpm` repository it pushes to,
+ * and which branch there. The URL is not here — git keeps it in `.lpm/.git`,
+ * per clone, which is where a teammate's clone already has it.
+ */
+export interface GitSyncConfig {
+    /** The git remote name inside `.lpm` (`origin`). */
+    remote: string;
+    /** The branch on that remote the board lives on (`main`, `_lpm_board_remote`). */
+    branch: string;
+}
+export declare function hasPeriods(config: BoardConfig): boolean;
+export declare function hasResources(config: BoardConfig): boolean;
+export declare function hasSquads(config: BoardConfig): boolean;
+/**
+ * Frontmatter keys owned by light-plan. Custom attributes may not use these.
+ * Fields backed by frontmatter keep the snake_case spelling of the key;
+ * fields derived at load time (dir, parentId, depth) are camelCase.
+ */
+export declare const ISSUE_RESERVED_FIELDS: readonly ["id", "type", "title", "status", "assignee", "period", "flag", "depends_on", "relates_to", "related_files", "created", "updated", "author"];
+export declare const PERIOD_RESERVED_FIELDS: readonly ["id", "type", "title", "starts", "ends", "active", "squad", "created", "updated", "author"];
+export declare const RESOURCE_RESERVED_FIELDS: readonly ["id", "type", "title", "capacity", "covers", "created", "updated", "author"];
+export declare const TEMPLATE_RESERVED_FIELDS: readonly ["id", "type", "title", "description", "params", "depends_on", "relates_to", "related_files", "created", "updated", "author"];
+export declare const SQUAD_RESERVED_FIELDS: readonly ["id", "type", "title", "members", "created", "updated", "author"];
+/**
+ * Why an issue somebody is working on has stopped.
+ *
+ * A flag is not a status: the work stays where it is, in whatever column the
+ * board calls "in progress", and the flag says it is not moving. That is
+ * deliberate — a board that had to invent a "blocked" column would lose the
+ * distinction between "nobody has started this" and "somebody started it and
+ * hit a wall", and only the second one needs anyone's attention today.
+ */
+export declare const FLAG_REASONS: readonly ["blocked", "paused", "help"];
+export type FlagReason = (typeof FLAG_REASONS)[number];
+/**
+ * A reason a *person* may raise. `DERIVED_FLAG` is deliberately not one: it is
+ * the roll-up's word for "something inside this has stopped", and letting
+ * somebody type it would make a container's own flag indistinguishable from one
+ * the roll-up may clear. `flagIssue` refuses it for that reason.
+ */
+export declare function isFlagReason(value: string): value is FlagReason;
+/**
+ * A value that may legitimately sit in a document's `flag` field — the reasons
+ * a person may raise, plus the one the roll-up writes.
+ *
+ * A different question from `isFlagReason`, and `check` asks this one: `--fix`
+ * writes `DERIVED_FLAG` onto containers, so validating against the raiseable
+ * reasons alone would make the repair produce a board that fails the check that
+ * asked for it.
+ */
+export declare function isValidFlag(value: string): boolean;
+/**
+ * The label a flag is shown with, falling back to whatever the file says — a
+ * value this version does not know is still printed rather than swallowed.
+ *
+ * `src/shared/model.ts` carries the same list and the same function for the
+ * browser, which imports nothing from core by design. They must agree, or the
+ * canvas and `lpm flag list` will call the same flag two different things.
+ */
+export declare function flagLabel(flag: string): string;
+export type NodeKind = 'issue' | 'period' | 'resource' | 'squad' | 'template';
+export declare function reservedFieldsFor(kind: NodeKind): readonly string[];
+/** Everything an issue and a period have in common. */
+export interface BaseNode {
+    kind: NodeKind;
+    id: string;
+    type: string;
+    title: string;
+    created?: string;
+    updated?: string;
+    author?: string;
+    /** Config-declared custom attributes, plus any extra frontmatter keys found. */
+    attributes: Record<string, unknown>;
+    body: string;
+    /** Absolute path to the document's folder. */
+    dir: string;
+    /** Absolute path to the document's markdown file. */
+    file: string;
+    parentId: string | null;
+    /** Folder depth below the collection root; 0 for top-level documents. */
+    depth: number;
+}
+export interface Issue extends BaseNode {
+    kind: 'issue';
+    status: string;
+    /** Id of the resource this issue is assigned to — a person or a pool. */
+    assignee: string | null;
+    /** Id of the period this issue is scheduled in, at any level. */
+    period: string | null;
+    /**
+     * Why this issue has stalled, or `null` when it has not — one of
+     * `FLAG_REASONS`. Raised by whoever is doing the work and cleared by whoever
+     * is running the plan, always with a comment saying why (`flagIssue` writes
+     * both, so no front end can raise a flag nobody can act on).
+     *
+     * Anything unrecognized is kept rather than dropped, so a flag written by a
+     * newer version of light-plan still shouts; `check` is what reports it.
+     */
+    flag: string | null;
+    /** Ids this issue is blocked by. The inverse is derived, never stored. */
+    depends_on: string[];
+    /** Ids this issue is associated with, without implying an ordering. */
+    relates_to: string[];
+    /**
+     * Files this issue is about: the requirement it was written from, the source
+     * that has to change, the fixture that proves it. Free text rather than ids,
+     * because the things worth pointing at live outside the board — a path
+     * relative to the project root, optionally with a line range
+     * (`docs/prd.md#L10-L42`).
+     *
+     * Deliberately not checked against the filesystem. An issue may name a file
+     * that does not exist yet — that is frequently the whole point of it — and a
+     * board that failed CI because somebody renamed a module would teach people
+     * to stop filling this in.
+     */
+    related_files: string[];
+}
+export interface Period extends BaseNode {
+    kind: 'period';
+    /** Inclusive start date, YYYY-MM-DD. */
+    starts?: string;
+    /** Inclusive end date, YYYY-MM-DD. */
+    ends?: string;
+    /**
+     * A switch held over the dates: `true` runs this period whatever the calendar
+     * says, `false` parks it. **Absent is the normal case** and means the dates
+     * decide, which is why this is optional rather than defaulted — a board that
+     * has never touched a switch behaves exactly as it always did.
+     *
+     * It exists because not every team plans by date. Turning a sprint off is how
+     * a reader says "not this one, work on that one instead" without inventing
+     * dates they do not believe in, and `periodStance` is the only place that
+     * reads it.
+     */
+    active?: boolean;
+    /** Id of the squad that owns this period, or null. */
+    squad: string | null;
+}
+export interface Resource extends BaseNode {
+    kind: 'resource';
+    /**
+     * Full-time equivalents this resource supplies: 1 for a full-time person,
+     * 0.5 part-time, 3 for a pool of three. Defaults to 1 when absent.
+     */
+    capacity: number;
+    /** Generic resources this one can be drawn from. The inverse is derived. */
+    covers: string[];
+}
+export interface Squad extends BaseNode {
+    kind: 'squad';
+    /** Resource ids that belong to this squad. The inverse is derived. */
+    members: string[];
+}
+/**
+ * A reusable piece of plan, kept in the registry (`.lpm/registry/`) and copied
+ * into the board on request.
+ *
+ * A template is written exactly like the issue it produces — it carries one of
+ * the board's own issue types, sits at that type's depth, and nests the same way
+ * — minus everything about *this* piece of work: no status, no assignee, no
+ * period, no flag. What it adds is a `description` (so the registry reads as a
+ * catalogue rather than a folder listing) and, on a root, the `params` whoever
+ * instantiates it has to answer.
+ */
+export interface Template extends BaseNode {
+    kind: 'template';
+    /** What this template is for, one or two lines. Shown in the registry. */
+    description: string;
+    /**
+     * What this template asks for, keyed by name. Declared only on a **root** —
+     * a template whose parent is a folder or nothing — because the root is the
+     * only thing anybody instantiates, and its children take the same answers.
+     * Empty on everything else.
+     */
+    params: ParamDefs;
+    /** Template ids this one depends on. Repointed at the copies on instantiation. */
+    depends_on: string[];
+    /** Template ids this one is associated with, without implying an ordering. */
+    relates_to: string[];
+    /** Files the issues produced from this template should point at. */
+    related_files: string[];
+}
+export type AnyNode = Issue | Period | Resource | Squad | Template;
+export interface IssueNode extends Issue {
+    children: IssueNode[];
+}
+export interface PeriodNode extends Period {
+    children: PeriodNode[];
+}
+export interface ResourceNode extends Resource {
+    children: ResourceNode[];
+}
+export interface SquadNode extends Squad {
+    children: SquadNode[];
+}
+export interface TemplateNode extends Template {
+    children: TemplateNode[];
+}
+/** True for the registry's own container type, which is never instantiated. */
+export declare function isFolderTemplate(node: {
+    type: string;
+}): boolean;
+export type ProblemLevel = 'error' | 'warn';
+export interface Problem {
+    level: ProblemLevel;
+    /** Path relative to the board root, for display. */
+    path: string;
+    message: string;
+    /** True when `check --fix` can repair this automatically. */
+    fixable?: boolean;
+}