light-plan 0.0.0-stage → 0.1.0

package/dist/remote/guard.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The write-confirmation gate (LP-350) — the pure decision a push must pause
+ * for, shared by every front end so the CLI, the web panel and an agent cannot
+ * disagree about whether a plan needs consent.
+ *
+ * Two pauses, one memory:
+ *
+ *   - **First write.** The very first time a remote is written to, a person
+ *     must confirm the target and the counts. The consent is recorded once
+ *     (`links.ts`'s `consentedAt`) and never asked again.
+ *   - **Oversized plan.** A push whose plan creates or closes more than the
+ *     configured threshold (default 25) stops and requires `--yes`, because a
+ *     scope typo that makes half the board look deleted would otherwise close
+ *     half a backlog — bulk-close is as dangerous as bulk-create.
+ *
+ * This file only *decides*. The prompting (interactive) and the refusal (a
+ * non-interactive run with no `--yes`) live in the caller — `runSync` enforces
+ * the decision through its `confirm` / `yes` options, and the CLI supplies the
+ * prompt. Nothing here touches a terminal, a file or a request.
+ */
+import type { PushPlan } from './plan.js';
+import type { OpenedRemote } from './remotes.js';
+/** The default write threshold: more creates+closes than this needs `--yes`. */
+export declare const DEFAULT_WRITE_THRESHOLD = 25;
+/** The write-shaped counts a plan implies, for the confirmation and the report. */
+export interface PushWriteCounts {
+    /** New twins the plan files: `create` plus `restore` (a re-file is a create). */
+    creates: number;
+    /** Existing twins the plan closes (a terminal status reached, or `on_delete: close`). */
+    closes: number;
+    /** Existing twins the plan deletes (`on_delete: delete`). */
+    deletes: number;
+    /** Every remote write of any kind — the number `--limit` budgets against. */
+    writes: number;
+}
+/**
+ * Count the write-shaped operations in a push plan. `creates` and `closes`
+ * feed the threshold gate; `deletes` feeds both the threshold gate (a bulk
+ * deletion is a bulk write) and the every-run delete gate; `writes` feeds the
+ * first-write gate (any write at all) and the report.
+ */
+export declare function countPushWrites(plan: PushPlan): PushWriteCounts;
+/** The configured threshold for a remote, or the default when it says nothing. */
+export declare function writeThresholdOf(remote: OpenedRemote): number;
+/** Why a push plan needs consent before it may run. */
+export type ConsentReason = 'first_write' | 'threshold' | 'delete';
+/** The decision: does this plan need a pause, and if so why. */
+export interface ConsentGate {
+    /** True when the push may not run without consent. */
+    requiresConsent: boolean;
+    /** Why, when `requiresConsent`. */
+    reason?: ConsentReason;
+    /** The counts the gate decided on, for the message. */
+    counts: PushWriteCounts;
+    /** The threshold in force (used when `reason` is `threshold`). */
+    threshold: number;
+}
+/** What a confirmation prompt shows: the target, the reason, and the counts. */
+export interface ConsentRequest {
+    remoteName: string;
+    /** The human-readable target (`owner/repo`, `PROJ @ host`, `team`). */
+    target: string;
+    reason: ConsentReason;
+    counts: PushWriteCounts;
+    threshold: number;
+}
+/** A refusal recorded on the result: the push was stopped, nothing written. */
+export interface ConsentRefusal {
+    reason: ConsentReason;
+    target: string;
+    counts: PushWriteCounts;
+    threshold: number;
+}
+/**
+ * Decide whether a push needs consent.
+ *
+ * A plan with no remote writes never asks — there is nothing to confirm. An
+ * oversized plan (creates + closes + deletes above the threshold) outranks the
+ * rest, because `--yes` satisfies it and it is the strictest of the gates.
+ * A plan that deletes a twin (`on_delete: delete`) is the next: it must be
+ * confirmed **every run**, and the gate is never satisfied by a remembered
+ * first-write consent (LP-351).  Otherwise the gate asks once, on the first
+ * write, until consent is recorded.
+ */
+export declare function consentGate(params: {
+    remote: OpenedRemote;
+    /** Whether first-write consent has already been recorded for this remote. */
+    consented: boolean;
+    plan: PushPlan;
+}): ConsentGate;

package/dist/remote/guard.js

@@ -0,0 +1,83 @@
+/**
+ * The write-confirmation gate (LP-350) — the pure decision a push must pause
+ * for, shared by every front end so the CLI, the web panel and an agent cannot
+ * disagree about whether a plan needs consent.
+ *
+ * Two pauses, one memory:
+ *
+ *   - **First write.** The very first time a remote is written to, a person
+ *     must confirm the target and the counts. The consent is recorded once
+ *     (`links.ts`'s `consentedAt`) and never asked again.
+ *   - **Oversized plan.** A push whose plan creates or closes more than the
+ *     configured threshold (default 25) stops and requires `--yes`, because a
+ *     scope typo that makes half the board look deleted would otherwise close
+ *     half a backlog — bulk-close is as dangerous as bulk-create.
+ *
+ * This file only *decides*. The prompting (interactive) and the refusal (a
+ * non-interactive run with no `--yes`) live in the caller — `runSync` enforces
+ * the decision through its `confirm` / `yes` options, and the CLI supplies the
+ * prompt. Nothing here touches a terminal, a file or a request.
+ */
+import { isRemoteWrite } from './execute.js';
+/** The default write threshold: more creates+closes than this needs `--yes`. */
+export const DEFAULT_WRITE_THRESHOLD = 25;
+/** Whether an op files a new twin, for the create half of the threshold count. */
+function isCreateLike(op) {
+    return op.kind === 'create' || op.kind === 'restore';
+}
+/**
+ * Count the write-shaped operations in a push plan. `creates` and `closes`
+ * feed the threshold gate; `deletes` feeds both the threshold gate (a bulk
+ * deletion is a bulk write) and the every-run delete gate; `writes` feeds the
+ * first-write gate (any write at all) and the report.
+ */
+export function countPushWrites(plan) {
+    let creates = 0;
+    let closes = 0;
+    let deletes = 0;
+    let writes = 0;
+    for (const op of plan.ops) {
+        if (isCreateLike(op))
+            creates += 1;
+        else if (op.kind === 'close')
+            closes += 1;
+        else if (op.kind === 'delete')
+            deletes += 1;
+        if (isRemoteWrite(op))
+            writes += 1;
+    }
+    return { creates, closes, deletes, writes };
+}
+/** The configured threshold for a remote, or the default when it says nothing. */
+export function writeThresholdOf(remote) {
+    return remote.write_threshold ?? DEFAULT_WRITE_THRESHOLD;
+}
+/**
+ * Decide whether a push needs consent.
+ *
+ * A plan with no remote writes never asks — there is nothing to confirm. An
+ * oversized plan (creates + closes + deletes above the threshold) outranks the
+ * rest, because `--yes` satisfies it and it is the strictest of the gates.
+ * A plan that deletes a twin (`on_delete: delete`) is the next: it must be
+ * confirmed **every run**, and the gate is never satisfied by a remembered
+ * first-write consent (LP-351).  Otherwise the gate asks once, on the first
+ * write, until consent is recorded.
+ */
+export function consentGate(params) {
+    const counts = countPushWrites(params.plan);
+    const threshold = writeThresholdOf(params.remote);
+    if (counts.writes === 0) {
+        return { requiresConsent: false, counts, threshold };
+    }
+    if (counts.creates + counts.closes + counts.deletes > threshold) {
+        return { requiresConsent: true, reason: 'threshold', counts, threshold };
+    }
+    if (counts.deletes > 0) {
+        return { requiresConsent: true, reason: 'delete', counts, threshold };
+    }
+    if (!params.consented) {
+        return { requiresConsent: true, reason: 'first_write', counts, threshold };
+    }
+    return { requiresConsent: false, counts, threshold };
+}
+//# sourceMappingURL=guard.js.map

package/dist/remote/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../src/remote/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,gFAAgF;AAChF,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAc1C,kFAAkF;AAClF,SAAS,YAAY,CAAC,EAAY;IAChC,OAAO,EAAE,CAAC,IAAI,KAAK,QAAQ,IAAI,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC;AACvD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,IAAc;IAC5C,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QAC1B,IAAI,YAAY,CAAC,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC;aAC9B,IAAI,EAAE,CAAC,IAAI,KAAK,OAAO;YAAE,MAAM,IAAI,CAAC,CAAC;aACrC,IAAI,EAAE,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC,CAAC;QAC5C,IAAI,aAAa,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC9C,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,gBAAgB,CAAC,MAAoB;IACnD,OAAO,MAAM,CAAC,eAAe,IAAI,uBAAuB,CAAC;AAC3D,CAAC;AAmCD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,MAK3B;IACC,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAElD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACvD,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,OAAO,GAAG,SAAS,EAAE,CAAC;QAChE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC3E,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACxE,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QACtB,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC7E,CAAC;IACD,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACvD,CAAC"}

package/dist/remote/hierarchy.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Hierarchy encoding — how a board's issue tree survives a flat or shallow
+ * tracker (LP-309).
+ *
+ * Two encodings, one board:
+ *
+ *   - `sub-issues` — the remote's native parent edge (GitHub's sub-issues),
+ *     for the levels the account supports (one native parent level on GitHub);
+ *   - `labels`      — the type label plus the parent id in the managed block,
+ *     everywhere the native edge is not available.
+ *
+ * Which encoding a remote gets is decided per remote, at runtime, from the
+ * *resolved* capability table (`hierarchyDepth`) and an optional forced choice
+ * (`--hierarchy sub-issues|labels`).  The module is pure: capabilities +
+ * hierarchy + option in, an encoding out — never an API version constant.
+ *
+ * The parent axis is the only thing this module owns.  The *type* axis is the
+ * mapping's business (`mapping.ts`): a `lpm:epic` label is written and read by
+ * the translator whatever the encoding, and this module's `labels` kind means
+ * only "the parent rides the managed block, not a native edge".
+ *
+ * LP-493 adds the switch detection this module was missing: `HierarchyRecord`
+ * is the two fields a remote records after a successful sync, and
+ * `carrierChanged` answers "would this depth ride a different carrier under
+ * the newly resolved encoding?" — the signal `planPush` turns into a
+ * `reparent` op rather than a stale carrier left behind.
+ */
+import type { ResolvedCapabilities } from './capabilities.js';
+import { type DegradedLevel } from './mapping.js';
+/** The two spellings of the hierarchy decision. */
+export type HierarchyEncoding = 'sub-issues' | 'labels';
+/**
+ * Which end of the board a remote's native parent chain is spent on.
+ *
+ * `root` gives the native edge to the *shallowest* levels: a programme's epics
+ * nest natively and the work below degrades. That is right for a tracker whose
+ * parent edge is type-blind — GitHub's sub-issues hold any issue under any
+ * issue, so the only question is how deep it goes. It is the default and the
+ * historical behaviour.
+ *
+ * `leaf` gives it to the *deepest*: the work items nest under their container
+ * and everything above degrades. That is right for a tracker whose hierarchy is
+ * defined from the bottom up — Jira's is (`Subtask` < standard < `Epic`), and
+ * only a standard issue may sit under an Epic. Spending the chain at the root
+ * there puts it exactly where Jira refuses it: a board with three levels above
+ * its stories maps them all onto `Epic`, `Epic` may not sit under `Epic`, so
+ * every native edge is rejected — while the one relationship Jira *would* hold,
+ * the work item under its container, rides the block and the tracker shows a
+ * flat list.
+ */
+export type HierarchyAnchor = 'root' | 'leaf';
+/** The field name the degraded parent's remote id rides under in the block. */
+export declare const PARENT_FIELD = "parent";
+/**
+ * One remote's resolved hierarchy encoding: which kind it is, how many levels
+ * nest natively (root = level 1), and which levels' parent therefore rides the
+ * managed block.
+ */
+export interface ResolvedHierarchy {
+    kind: HierarchyEncoding;
+    /** Levels that nest natively, counting the root: 1 for labels, `hierarchyDepth + 1` for sub-issues. */
+    nativeDepth: number;
+    /** Which end of the board the native chain is spent on. */
+    anchor: HierarchyAnchor;
+    /** Shallowest depth whose parent edge is native (a root document has none). */
+    nativeFrom: number;
+    /** Deepest depth whose parent edge is native. */
+    nativeTo: number;
+    /** Levels whose parent is carried in the block. */
+    degraded: DegradedLevel[];
+}
+/**
+ * The hierarchy encoding a remote last used (LP-493): the two fields that
+ * decide which carrier a parent rides. Recorded beside the links after a
+ * successful sync, so the next sync can detect a switch — a plan gaining the
+ * sub-issue API, or a forced `--hierarchy` — and migrate each twin in place
+ * rather than leaving a stale carrier behind. `degraded` is derived, never
+ * stored.
+ */
+export interface HierarchyRecord {
+    kind: HierarchyEncoding;
+    nativeDepth: number;
+    /**
+     * The anchor the last sync used. Absent on a record written before anchors
+     * existed, which reads as `root` — the behaviour those twins were filed
+     * under — so nothing migrates until the resolved anchor genuinely differs.
+     */
+    anchor?: HierarchyAnchor;
+}
+/** The `HierarchyRecord` a resolved encoding records. */
+export declare function recordOf(resolved: ResolvedHierarchy): HierarchyRecord;
+/**
+ * True when a document at `depth` (ancestor count, root = 0) would ride a
+ * different parent carrier under `resolved` than it did under `recorded`.
+ * Absent `recorded` (the first sync, or a store predating LP-493) or absent
+ * `resolved` answers false — there is nothing known to migrate.
+ */
+export declare function carrierChanged(recorded: HierarchyRecord | undefined, resolved: ResolvedHierarchy | undefined, depth: number): boolean;
+/** The forced-choice option `--hierarchy` maps onto. */
+export interface HierarchyOptions {
+    /** Force one encoding, overriding capability detection. */
+    force?: HierarchyEncoding;
+}
+/**
+ * Resolve the hierarchy encoding for one remote.
+ *
+ * With no forced choice the capability decides: a remote that holds at least
+ * one native parent level is `sub-issues`, a flat one `labels`.  `force`
+ * overrides that — a user who wants the same behaviour across accounts pins it
+ * (`labels` on a secondary account without sub-issues, or `sub-issues` on an
+ * account where the probe would otherwise read "flat").
+ */
+export declare function resolveHierarchyEncoding(capabilities: Pick<ResolvedCapabilities, 'hierarchyDepth' | 'hierarchyAnchor'>, hierarchy: string[][], options?: HierarchyOptions): ResolvedHierarchy;
+/**
+ * True when a document at `depth` (ancestor count, root = 0) files under a
+ * native parent edge.  A document at depth 0 has no parent at all; the native
+ * edge covers depths 1 .. `nativeDepth - 1` — exactly one level of sub-issues
+ * (nativeDepth 2) leaves depth 2 and below to the block.
+ */
+export declare function parentIsNative(depth: number, resolved: ResolvedHierarchy): boolean;
+/**
+ * Build the managed-block entry carrying the degraded parent's **remote** id.
+ *
+ * The value is the remote id, not the local one, deliberately: the block must
+ * round-trip across boards.  A fresh checkout pulling this remote has never
+ * seen the local id, but it resolves the remote id through the link store
+ * exactly as it resolves a native sub-issue parent.  It is a `text` entry
+ * rather than an `id` link so the cell stays a plain token either way.
+ */
+export declare function parentBlockEntry(parentRemoteId: string): {
+    name: string;
+    kind: 'text';
+    value: string;
+};
+/**
+ * Read the degraded parent's remote id back out of a remote body.  Returns
+ * `undefined` when the body carries no managed block, when the block carries
+ * no `parent` row, or when a human left the cell empty — the caller then
+ * treats the issue as filed at the remote root.
+ */
+export declare function parentRemoteIdFromBlock(body: string): string | undefined;

