wingfoil 0.2.2 → 0.3.0

package/dist/memory/add.d.ts

@@ -15,26 +15,88 @@ export declare function slugifyTitle(title: string): string;
  * default rather than writing an empty list).
  */
 export declare function parseTags(raw: string | undefined): string[] | undefined;
-/** Whether an `id_pattern` contains a `{n}`-family numeric token (e.g. `task-{n}-{slug}`) — i.e. it
- * needs a sequence counter resolved before {@link generateId} can render it. */
+/** Whether an `id_pattern` contains a `{n}`-family numeric token (e.g. `task-{n}-{slug}`, `u-{n:1}`) —
+ * i.e. it needs a sequence counter resolved before {@link generateId} can render it. */
 export declare function hasNumericToken(idPattern: string): boolean;
 /**
- * The directory that holds every document of a type: the type's `path` pattern
- * (spec-001-memory-yaml-schema `MemoryTypeEntry.path`, e.g. `docs/memory/decision/{id}.md`) rendered
- * with a dummy `{id}` and reduced to its containing directory. The directory portion never depends on
- * the concrete id value, so this is well-defined before the id is generated (used by
- * {@link nextSequenceNumber} to count existing siblings). `values` fills any other path token —
- * `{release-line}`, `{scope}` — from `memory add --set` (task-110); `id` is always the dummy.
+ * The author date git would record for a commit made now at `root`, as git's internal
+ * `<seconds> <offset>` pair (`1790731800 -0200`): `GIT_AUTHOR_DATE` when it is set, in any format git
+ * accepts, otherwise the system clock — read ONCE, through `git var GIT_AUTHOR_IDENT` (task-163,
+ * `bug-158`). `memory add` builds `{date}` from it ({@link formatIdDate}) and records the add commit
+ * with this same author date (passed back as `@<seconds> <offset>`: git reads a bare pair as a
+ * timestamp only from 9 digits of seconds up), so the id and the commit cannot disagree, and a caller (a test, a
+ * replay) fixes the date the way it fixes any git author date.
+ *
+ * `identity` is passed to git as `GIT_AUTHOR_NAME`/`GIT_AUTHOR_EMAIL`: the identity was already
+ * resolved and checked (`requireGitIdentity`), and only the date part of git's answer is read.
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when git refuses (e.g. a `GIT_AUTHOR_DATE` it
+ *   cannot parse) or answers in a shape that is not `… <seconds> <offset>`.
+ */
+export declare function readAuthorDate(root: string, identity: {
+    readonly name: string;
+    readonly email: string;
+}): string;
+/**
+ * The `<seconds> <offset>` date that ends a git ident line (`Name <email> 1790731800 -0200`). Pure.
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when the line does not end with one.
+ */
+export declare function identDate(ident: string): string;
+/**
+ * `{date}`'s value (`spec-001`'s placeholder table): the UTC calendar date `YYYYMMDD` of a git
+ * `<seconds> <offset>` date ({@link readAuthorDate}). The offset does not move the instant, so
+ * `23:30 -0200` on the 29th is the 30th. Pure.
+ */
+export declare function formatIdDate(gitDate: string): string;
+/**
+ * The highest `{n}` value among `paths` (repository-relative, `/`-separated) that the type's `path`
+ * pattern and materialized `id_pattern` match, or `0` when none does (`spec-001` "Counter algorithm",
+ * `dl-101` §2 (a)). The **highest**, not a count, so a gap never reissues a number (`bug-087`); and a
+ * maximum, so the answer is independent of the order `paths` arrive in (REQ-SYS-07).
  */
-export declare function resolveTypeDirectory(root: string, pathPattern: string, values?: Readonly<Record<string, string>>): string;
+export declare function highestSequenceNumber(paths: Iterable<string>, pathPattern: string, idPattern: string): number;
 /**
- * The next sequence number for a `{n}`-token id: `1 +` the count of existing files in `dir` whose
- * basename (sans `.md`) matches `idPattern` (`patternToRegExp`, task-002). Deterministic — a count is
- * independent of directory-entry order (REQ-SYS-07) — and confined to this type's own directory, so
- * unrelated files never perturb it. Returns `1` when the directory does not yet exist.
+ * The commits of the refs a number or a WIP slot can be taken on (`dl-101` §2 (a)): the tip of every
+ * local branch (`refs/heads/*`) and remote-tracking ref (`refs/remotes/*`), and `HEAD` (a detached
+ * `HEAD` is on no branch; an unborn one adds nothing), as full shas, de-duplicated and sorted
+ * (REQ-SYS-07). No network: the remote-tracking refs are what the last `git fetch` left (`dl-101`
+ * §1.1).
+ *
+ * The one listing of "every ref" both wider reads use — `memory add`'s `{n}` counter
+ * ({@link nextSequenceNumber}) and the WIP-limit holder count (`requireWipSlot`, `dl-156` Q1 (a),
+ * task-274) — so the two cannot disagree about which refs exist (`command-baseline`, *Declared
+ * baselines*).
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when a git read fails.
  */
-export declare function nextSequenceNumber(dir: string, idPattern: string): number;
-/** The fields `memory.add` pins on the freshly-created draft document (P1.3 memory.add / spec-010). */
+export declare function refBaselineCommits(root: string): string[];
+/**
+ * The next sequence number for a `{n}`-token id: `1 +` the highest number any baseline holds for this
+ * type — every local branch, remote-tracking ref, `HEAD`, the index and the untracked working-tree
+ * files ({@link sequenceCandidatePaths}) — over every folder the type's `path` can resolve to
+ * ({@link highestSequenceNumber}). `1` when nothing matches. Ratified `dl-101` §2 (a) (task-128,
+ * `bug-087`, `bug-162`); `spec-001` "Counter algorithm".
+ *
+ * @param root - The repository root.
+ * @param pathPattern - The type's committed `path` pattern, e.g. `docs/04_memory/{release}/{id}.md`.
+ * @param idPattern - The type's `id_pattern` with its field tokens already materialized.
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when a git read fails.
+ */
+export declare function nextSequenceNumber(root: string, pathPattern: string, idPattern: string): number;
+/**
+ * Which ids of a type with `path` pattern `pathPattern` exist on any baseline a number can be taken on —
+ * the ones {@link nextSequenceNumber} reads (every local branch, remote-tracking ref, `HEAD`, the index and
+ * the untracked working-tree files; `dl-101` §2 (a)) — in any folder the pattern resolves to: every token
+ * other than `{id}` matches one or more path segments. The paths are listed once; the returned predicate
+ * answers for any id. `workflow start` asks it of a derived or `--set phase=` plan id (`spec-017` §7.1,
+ * task-217): ids are unique per type, so a plan held by another branch, or under another `{scope}`,
+ * occupies its id.
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when a git read fails.
+ */
+export declare function idOccupancy(root: string, pathPattern: string): (id: string) => boolean;
+/** The fields `memory.add` pins on the freshly-created document (P1.3 memory.add / spec-010). */
 export interface AddDocumentFields {
     readonly id: string;
     readonly title: string;
@@ -46,16 +108,27 @@ export interface AddDocumentFields {
      * or appended when the scaffold has none.
      */
     readonly fields?: readonly (readonly [string, string])[];
+    /**
+     * The initial `status`: the head of the type's machine (`spec-001`; `bug-214`, task-180), which
+     * `memory add` resolves from the committed `memory.yaml`. Defaults to `draft`, the head of the
+     * built-in default machine.
+     */
+    readonly status?: string;
 }
 /**
  * Copy a type's `template.file` scaffold verbatim and fill only the frontmatter skeleton `memory.add`
  * pins (P1.3; spec-010-memory-frontmatter-schema): the generated `id`, the `--title`, the
- * initial `status: draft`, when `--tags` was supplied the `tags` flow sequence, and the `--set` fields
+ * initial `status` (the head of the type's machine, {@link AddDocumentFields.status}), when `--tags`
+ * was supplied the `tags` flow sequence, and the `--set` fields
  * {@link AddDocumentFields.fields} carries (task-110). Every other
  * field (notably `type` and `tmpl_version`, spec-010: not touched by add) and the whole body are left
  * exactly as the scaffold had them. `title`/`tags` are JSON-quoted (valid YAML double-quoted scalars /
  * flow sequences), so an arbitrary title with spaces or colons is written safely.
  *
+ * Each field is set through `./frontmatter-edit`'s shared setter, the one the transition verbs use
+ * (task-163, `bug-033`): only a TOP-LEVEL key is matched, so a nested key of the same name is never
+ * edited, and an edited line keeps the scaffold's inline `# comment`.
+ *
  * @throws when the scaffold has no frontmatter block (a malformed template — a config error surfaced
  *   as a thrown `Error` the core op maps to a `CoreError`).
  */
@@ -85,17 +158,30 @@ export declare function parseSetOptions(raw: string | readonly string[] | undefi
  */
 export declare function unknownSetNames(values: Readonly<Record<string, string>>, idPattern: string, pathPattern: string): string[];
 /**
- * Materialize an `id_pattern`'s frontmatter and context tokens (`{kind}`, `{version}`, `{workflow}`,
- * …) from the `--set` values, leaving `{slug}`, the `{n}` family and the not-yet-implemented
- * `{date}`/`{author}` in place — `spec-001`'s fixed expansion order (`{date}` → `{author}` → field and
- * context tokens → `{slug}` → `{n}`), so the `{n}` counter regexp built from the result sees a
- * fully-materialized prefix (task-110).
+ * The values of the tokens `memory add` sources itself rather than from `--set` (`spec-001`'s
+ * placeholder table, task-163): `{date}` and `{author}`. Each is needed only when the pattern has the
+ * token, and is read once per add by the caller.
+ */
+export interface IdTokenSources {
+    /** The add commit's author date as git's `<seconds> <offset>` ({@link readAuthorDate}). */
+    readonly date?: string;
+    /** The git author name the add commit records (`requireGitIdentity`), before slugging. */
+    readonly authorName?: string;
+}
+/**
+ * Materialize an `id_pattern`'s `{date}`, `{author}`, frontmatter and context tokens (`{kind}`,
+ * `{version}`, `{workflow}`, …), leaving `{slug}` and the `{n}` family in place — `spec-001`'s fixed
+ * expansion order (`{date}` → `{author}` → field and context tokens → `{slug}` → `{n}`), so the
+ * `{n}` counter regexp built from the result sees a fully-materialized prefix (task-110). `{date}` is
+ * the UTC `YYYYMMDD` of `sources.date` ({@link formatIdDate}); `{author}` the slug of
+ * `sources.authorName` ({@link slugifyTitle}) — task-163, `bug-158`.
  *
  * @throws {@link ValidationError} naming every field token with no value
- *   (`missing value for token {<name>}: give it with --set <name>=<value>`) and every value outside
- *   the ID character class, in pattern order — the same `E_INVALID_ID` code `generateId` raises.
+ *   (`missing value for token {<name>}: give it with --set <name>=<value>`), an `{author}` whose
+ *   name slugs to nothing, and every value outside the ID character class, in pattern order — the
+ *   same `E_INVALID_ID` code `generateId` raises.
  */
-export declare function expandFieldTokens(idPattern: string, values: Readonly<Record<string, string>>): string;
+export declare function expandFieldTokens(idPattern: string, values: Readonly<Record<string, string>>, sources?: IdTokenSources): string;
 /**
  * The `--set` values `memory add` writes into the new document's frontmatter, as `[name, value]`
  * pairs sorted by name (REQ-SYS-07). A field token is always written, so the id and the field cannot

package/dist/memory/add.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/memory/add.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOlD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAOvE;AAED;gFACgF;AAChF,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAK1D;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,MAAM,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAC5C,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQzE;AAED,uGAAuG;AACvG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;CAC1D;AAsBD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAiBrF;AAkBD,iGAAiG;AACjG,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,GACxE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,gBAAgB,CA4B7F;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACxC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,MAAM,EAAE,CAIV;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAiBrG;AAMD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAQ5G"}
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/memory/add.ts"],"names":[],"mappings":"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"}

package/dist/memory/add.js

@@ -3,8 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.slugifyTitle = slugifyTitle;
 exports.parseTags = parseTags;
 exports.hasNumericToken = hasNumericToken;
-exports.resolveTypeDirectory = resolveTypeDirectory;
+exports.readAuthorDate = readAuthorDate;
+exports.identDate = identDate;
+exports.formatIdDate = formatIdDate;
+exports.highestSequenceNumber = highestSequenceNumber;
+exports.refBaselineCommits = refBaselineCommits;
 exports.nextSequenceNumber = nextSequenceNumber;
+exports.idOccupancy = idOccupancy;
 exports.renderAddDocument = renderAddDocument;
 exports.parseSetOptions = parseSetOptions;
 exports.unknownSetNames = unknownSetNames;
@@ -17,14 +22,16 @@ exports.writtenFields = writtenFields;
  * thin composition and the id/slug/document-render logic is independently unit-testable.
  *
  * Every function here is deterministic (REQ-SYS-07): a slug is a pure function of the title, the
- * rendered document a pure function of `(scaffold, id, title, tags)`, and the sequence counter a pure
- * function of the committed on-disk state (a stable count, order-independent) — no wall-clock, no
- * randomness, no unordered iteration in a value that reaches the produced id or document.
+ * rendered document a pure function of `(scaffold, id, title, tags)`, and the sequence counter a
+ * maximum over the paths every ref and the working tree hold (order-independent, task-128) — no
+ * randomness and no unordered iteration in a value that reaches the produced id or document. The one
+ * time read is `{date}`'s ({@link readAuthorDate}, task-163): a write path, not a context-building
+ * one, taken once per add from the author date git records for the add commit, so a caller fixes it
+ * with `GIT_AUTHOR_DATE` and the id never disagrees with its own commit.
  */
-const fs_1 = require("fs");
-const path_1 = require("path");
 const storage_1 = require("../storage");
 const validation_1 = require("../validation");
+const frontmatter_edit_1 = require("./frontmatter-edit");
 const TOKEN_RE = /\{([^{}]+)\}/g;
 /**
  * Turn a human `--title` into a single, valid `[a-z0-9-.]` ID slug piece (spec-009-validation-strategy
@@ -56,70 +63,205 @@ function parseTags(raw) {
         .filter((tag) => tag.length > 0);
     return tags.length > 0 ? tags : undefined;
 }
-/** Whether an `id_pattern` contains a `{n}`-family numeric token (e.g. `task-{n}-{slug}`) — i.e. it
- * needs a sequence counter resolved before {@link generateId} can render it. */
+/** Whether an `id_pattern` contains a `{n}`-family numeric token (e.g. `task-{n}-{slug}`, `u-{n:1}`) —
+ * i.e. it needs a sequence counter resolved before {@link generateId} can render it. */
 function hasNumericToken(idPattern) {
     for (const match of idPattern.matchAll(TOKEN_RE)) {
-        if (/^n+$/.test(match[1] ?? ''))
+        if ((0, validation_1.isNumericToken)(match[1] ?? ''))
             return true;
     }
     return false;
 }
 /**
- * The directory that holds every document of a type: the type's `path` pattern
- * (spec-001-memory-yaml-schema `MemoryTypeEntry.path`, e.g. `docs/memory/decision/{id}.md`) rendered
- * with a dummy `{id}` and reduced to its containing directory. The directory portion never depends on
- * the concrete id value, so this is well-defined before the id is generated (used by
- * {@link nextSequenceNumber} to count existing siblings). `values` fills any other path token —
- * `{release-line}`, `{scope}` — from `memory add --set` (task-110); `id` is always the dummy.
+ * The author date git would record for a commit made now at `root`, as git's internal
+ * `<seconds> <offset>` pair (`1790731800 -0200`): `GIT_AUTHOR_DATE` when it is set, in any format git
+ * accepts, otherwise the system clock — read ONCE, through `git var GIT_AUTHOR_IDENT` (task-163,
+ * `bug-158`). `memory add` builds `{date}` from it ({@link formatIdDate}) and records the add commit
+ * with this same author date (passed back as `@<seconds> <offset>`: git reads a bare pair as a
+ * timestamp only from 9 digits of seconds up), so the id and the commit cannot disagree, and a caller (a test, a
+ * replay) fixes the date the way it fixes any git author date.
+ *
+ * `identity` is passed to git as `GIT_AUTHOR_NAME`/`GIT_AUTHOR_EMAIL`: the identity was already
+ * resolved and checked (`requireGitIdentity`), and only the date part of git's answer is read.
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when git refuses (e.g. a `GIT_AUTHOR_DATE` it
+ *   cannot parse) or answers in a shape that is not `… <seconds> <offset>`.
  */
-function resolveTypeDirectory(root, pathPattern, values = {}) {
-    return (0, path_1.dirname)((0, path_1.join)(root, (0, storage_1.renderMemoryPath)(pathPattern, { ...values, id: '__id__' })));
+function readAuthorDate(root, identity) {
+    const answer = (0, storage_1.runGitRead)(root, ['var', 'GIT_AUTHOR_IDENT'], {
+        env: { GIT_AUTHOR_NAME: identity.name, GIT_AUTHOR_EMAIL: identity.email },
+    }).stdout;
+    return identDate(answer);
 }
 /**
- * The next sequence number for a `{n}`-token id: `1 +` the count of existing files in `dir` whose
- * basename (sans `.md`) matches `idPattern` (`patternToRegExp`, task-002). Deterministic — a count is
- * independent of directory-entry order (REQ-SYS-07) — and confined to this type's own directory, so
- * unrelated files never perturb it. Returns `1` when the directory does not yet exist.
+ * The `<seconds> <offset>` date that ends a git ident line (`Name <email> 1790731800 -0200`). Pure.
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when the line does not end with one.
  */
-function nextSequenceNumber(dir, idPattern) {
-    if (!(0, fs_1.existsSync)(dir) || !(0, fs_1.statSync)(dir).isDirectory())
-        return 1;
-    const re = (0, validation_1.patternToRegExp)(idPattern);
-    let count = 0;
-    for (const entry of (0, fs_1.readdirSync)(dir).sort()) {
-        if (entry.endsWith('.md') && re.test(entry.slice(0, -'.md'.length)))
-            count += 1;
+function identDate(ident) {
+    const date = /> (-?[0-9]+ [+-][0-9]{4})$/.exec(ident.trim())?.[1];
+    if (date === undefined) {
+        throw new storage_1.StorageError(storage_1.E_GIT_READ_FAILED, `git var GIT_AUTHOR_IDENT gave no author date: "${ident.trim()}"`);
     }
-    return count + 1;
+    return date;
 }
 /**
- * Escape a literal string for safe insertion into a `RegExp` source (a frontmatter key here). */
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+ * `{date}`'s value (`spec-001`'s placeholder table): the UTC calendar date `YYYYMMDD` of a git
+ * `<seconds> <offset>` date ({@link readAuthorDate}). The offset does not move the instant, so
+ * `23:30 -0200` on the 29th is the 30th. Pure.
+ */
+function formatIdDate(gitDate) {
+    const seconds = Number.parseInt(gitDate, 10);
+    return new Date(seconds * 1000).toISOString().slice(0, 10).replace(/-/g, '');
+}
+/** A non-`{id}` `path` token as the counter matches it: one or more path segments (`dl-101` (a)). */
+const PATH_TOKEN_SOURCE = '[^/]+(?:/[^/]+)*';
+/**
+ * The RegExp a repository-relative path of this type matches, with the `{n}` value as group 1: the
+ * `path` pattern with `{id}` replaced by the (materialized) `id_pattern` and **every other token a
+ * wildcard**, whatever value this add gives it — so a `task`'s counter spans every
+ * `docs/04_memory/{release}/` folder, not only the one being added to (`bug-162`).
+ */
+function sequencePathRegExp(pathPattern, idPattern) {
+    const idSource = (0, validation_1.patternToSource)(idPattern, { captureNumeric: true });
+    let source = '^';
+    let last = 0;
+    for (const match of pathPattern.matchAll(TOKEN_RE)) {
+        const index = match.index;
+        source += escapeRegExp(pathPattern.slice(last, index));
+        source += match[1] === 'id' ? `(?:${idSource})` : PATH_TOKEN_SOURCE;
+        last = index + match[0].length;
+    }
+    return new RegExp(`${source}${escapeRegExp(pathPattern.slice(last))}$`);
 }
 /**
- * Set one frontmatter field on the raw frontmatter text, line-based: replace the value on the existing
- * `^<indent>key:` line if present (preserving the scaffold's ordering, comments and other fields
- * verbatim — the P1.3 memory.add contract copies the scaffold verbatim), otherwise append the field. `valueYaml`
- * is the already-serialized YAML scalar/flow value (e.g. a JSON-quoted string, a flow sequence).
+ * The highest `{n}` value among `paths` (repository-relative, `/`-separated) that the type's `path`
+ * pattern and materialized `id_pattern` match, or `0` when none does (`spec-001` "Counter algorithm",
+ * `dl-101` §2 (a)). The **highest**, not a count, so a gap never reissues a number (`bug-087`); and a
+ * maximum, so the answer is independent of the order `paths` arrive in (REQ-SYS-07).
  */
-function setFrontmatterField(frontmatter, key, valueYaml) {
-    const re = new RegExp(`^([ \\t]*)${escapeRegExp(key)}:.*$`, 'm');
-    if (re.test(frontmatter)) {
-        return frontmatter.replace(re, (_match, indent) => `${indent}${key}: ${valueYaml}`);
+function highestSequenceNumber(paths, pathPattern, idPattern) {
+    const re = sequencePathRegExp(pathPattern, idPattern);
+    let highest = 0;
+    for (const path of paths) {
+        const digits = re.exec(path)?.[1];
+        if (digits !== undefined)
+            highest = Math.max(highest, Number.parseInt(digits, 10));
     }
-    return `${frontmatter}\n${key}: ${valueYaml}`;
+    return highest;
+}
+/** The literal directory a `path` pattern starts with (up to its last `/` before any token), or `''`. */
+function literalPrefix(pathPattern) {
+    const head = pathPattern.split('{', 1)[0];
+    return head.slice(0, head.lastIndexOf('/') + 1);
+}
+/**
+ * Every repository-relative path under `prefix` that any baseline a number can be taken on holds —
+ * `command-baseline`'s declared baseline for `memory add`'s counter (`dl-101` §2 (a), `dl-080`):
+ *
+ * - the tree of every local branch (`refs/heads/*`) and remote-tracking ref (`refs/remotes/*`), and
+ *   of `HEAD` (a detached `HEAD` is on no branch);
+ * - the working tree as git sees it: the index and the untracked, non-ignored files.
+ *
+ * No network: the remote-tracking refs are what the last `git fetch` left (`dl-101` §1.1). Commits are
+ * de-duplicated and visited in sorted order, and the result is sorted (REQ-SYS-07).
+ */
+function sequenceCandidatePaths(root, prefix) {
+    const pathspec = prefix.length === 0 ? [] : ['--', prefix];
+    const paths = new Set();
+    const worktree = (0, storage_1.runGitRead)(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard', ...pathspec]);
+    for (const path of worktree.stdout.split('\0'))
+        if (path.length > 0)
+            paths.add(path);
+    // One batched read for every commit, not one `git ls-tree` each (`bug-178`, task-142): the number of
+    // git processes no longer grows with the number of branches and remote-tracking refs.
+    for (const path of (0, storage_1.listPathsAtRevs)(root, refBaselineCommits(root), prefix))
+        paths.add(path);
+    return [...paths].sort();
+}
+/**
+ * The commits of the refs a number or a WIP slot can be taken on (`dl-101` §2 (a)): the tip of every
+ * local branch (`refs/heads/*`) and remote-tracking ref (`refs/remotes/*`), and `HEAD` (a detached
+ * `HEAD` is on no branch; an unborn one adds nothing), as full shas, de-duplicated and sorted
+ * (REQ-SYS-07). No network: the remote-tracking refs are what the last `git fetch` left (`dl-101`
+ * §1.1).
+ *
+ * The one listing of "every ref" both wider reads use — `memory add`'s `{n}` counter
+ * ({@link nextSequenceNumber}) and the WIP-limit holder count (`requireWipSlot`, `dl-156` Q1 (a),
+ * task-274) — so the two cannot disagree about which refs exist (`command-baseline`, *Declared
+ * baselines*).
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when a git read fails.
+ */
+function refBaselineCommits(root) {
+    const refs = (0, storage_1.runGitRead)(root, ['for-each-ref', '--format=%(objectname)', 'refs/heads', 'refs/remotes']);
+    // `--verify --quiet` exits 1, printing nothing, on an unborn `HEAD`: an answer, not a failure.
+    const head = (0, storage_1.runGitRead)(root, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], { accepted: [0, 1] });
+    const commits = new Set(`${refs.stdout}\n${head.stdout}`.split('\n').map((sha) => sha.trim()));
+    commits.delete('');
+    return [...commits].sort();
+}
+/**
+ * The next sequence number for a `{n}`-token id: `1 +` the highest number any baseline holds for this
+ * type — every local branch, remote-tracking ref, `HEAD`, the index and the untracked working-tree
+ * files ({@link sequenceCandidatePaths}) — over every folder the type's `path` can resolve to
+ * ({@link highestSequenceNumber}). `1` when nothing matches. Ratified `dl-101` §2 (a) (task-128,
+ * `bug-087`, `bug-162`); `spec-001` "Counter algorithm".
+ *
+ * @param root - The repository root.
+ * @param pathPattern - The type's committed `path` pattern, e.g. `docs/04_memory/{release}/{id}.md`.
+ * @param idPattern - The type's `id_pattern` with its field tokens already materialized.
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when a git read fails.
+ */
+function nextSequenceNumber(root, pathPattern, idPattern) {
+    const prefix = literalPrefix(pathPattern);
+    return highestSequenceNumber(sequenceCandidatePaths(root, prefix), pathPattern, idPattern) + 1;
+}
+/**
+ * Which ids of a type with `path` pattern `pathPattern` exist on any baseline a number can be taken on —
+ * the ones {@link nextSequenceNumber} reads (every local branch, remote-tracking ref, `HEAD`, the index and
+ * the untracked working-tree files; `dl-101` §2 (a)) — in any folder the pattern resolves to: every token
+ * other than `{id}` matches one or more path segments. The paths are listed once; the returned predicate
+ * answers for any id. `workflow start` asks it of a derived or `--set phase=` plan id (`spec-017` §7.1,
+ * task-217): ids are unique per type, so a plan held by another branch, or under another `{scope}`,
+ * occupies its id.
+ *
+ * @throws {@link StorageError} `E_GIT_READ_FAILED` when a git read fails.
+ */
+function idOccupancy(root, pathPattern) {
+    const paths = sequenceCandidatePaths(root, literalPrefix(pathPattern));
+    return (id) => {
+        let source = '^';
+        let last = 0;
+        for (const match of pathPattern.matchAll(TOKEN_RE)) {
+            const index = match.index;
+            source += escapeRegExp(pathPattern.slice(last, index));
+            source += match[1] === 'id' ? escapeRegExp(id) : PATH_TOKEN_SOURCE;
+            last = index + match[0].length;
+        }
+        const re = new RegExp(`${source}${escapeRegExp(pathPattern.slice(last))}$`);
+        return paths.some((path) => re.test(path));
+    };
+}
+/**
+ * Escape a literal string for safe insertion into a `RegExp` source (a frontmatter key here). */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 /**
  * Copy a type's `template.file` scaffold verbatim and fill only the frontmatter skeleton `memory.add`
  * pins (P1.3; spec-010-memory-frontmatter-schema): the generated `id`, the `--title`, the
- * initial `status: draft`, when `--tags` was supplied the `tags` flow sequence, and the `--set` fields
+ * initial `status` (the head of the type's machine, {@link AddDocumentFields.status}), when `--tags`
+ * was supplied the `tags` flow sequence, and the `--set` fields
  * {@link AddDocumentFields.fields} carries (task-110). Every other
  * field (notably `type` and `tmpl_version`, spec-010: not touched by add) and the whole body are left
  * exactly as the scaffold had them. `title`/`tags` are JSON-quoted (valid YAML double-quoted scalars /
  * flow sequences), so an arbitrary title with spaces or colons is written safely.
  *
+ * Each field is set through `./frontmatter-edit`'s shared setter, the one the transition verbs use
+ * (task-163, `bug-033`): only a TOP-LEVEL key is matched, so a nested key of the same name is never
+ * edited, and an edited line keeps the scaffold's inline `# comment`.
+ *
  * @throws when the scaffold has no frontmatter block (a malformed template — a config error surfaced
  *   as a thrown `Error` the core op maps to a `CoreError`).
  */
@@ -128,18 +270,20 @@ function renderAddDocument(scaffold, fields) {
     if (frontmatter === null) {
         throw new Error('memory template scaffold has no frontmatter block');
     }
-    let fm = frontmatter;
-    fm = setFrontmatterField(fm, 'id', fields.id);
-    fm = setFrontmatterField(fm, 'title', JSON.stringify(fields.title));
-    fm = setFrontmatterField(fm, 'status', 'draft');
+    // Rebuilt as `memory add` always wrote it (a `---` line, the frontmatter, a `---` line, the body),
+    // then edited in place by the shared setter.
+    let document = `---\n${frontmatter}\n---\n${body}`;
+    document = (0, frontmatter_edit_1.setFrontmatterEntry)(document, 'id', fields.id);
+    document = (0, frontmatter_edit_1.setFrontmatterEntry)(document, 'title', JSON.stringify(fields.title));
+    document = (0, frontmatter_edit_1.setFrontmatterEntry)(document, 'status', fields.status ?? 'draft');
     if (fields.tags !== undefined) {
         const flow = `[${fields.tags.map((tag) => JSON.stringify(tag)).join(',')}]`;
-        fm = setFrontmatterField(fm, 'tags', flow);
+        document = (0, frontmatter_edit_1.setFrontmatterEntry)(document, 'tags', flow);
     }
     for (const [name, value] of fields.fields ?? []) {
-        fm = setFrontmatterField(fm, name, JSON.stringify(value));
+        document = (0, frontmatter_edit_1.setFrontmatterEntry)(document, name, JSON.stringify(value));
     }
-    return `---\n${fm}\n---\n${body}`;
+    return document;
 }
 /**
  * Names `memory add --set` refuses (`spec-008-cli-grammar` §10): the fields `memory add` fills itself
@@ -147,6 +291,19 @@ function renderAddDocument(scaffold, fields) {
  * their own (`n`, `slug`, `date`, `author` — `spec-001`'s placeholder table).
  */
 const RESERVED_SET_NAMES = new Set(['id', 'type', 'status', 'title', 'tags', 'n', 'slug', 'date', 'author']);
+/**
+ * The refusal of a reserved `--set` name, saying where its value comes from (`spec-008` §10). `date`
+ * and `author` name their source, which is not an option of `memory add` (task-163, `bug-158`: the
+ * generic sentence was false while nothing filled them, and unhelpful once something did).
+ */
+function reservedSetMessage(name) {
+    const prefix = `invalid flag value: --set cannot set "${name}": memory add fills`;
+    if (name === 'date')
+        return `${prefix} {date} from the add commit's author date (GIT_AUTHOR_DATE, or the clock)`;
+    if (name === 'author')
+        return `${prefix} {author} from the git author name`;
+    return `${prefix} it itself or through its own option`;
+}
 /** A `--set` field name: `[a-z][a-z0-9_-]*` — the same shape `idPatternIssues` accepts for a token. */
 const SET_NAME_RE = /^[a-z][a-z0-9_-]*$/;
 /**
@@ -154,6 +311,24 @@ const SET_NAME_RE = /^[a-z][a-z0-9_-]*$/;
  * written into the document only where its template declares a field of that name.
  */
 const CONTEXT_TOKENS = new Set(['workflow', 'phase', 'scope']);
+/**
+ * The spelling refusal of a `--set` value read as a path (task-281, `bug-325`; `spec-008` §10), or `null`.
+ * A token value may be substituted into the type's `path` pattern, so it must be a relative path whose
+ * segments (split on `/` and `\`) are neither empty nor `.` / `..` — first match wins: absolute, empty
+ * segment, dot segment. Applied to every `--set` value, because which names are path tokens is known only
+ * from the committed `memory.yaml`, and spelling is decided before anything is read (exit 2).
+ */
+function pathSpellingRefusal(name, value) {
+    if (/^[/\\]/.test(value) || /^[A-Za-z]:/.test(value))
+        return `invalid flag value: --set ${name} must be a relative path, got "${value}"`;
+    const segments = value.split(/[/\\]/);
+    if (segments.includes(''))
+        return `invalid flag value: --set ${name} holds an empty path segment: "${value}"`;
+    if (segments.some((segment) => segment === '.' || segment === '..')) {
+        return `invalid flag value: --set ${name} holds a '.' or '..' path segment: "${value}"`;
+    }
+    return null;
+}
 /**
  * Parse `memory add`'s repeatable `--set <name>=<value>` occurrences (`spec-008-cli-grammar` §10,
  * task-110). The CLI hands every occurrence as a string array; a single string is one occurrence;
@@ -177,14 +352,14 @@ function parseSetOptions(raw) {
             return { ok: false, message: `invalid flag value: --set name "${name}" is not a field name ([a-z][a-z0-9_-]*)` };
         }
         if (RESERVED_SET_NAMES.has(name)) {
-            return {
-                ok: false,
-                message: `invalid flag value: --set cannot set "${name}": memory add fills it itself or through its own option`,
-            };
+            return { ok: false, message: reservedSetMessage(name) };
         }
         if (value.trim().length === 0) {
             return { ok: false, message: `invalid flag value: --set ${name} must not be blank` };
         }
+        const spelling = pathSpellingRefusal(name, value);
+        if (spelling !== null)
+            return { ok: false, message: spelling };
         if (Object.prototype.hasOwnProperty.call(values, name)) {
             return { ok: false, message: `invalid flag value: --set ${name} given more than once` };
         }
@@ -203,20 +378,31 @@ function unknownSetNames(values, idPattern, pathPattern) {
     return Object.keys(values).filter((name) => !tokens.has(name));
 }
 /**
- * Materialize an `id_pattern`'s frontmatter and context tokens (`{kind}`, `{version}`, `{workflow}`,
- * …) from the `--set` values, leaving `{slug}`, the `{n}` family and the not-yet-implemented
- * `{date}`/`{author}` in place — `spec-001`'s fixed expansion order (`{date}` → `{author}` → field and
- * context tokens → `{slug}` → `{n}`), so the `{n}` counter regexp built from the result sees a
- * fully-materialized prefix (task-110).
+ * Materialize an `id_pattern`'s `{date}`, `{author}`, frontmatter and context tokens (`{kind}`,
+ * `{version}`, `{workflow}`, …), leaving `{slug}` and the `{n}` family in place — `spec-001`'s fixed
+ * expansion order (`{date}` → `{author}` → field and context tokens → `{slug}` → `{n}`), so the
+ * `{n}` counter regexp built from the result sees a fully-materialized prefix (task-110). `{date}` is
+ * the UTC `YYYYMMDD` of `sources.date` ({@link formatIdDate}); `{author}` the slug of
+ * `sources.authorName` ({@link slugifyTitle}) — task-163, `bug-158`.
  *
  * @throws {@link ValidationError} naming every field token with no value
- *   (`missing value for token {<name>}: give it with --set <name>=<value>`) and every value outside
- *   the ID character class, in pattern order — the same `E_INVALID_ID` code `generateId` raises.
+ *   (`missing value for token {<name>}: give it with --set <name>=<value>`), an `{author}` whose
+ *   name slugs to nothing, and every value outside the ID character class, in pattern order — the
+ *   same `E_INVALID_ID` code `generateId` raises.
  */
-function expandFieldTokens(idPattern, values) {
+function expandFieldTokens(idPattern, values, sources = {}) {
     const issues = [];
     const expanded = idPattern.replace(TOKEN_RE, (whole, token) => {
-        if (/^n+$/.test(token) || RESERVED_SET_NAMES.has(token))
+        if (token === 'date' && sources.date !== undefined)
+            return formatIdDate(sources.date);
+        if (token === 'author' && sources.authorName !== undefined) {
+            const author = slugifyTitle(sources.authorName);
+            if (author.length > 0)
+                return author;
+            issues.push(fieldIssue(idPattern, `value for token {author} is empty once the git author name "${sources.authorName}" is slugged`));
+            return whole;
+        }
+        if ((0, validation_1.isNumericToken)(token) || RESERVED_SET_NAMES.has(token))
             return whole;
         const value = values[token];
         if (value === undefined) {
@@ -245,7 +431,8 @@ function fieldIssue(pattern, message) {
  */
 function writtenFields(scaffold, values) {
     const { frontmatter } = (0, storage_1.splitFrontmatter)(scaffold);
-    const declared = (key) => frontmatter !== null && new RegExp(`^[ \\t]*${escapeRegExp(key)}:`, 'm').test(frontmatter);
+    // A top-level key only (task-163): a nested key of the same name is not a declaration of the field.
+    const declared = (key) => frontmatter !== null && new RegExp(`^${escapeRegExp(key)}:(?:[ \\t\\r]|$)`, 'm').test(frontmatter);
     return Object.keys(values)
         .sort()
         .filter((name) => !CONTEXT_TOKENS.has(name) || declared(name))