package/dist/remote/hierarchy.js

@@ -0,0 +1,129 @@
+/**
+ * Hierarchy encoding — how a board's issue tree survives a flat or shallow
+ * tracker (LP-309).
+ *
+ * Two encodings, one board:
+ *
+ *   - `sub-issues` — the remote's native parent edge (GitHub's sub-issues),
+ *     for the levels the account supports (one native parent level on GitHub);
+ *   - `labels`      — the type label plus the parent id in the managed block,
+ *     everywhere the native edge is not available.
+ *
+ * Which encoding a remote gets is decided per remote, at runtime, from the
+ * *resolved* capability table (`hierarchyDepth`) and an optional forced choice
+ * (`--hierarchy sub-issues|labels`).  The module is pure: capabilities +
+ * hierarchy + option in, an encoding out — never an API version constant.
+ *
+ * The parent axis is the only thing this module owns.  The *type* axis is the
+ * mapping's business (`mapping.ts`): a `lpm:epic` label is written and read by
+ * the translator whatever the encoding, and this module's `labels` kind means
+ * only "the parent rides the managed block, not a native edge".
+ *
+ * LP-493 adds the switch detection this module was missing: `HierarchyRecord`
+ * is the two fields a remote records after a successful sync, and
+ * `carrierChanged` answers "would this depth ride a different carrier under
+ * the newly resolved encoding?" — the signal `planPush` turns into a
+ * `reparent` op rather than a stale carrier left behind.
+ */
+import { parseManagedBlock, parseManagedId } from './managed-block.js';
+/** The field name the degraded parent's remote id rides under in the block. */
+export const PARENT_FIELD = 'parent';
+/** The `HierarchyRecord` a resolved encoding records. */
+export function recordOf(resolved) {
+    return { kind: resolved.kind, nativeDepth: resolved.nativeDepth, anchor: resolved.anchor };
+}
+/**
+ * True when a document at `depth` (ancestor count, root = 0) would ride a
+ * different parent carrier under `resolved` than it did under `recorded`.
+ * Absent `recorded` (the first sync, or a store predating LP-493) or absent
+ * `resolved` answers false — there is nothing known to migrate.
+ */
+export function carrierChanged(recorded, resolved, depth) {
+    if (recorded === undefined || resolved === undefined)
+        return false;
+    // The recorded shape carries a count and (since anchors) an end; rebuilding
+    // the span it implied is what lets a *changed anchor* migrate each twin in
+    // place rather than leaving half the board parented the old way.
+    const wasAnchor = recorded.anchor ?? 'root';
+    const deepest = Math.max(resolved.nativeFrom - 1, 0) + (resolved.nativeTo - resolved.nativeFrom) + 1;
+    const span = Math.max(recorded.nativeDepth - 1, 0);
+    const was = wasAnchor === 'leaf'
+        ? { nativeFrom: Math.max(1, deepest - span + 1), nativeTo: deepest }
+        : { nativeFrom: 1, nativeTo: span };
+    const wasNative = depth >= was.nativeFrom && depth <= was.nativeTo;
+    return wasNative !== parentIsNative(depth, resolved);
+}
+/**
+ * Resolve the hierarchy encoding for one remote.
+ *
+ * With no forced choice the capability decides: a remote that holds at least
+ * one native parent level is `sub-issues`, a flat one `labels`.  `force`
+ * overrides that — a user who wants the same behaviour across accounts pins it
+ * (`labels` on a secondary account without sub-issues, or `sub-issues` on an
+ * account where the probe would otherwise read "flat").
+ */
+export function resolveHierarchyEncoding(capabilities, hierarchy, options = {}) {
+    const depth = capabilities.hierarchyDepth;
+    const kind = options.force ?? (depth >= 1 ? 'sub-issues' : 'labels');
+    // `labels` never nests. `sub-issues` nests to the capability's depth; a
+    // forced `sub-issues` over a probe that read "flat" assumes one native
+    // level — the caller is asserting the account has the API.
+    const nativeDepth = kind === 'labels' ? 1 : depth >= 1 ? depth + 1 : 2;
+    const anchor = capabilities.hierarchyAnchor ?? 'root';
+    // Which depths' *parent edge* is native. Root-anchored, the chain starts at
+    // the first level below the root; leaf-anchored, it ends at the deepest level
+    // the board has, so the work items are what nest.
+    const deepest = Math.max(hierarchy.length - 1, 0);
+    const span = Math.max(nativeDepth - 1, 0);
+    const nativeFrom = anchor === 'leaf' ? Math.max(1, deepest - span + 1) : 1;
+    const nativeTo = anchor === 'leaf' ? deepest : span;
+    const degraded = [];
+    for (let level = 1; level < hierarchy.length; level += 1) {
+        if (level >= nativeFrom && level <= nativeTo)
+            continue;
+        const types = hierarchy[level] ?? [];
+        if (types.length > 0)
+            degraded.push({ depth: level, types: [...types] });
+    }
+    return { kind, nativeDepth, anchor, nativeFrom, nativeTo, degraded };
+}
+/**
+ * True when a document at `depth` (ancestor count, root = 0) files under a
+ * native parent edge.  A document at depth 0 has no parent at all; the native
+ * edge covers depths 1 .. `nativeDepth - 1` — exactly one level of sub-issues
+ * (nativeDepth 2) leaves depth 2 and below to the block.
+ */
+export function parentIsNative(depth, resolved) {
+    return depth >= resolved.nativeFrom && depth <= resolved.nativeTo;
+}
+// ---------------------------------------------------------------------------
+// The block carrier (the `labels` encoding's parent)
+// ---------------------------------------------------------------------------
+/**
+ * Build the managed-block entry carrying the degraded parent's **remote** id.
+ *
+ * The value is the remote id, not the local one, deliberately: the block must
+ * round-trip across boards.  A fresh checkout pulling this remote has never
+ * seen the local id, but it resolves the remote id through the link store
+ * exactly as it resolves a native sub-issue parent.  It is a `text` entry
+ * rather than an `id` link so the cell stays a plain token either way.
+ */
+export function parentBlockEntry(parentRemoteId) {
+    return { name: PARENT_FIELD, kind: 'text', value: parentRemoteId };
+}
+/**
+ * Read the degraded parent's remote id back out of a remote body.  Returns
+ * `undefined` when the body carries no managed block, when the block carries
+ * no `parent` row, or when a human left the cell empty — the caller then
+ * treats the issue as filed at the remote root.
+ */
+export function parentRemoteIdFromBlock(body) {
+    const parsed = parseManagedBlock(body);
+    if (!parsed.found)
+        return undefined;
+    const cell = parsed.fields[PARENT_FIELD];
+    if (cell === undefined || cell === '')
+        return undefined;
+    return parseManagedId(cell);
+}
+//# sourceMappingURL=hierarchy.js.map

package/dist/remote/hierarchy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchy.js","sourceRoot":"","sources":["../../src/remote/hierarchy.ts"],"names":[],"mappings":"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"}

package/dist/remote/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Remote sync layer.
+ *
+ * Knows how to mirror an `.lpm` board onto an external tracker and back.  Sits
+ * above the engine, beside `src/sync`: it may import `src/core`, `src/shared`
+ * and `src/sync`, and nothing in `src/core` may import it.
+ *
+ * The *reasoning* behind the choices this folder makes — why the link store
+ * rather than a frontmatter field, why the base snapshot, the degradation
+ * ladder, pull-as-push, and the two-connector split — is the design record,
+ * `docs/remote-sync.md`. This comment and that document are the two things
+ * that keep a provider from growing reshaping logic.
+ *
+ *   links.ts       the correspondence store — which document is which remote issue
+ *   managed-block.ts the rung-4 codec: write fields into the body idempotently
+ *                  and parse them back out (LP-276, LP-277)
+ *   managed-comment.ts the rung-5 codec: the same block as a comment when the
+ *                  body is not writable (LP-278)
+ *   remotes.ts     declared remotes from config (LP-252)
+ *   scope.ts       which subtree a remote mirrors, and nothing else (LP-261)
+ *   shape.ts       hierarchy/type divergence report — reparent, retype, scope
+ *                  exit — reported, never silently applied (LP-368)
+ *   lifecycle.ts   the state of each correspondence (LP-361)
+ *   adopt.ts       adopt an existing remote issue into a document, and read
+ *                  the managed-block pairing a re-cloned board offers (LP-367)
+ *   mapping.ts     board vocabulary ↔ remote vocabulary (LP-362)
+ *   attributes.ts  attribute coercion, both directions (LP-270)
+ *   accounts.ts    resource ↔ account mapping, pools to a label (LP-271)
+ *   periods.ts     period ↔ container mapping (LP-272, LP-313)
+ *   capabilities.ts what a provider can hold as data, plus probed cells (LP-274)
+ *   ladder.ts      the degradation ladder as a report: the rung each construct
+ *                  lands on, and why (LP-275)
+ *   labels.ts      label reconciliation: the claimed set, the push merge, and
+ *                  what `provision` creates (LP-308)
+ *   ledger.ts      which remote owns which document, derived from every link
+ *                  store — the one-remote-per-document rule. A push reports a
+ *                  document another remote holds (`skipped: owned_elsewhere`);
+ *                  an explicit link is refused.
+ *   provider.ts    the four-member shape every provider adapter conforms to
+ *   transport/     the Connector contract that knows nothing about boards —
+ *                  REST, GraphQL and `gh` connectors (LP-293), plus the
+ *                  reliability decorators that slow a sync down instead of
+ *                  falling over: retry/backoff and the request budget
+ *                  (LP-297). Imported directly, never re-exported here: its
+ *                  `Connector` and `RemoteRequest` are transport vocabulary
+ *                  and would collide with the board-vocabulary ones in
+ *                  `provider.ts`.
+ *   transport-error.ts the seam that wraps a transport `RemoteError` into a
+ *                  `BoardError` (LP-294).
+ *   registry.ts    provider name → implementation (LP-260)
+ *   connection-catalogue.ts what connecting to each provider asks for —
+ *                  fields, credential keys, conditional keys — derived from
+ *                  the providers, for every front end that asks
+ *   connection.ts  connect, store a credential, change a connection — the
+ *                  refusals every caller without a terminal must share
+ *   inspect.ts     ask a remote about itself: reachability, discovery,
+ *                  vocabulary and prerequisites, as a report
+ *   check.ts       remote config as a check pass, composed by `lpm check` (LP-262)
+ *   preflight.ts   every unmappable value, collected before a push writes (LP-273)
+ *   prerequisites.ts what the remote must already have for a push to land —
+ *                  labels, sprints, Project fields — created by the push itself
+ *   plan.ts        planPush / planPull — pure functions, no I/O (LP-280, LP-281)
+ *   merge.ts       the field-by-field three-way merge (LP-284)
+ *   policy.ts      conflict resolution by policy, per remote and per field (LP-286)
+ *   resolutions.ts the pending decisions `lpm remote resolve` records (LP-287)
+ *   audit.ts       the sync audit log — one JSONL line per applied sync (LP-352)
+ *   conflicts.ts   the merge across a document: policy and resolutions applied (LP-287)
+ *   render.ts      a plan as a diff, for --dry-run and the web preview (LP-282)
+ *   redact.ts      the one place a secret value becomes `***` (LP-296)
+ *   fixtures.ts    record real traffic to fixtures, scrubbed, and replay it
+ *                  offline (LP-301)
+ *   pull.ts        the pull applier — applyChanges + link bookkeeping (LP-281)
+ *   execute.ts     push-side applier (LP-490)
+ *   guard.ts       the write-confirmation gate — first write, threshold, and the
+ *                  every-run delete gate (LP-350, LP-351)
+ *   sync.ts        the sync session — one remote, planned then rendered or
+ *                  applied, for `lpm remote push|pull|sync` (LP-341)
+ *   scaffold.ts    the mapping scaffold — draft a `mapping:` block from board
+ *                  config × capability descriptor (LP-369)
+ *   fingerprint.ts mapping fingerprint — detect a mapping change before it
+ *                  manufactures phantom conflicts (LP-370)
+ *   rebase.ts     re-base a board onto a changed mapping as an explicit
+ *                  operation (LP-371)
+ *
+ * ## The check layering, decided
+ *
+ * Core's `validation/check.ts` may not import this folder, so `checkBoard`
+ * knows nothing about remotes — not even a dangling `scope`. All remote checks
+ * live in `check.ts` and are composed by the CLI (`lpm check` calls
+ * `checkBoard` then `checkRemoteConfiguration`). Keep it that way: a remote check added to core is the same layering
+ * mistake this boundary exists to prevent.
+ */
+export * from './accounts.js';
+export * from './adopt.js';
+export * from './audit.js';
+export * from './attributes.js';
+export * from './capabilities.js';
+export * from './check.js';
+export * from './comments.js';
+export * from './config-file.js';
+export * from './conflicts.js';
+export * from './coverage.js';
+export * from './credentials.js';
+export * from './execute.js';
+export * from './fingerprint.js';
+export * from './fixtures.js';
+export * from './guard.js';
+export * from './hierarchy.js';
+export * from './ladder.js';
+export * from './labels.js';
+export * from './connection-catalogue.js';
+export * from './connection.js';
+export * from './inspect.js';
+export * from './ledger.js';
+export * from './lifecycle.js';
+export * from './links.js';
+export * from './managed-block.js';
+export * from './managed-comment.js';
+export * from './mapping.js';
+export * from './merge.js';
+export * from './periods.js';
+export * from './plan.js';
+export * from './policy.js';
+export * from './preflight.js';
+export * from './prerequisites.js';
+export * from './provider.js';
+export * from './provision.js';
+export * from './pull.js';
+export * from './rebase.js';
+export * from './readiness.js';
+export * from './reconcile.js';
+export * from './redact.js';
+export * from './registry.js';
+export * from './remotes.js';
+export * from './render.js';
+export * from './report.js';
+export * from './resolutions.js';
+export * from './scaffold.js';
+export * from './scope.js';
+export * from './selection.js';
+export * from './shape.js';
+export * from './status.js';
+export * from './vocabulary.js';
+export * from './sync.js';
+export * from './transport-error.js';