IF Commons GitHub

Planning

0037Draft

0037-planning · owner if · domain commons · part of 0033-kanon

Governance: what an item is and what may happen to it

FR-001checkno test run

The library MUST model an item (plan:Item) as a sum of kinds (plan:Issue, plan:Task, plan:Todo, plan:Finding, the four members of plan:ItemKind) over one shared core that every kind has: an id, a kind, a title, a body, labels, assignees, an optional severity, an origin, the external ids of FR-044, the links of FR-009 and the optional fields the sources carry (the motivation, the blocker flag, the target and the source of a record, and the priority, size, goals, engines, citations and evidence of a typed issue, FR-046); a kind MAY add fields of its own and MUST NOT remove any field of the core.

Enforced (check): .github: cd commons/planning && bun run verify — commons/planning suite/fold.test.ts, vocabulary.test.ts (0002-planning-core FR-001, FR-002): an item is a sum of the four kinds over the shared core, with the carried fields, and the lists are the ontology's

Cited by: planning/planning, governance/item, governance/mod, governance/vocab, Planning, Planning core

FR-002noneno test run

A severity MUST be exactly one of the three members of plan:Severity (plan:Error, plan:Warning, plan:Note), the values of the SARIF result level that apply where the kind of a result is fail (SARIF 2.1.0 section 3.27.9, 3.27.10), and a verdict of a plan:DecidedEvent exactly one of the four members of plan:Verdict (accept, minor revision, major revision, reject), and each closed list MUST be a union of literals with one registry entry for each case, so that a value outside the list does not compile and a parsed value outside it is an error value; WHERE a source has a severity of more levels (the typed issues of data 0044 have critical, high, medium and low), the item MUST carry the source's own value and the matrix of FR-015 MUST say that the three levels are not an exact expression of it.

Enforced (none): Planned, phase 1 in part: the three severities, the four verdicts and the carried value of a source are in commons/planning (0002-planning-core FR-001, FR-002); the statement of the matrix of FR-015 waits for phase 4

Cited by: governance/vocab, Planning, Planning core

FR-003checkno test run

The history of an item MUST be a set of events, each one case of the closed union plan:EventType (opened, commented, edited, labeled, assigned, severity set, blocker set, started, deferred, closed, reopened, decided, linked, confirmed), each with an id (FR-007), a time in UTC to the second (YYYY-MM-DDTHH:MM:SSZ) and an actor (FR-005), and holding the data its source wrote; the ten types of the monorepo's issue files (opened, commented, edited, labeled, assigned, severity, blocker, closed, reopened, decided) MUST each be a case of the union with the data that record holds; an event MUST be immutable once written, and the library MUST have no operation that changes or removes an event.

Enforced (check): .github: cd commons/planning && bun run verify — commons/planning suite/events.test.ts, records.test.ts (0002-planning-core FR-005, FR-011): the fourteen types of event as a closed union, immutable, no operation that changes or removes one, and the ten types of the monorepo's issue files read as cases of it

Cited by: planning/planning, governance/event, governance/time, governance/vocab, Planning, logical/mod, Planning core

FR-004checkno test run

The state of an item (plan:State: proposed, open, in progress, deferred with an until day, closed with a plan:CloseReason) MUST be the result of fold, a pure and total function from the events of the item to its state, with the events taken in the order of their id (FR-007: a UUID version 7 sorts as text in the order its time and its counter give), the first event of an item being its opening; a state MUST NOT be stored as a fact, and WHEN two histories hold the same events in any order or with any repeats, fold MUST give the same state.

Enforced (check): .github: cd commons/planning && bun run verify — commons/planning suite/fold.test.ts (0002-planning-core FR-006): fold is the same for any order and any repeat of the events, by property tests, and the state is never stored

Cited by: planning/planning, governance/item, governance/vocab, Planning, logical/fold, Planning core, Planning sources and the store

FR-005checkno test run

An actor (plan:Actor, a prov:Agent) MUST be of one of the three members of plan:ActorKind (person, agent, tool) with an id and a name; WHERE an agent (an AI agent such as claude) authors an item or an event, its actor MUST be of kind agent and MUST name, in the same actor value, the person on whose behalf it acted, its principal, and how the principal was established (FR-045), by prov:actedOnBehalfOf (PROV-O section 4.1: delegation is the assignment of authority and responsibility to an agent while the agent it acts on behalf of retains some responsibility for the outcome), the principal being an actor of kind person; an event or an item of an agent with no principal MUST be refused when it is built and found as invalid when it is read; an event of a person MUST NOT name an agent and MUST NOT name a principal; a tool MAY name the person who ran it and need not; and a library function MUST refuse to build an event whose actor is a person from a context that has no person's credentials, configuration or argument (FR-045).

Enforced (check): .github: cd commons/planning && bun run verify — commons/planning suite/actors.test.ts, events.test.ts (0002-planning-core FR-004, FR-005): an agent names its principal, a person names none, an agent with no principal is refused when built and when read, and a context with no person makes no person's or agent's actor

Cited by: planning/planning, governance/actor, Planning, Planning core, Planning surfaces

FR-006noneno test run

An item MUST have an origin (plan:Origin: declared, derived or inferred); WHEN an item is inferred by a heuristic or an agent, it MUST start in the state plan:Proposed, MUST NOT be counted by any derived view (FR-021) or any query that is not told to include proposals, and MUST leave plan:Proposed only by a plan:ConfirmedEvent whose actor is of kind person with no principal; an agent MUST NOT confirm any item, its own or another's, and WHEN the configuration (FR-037) says confirmers: "principal" only the principal of the event that proposed the item MUST confirm it, and otherwise (the default) any person MAY, because a proposal belongs to the plan and not to the one who ran the agent.

Enforced (none): Planned, phase 1 in part: fold starts an inferred item proposed and confirms it only by a person, by the policy (commons/planning suite/fold.test.ts); the views and queries that do not count a proposal wait for phase 4

Cited by: planning/planning, governance/item, Planning core, Planning Query relations, Planning reconcile, patches and views

FR-007noneno test run

An item id and an event id MUST each be a UUID version 7 (RFC 9562 section 5.7) as 36 lower case characters, branded by a smart constructor that returns a Result and made by the hybrid clock of AnyFS's merge (@intellectual-frontiers/anyfs/merge: nextTime, seeTime; @intellectual-frontiers/anyfs/governance: makeVersionId, parseVersionId, timeOfId, randomIdBytes, randomCounterSeed), reused and not made again, so that the clock of a replica holds the replica as a field of its own and the id holds nothing of it (the rand_b of an id is random for each id, RFC 9562 sections 5.7, 6.9), every id a replica makes is after every id it has seen, and two stores merge by the union of their events; an id MUST be minted once, MUST NOT change when the item is seen in another place or moves inside a place, and MUST NOT be reused for another item, even after the item is closed; WHEN an event is taken from another store, the next id made MUST come after it (seeTime), and an id whose time is further ahead of the clock than the limit of the configuration (five minutes by default, as AnyFS) MUST be refused.

Enforced (none): Planned, phase 1 and 2 in part: the ids are made by the hybrid clock of anyfs's merge, the next id is after every id seen and a far-future id is refused (commons/planning suite/ids.test.ts); that an id survives a move between places waits for reconcile, phase 3

Cited by: governance/ids, governance/mod, Planning, logical/clock, logical/mod, physical/store, Planning core, Planning sources and the store

FR-008noneno test run

An observation (plan:Observation) MUST be what one source read in one place at one time: the content as the source read it, a locator (plan:Locator, one of the three kinds of plan:LocatorKind: file span, URL, commit), the SHA-256 of the bytes it was read from (plan:contentHash) and a fingerprint of the identity of the thing read (plan:fingerprint) that does not depend on where in the place it is, as a SARIF result's fingerprint is a stable identifier the same for logically identical results and resistant to a change of line number (SARIF 2.1.0 section 3.27.16, 3.27.17).

Enforced (none): Planned: phase 3

Cited by: planning/planning, governance/observation, Planning, Planning core, Planning reconcile, patches and views

FR-009noneno test run

Every item MUST carry a trace (plan:Trace, a PROV-O derivation) to each observation it was derived from, so that every place an item was seen (file and line, URL, commit) can be found from the item, and WHEN an item has no trace to any observation, it MUST be one declared directly in the store; a link (plan:Link) MUST be one of the four plan:LinkKind (blocks, same as, relates to, parent of), and the links of kind blocks MUST make a graph with no cycle: WHEN a link would close a cycle, the library MUST refuse it with the items of the cycle named.

Enforced (none): Planned, phase 1 in part: the cycle check of blocks (commons/planning suite/links.test.ts); the trace to each observation waits for phase 3

Cited by: planning/planning, governance/observation, Planning, logical/links, Planning core, Planning reconcile, patches and views

FR-010noneno test run

A patch (plan:Patch) MUST be a value of a closed union (add an item, add an event, change a state, link, confirm), made for one explicit source, and MUST do nothing until it is applied; a function that makes patches MUST be pure.

Enforced (none): Planned: phase 3

Cited by: governance/patch, Planning, Planning reconcile, patches and views

FR-011noneno test run

A preview (plan:Preview) MUST say exactly what applying a patch would write, to which source and place, with a hash of itself (plan:previewHash); WHEN a write is asked for without a preview that it names by its hash, the library MUST do a dry run and write nothing, and WHEN the preview it is given differs from what the patch would now do, it MUST refuse and write nothing.

Enforced (none): Planned: phase 3

Cited by: Planning, logical/preview, Planning reconcile, patches and views, Planning sources and the store

FR-012noneno test run

The authority over each field of an item MUST be one of the members of plan:FieldAuthority (source wins, store wins, latest wins, person only), set for a source and a field in the typed configuration (FR-037), and the library MUST apply it in fold, over events, and not by overwriting a field: WHERE the authority of a field is person only, an event of an agent or a tool that changes it MUST wait as a proposal and MUST NOT change the state, and an agent that acts on behalf of a person MUST NOT be counted as that person, so that only the person's own event changes the field.

Enforced (none): Planned, phase 1 in part: fold applies the four authorities to each field over the events, and a person-only field waits as a proposal (commons/planning suite/fold.test.ts); the authority for a source and a field comes with the configuration, phase 6

Cited by: planning/planning, governance/item, governance/vocab, logical/fold, Planning core

FR-013noneno test run

A source (plan:Source) MUST be a typed lens over one kind of place with two functions: acquire, which reads a place and returns observations or an error value, and write, which takes a patch and returns the observations the place now holds or an error value (a source gives the plan a patch would carry out, preview, so that the write is held to its hash, FR-011; the plan is what write carries out); a source MUST declare its name and its capabilities (FR-014), and MUST NOT write unless it was given an explicit target.

Enforced (none): Planned: phase 3

Cited by: Planning, physical/source, Planning reconcile, patches and views, Planning sources and the store

FR-014noneno test run

A source MUST declare its capabilities as a set of the members of plan:Capability (read, create, append event, edit, close, assign, delete), and WHEN a patch needs a capability the source does not declare, the library MUST NOT apply the patch to that source and MUST put it in the outbox (FR-033), with the capability named.

Enforced (none): Planned: phase 3

Proved by: planning/suite/views.test.ts

Cited by: planning/planning, Planning, logical/outbox, Planning reconcile, patches and views

FR-015noneno test run

Nothing MUST be dropped silently between what an item says and what a source can hold: each field of an item MUST end, for each source, expressed (the place holds it), carried (it travels in a form the place keeps, such as an anchor or the observation's content as read) or unexpressed with a reason, and a field that ends in none MUST be a kanon/dropped finding of the Kanon check, with the matrix of field by source given as in 0033-kanon FR-023.

Enforced (none): Planned: phase 4

Cited by: Planning, logical/matrix, physical/catalog, Planning reconcile, patches and views, Planning sources and the store

Logical: reconcile, merge, query and views

FR-016noneno test run

WHEN observations are reconciled with the store, reconcile MUST match each observation to an item in this order: the id an anchor in the place carries, then an external id (FR-044), then the fingerprint, then the locator; WHEN none matches, it MUST make a new item whose origin is derived or inferred as the source says, and it MUST return events and links as data and write nothing.

Enforced (none): Planned: phase 3

Cited by: Planning, logical/reconcile, physical/collect, Planning reconcile, patches and views

FR-017noneno test run

WHEN a place and the store disagree, reconcile MUST do a three-way merge of the observation last taken (the base), the observation now read and the store, MUST class each observation against the base as new, unchanged, updated or absent (the four values of the SARIF result baselineState, section 3.27.24) and MUST express each difference as an event whose actor is the source (a tool), so that the field authority of FR-012 decides the result in fold; a difference that no authority decides MUST be a conflict value that names the field, the three values and the sources, and MUST NOT be settled by taking either one silently; two events with one id and different content MUST be a conflict value.

Enforced (none): Planned: phase 3

Cited by: logical/canonical, logical/reconcile, Planning reconcile, patches and views

FR-018noneno test run

WHEN a thing an item was derived from is no longer found in the place (a removed comment, a deleted line: an observation absent in the words of FR-017), reconcile MUST add a derived close, a plan:ClosedEvent with the reason plan:Completed, the origin derived and a tool as actor, and WHEN the same fingerprint is read again, it MUST add a plan:ReopenedEvent; an event by a person MUST win over a derived close.

Enforced (none): Planned: phase 3

Cited by: Planning, logical/reconcile, Planning reconcile, patches and views

FR-019noneno test run

The library MUST find likely duplicates by a similarity of titles, bodies and locators with a threshold set in the configuration, and MUST propose each as a link of kind plan:SameAs in the state proposed that a person confirms, and MUST NOT merge, close or hide an item because of a likeness; the same items and the same threshold MUST give the same proposals in the same order.

Enforced (none): Planned: phase 3

Cited by: Planning, logical/duplicates, Planning reconcile, patches and views

FR-020noneno test run

The library MUST give a query as a typed algebra over the items, the events, the links and the traces (select, filter by state, kind, label, assignee, severity and origin, join, order, limit), pure and read-only, and a surface (FR-036) MUST be a projection of it and not a second definition.

Enforced (none): Planned: phase 4

Cited by: Planning, logical/query, Planning Query relations, Planning reconcile, patches and views

FR-021noneno test run

The library MUST derive these views by pure functions of the items: the roadmap (the items that are counted, in an order that puts an item after every item that blocks it), the graph of blocks and blocked by with its cycle check (FR-009), the matrix of requirement by source that links each item to the requirement it cites (a citation such as FR-014 or 0037-planning FR-014), so that a requirement with no item and an item that cites a requirement that does not exist are each found, and the view of responsibility: for each person, the events their agents authored, by agent, and the proposals of those agents that still wait.

Enforced (none): Planned: phase 4

Cited by: Planning, logical/views, Planning reconcile, patches and views

FR-022checkno test run

The governance and logical code MUST be pure: it MUST read no file, call no network and take no clock; the time of an event or an observation, and the time the hybrid clock of FR-007 is given, MUST come from a value the caller passes in, and the last time of the clock MUST be a value taken and returned.

Enforced (check): .github: cd commons/planning && bun run verify — commons/planning suite/typing.test.ts (0002-planning-core FR-008): the governance and logical sources import no system module and the work runs with the clock, the random source and the network taken away

Cited by: Planning core, Planning reconcile, patches and views

Physical: the sources

FR-023noneno test run

Every source MUST keep the laws of a lens, proved by property tests over generated places: acquire then write of the observations it returned writes nothing and changes no byte; write of a patch then acquire returns the observations with the patch applied and no other change; and acquire twice of an unchanged place returns the same observations in the same order with the same fingerprints.

Enforced (none): Planned: phase 4

Cited by: Planning, physical/conformance, Planning sources and the store

FR-024noneno test run

The source for typed issues in code MUST read the folder issues/ of a library as data 0044-issues FR-002 lays it out (NNNNN-slug.ts, listed in order by mod.ts) as items, keeping every field of an issue (its severity, priority, goals, size, engines, citations, evidence, links, status and day raised) in the observation's content, MUST find a file the barrel does not list and a name the barrel lists with no file, and MUST write a patch back as a change to that file that keeps the rest of it as it was.

Enforced (none): Planned: phase 5

Cited by: Planning, physical/sources/issues, Planning sources and the store

FR-025noneno test run

The source for a folder of event files MUST read each JSON5 file of the monorepo's issue schema erga/issue@1 (and each event object of its store, erga/issue-event@1) as one item with its events, MUST read all ten types of event and all fields of the opening (title, body, labels, assignees, severity, the Web Annotation motivation, blocker, target and source), MUST find a file it cannot read and name why, and MUST write a new event by the rules of that schema, keeping every other byte of the file.

Enforced (none): Planned, phase 2 in part: the issue file, the event object and the summary of the monorepo are decoded, read as an item with all ten types of event and written as they were (commons/planning suite/records.test.ts, and read-only against the monorepo's own files); the source that writes a new event waits for phase 5

Cited by: Planning, logical/records/erga-read, logical/records/erga, logical/records/mod, physical/sources/event-files, Planning core, Planning reconcile, patches and views, Planning sources and the store

FR-026noneno test run

The source for Markdown MUST read each task list item of GitHub Flavored Markdown as an item: a list item whose first block is a paragraph that begins with a marker (optional spaces, [, one whitespace character or x or X, ]) and at least one whitespace character before any other content (GFM 0.29-gfm section 5.3), under any list marker the list allows (-, +, *, or an ordered number with . or )), unchecked where the character is whitespace and checked otherwise, nested items as sub-items linked plan:ParentOf, in any Markdown file, in a Spec Kit tasks.md and in a task list of the body of a GitHub issue, and WHEN an item is closed, write MUST change the one character between the brackets to x and WHEN it is reopened, to a space, and no other byte of the file.

Enforced (none): Planned: phase 5

Cited by: Planning, physical/sources/markdown, Planning sources and the store

FR-027noneno test run

The source for comments in source files MUST read a comment that carries one of the markers set in the configuration (TODO, FIXME, XXX and HACK by default, the markers the documentation scan of Docs reads) as an item, with the fingerprint of the comment's normalized text and the symbol that encloses it, so that the id survives a move of the line; WHERE a marker is written back, write MUST insert an anchor of the form TODO(#id) and MUST do so only for the files the configuration lists, and never in a generated or a vendored file.

Enforced (none): Planned: phase 5

Cited by: Planning, physical/sources/comments, Planning sources and the store

FR-028noneno test run

The source for a Git host MUST read the issues of a repository (the number, title, body, state, url, labels, parent and children that the host contract holds) and the references of its commits (the line Refs #N that repoctl commit writes and the closing keywords of the host: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved) as items, links and traces, through the Git host contract of the library githost and never a client of its own, and MUST write only what the host's capabilities and the token's grants allow; a field the contract does not hold (the close reason, the assignees, the comments, the events) MUST be unexpressed with that reason until the contract holds it.

Enforced (none): Planned: phase 5

Cited by: Planning, physical/sources/githost, Planning sources and the store

FR-029noneno test run

A source that reads files MUST be written against a store of AnyFS (@intellectual-frontiers/anyfs) whose capabilities are in its type, so that the same source works over a folder, Git, S3, SSH and SQL; WHEN it writes, it MUST state the revision it read as the expectation of the write, and a write that finds the file changed MUST be a conflict value and change nothing.

Enforced (none): Planned: phase 5

Cited by: Planning, physical/file-source, Planning sources and the store

FR-030noneno test run

The library MUST give defineSource, which makes a source from a typed record (its name, its capabilities, acquire and write) and refuses a record whose write is present when capabilities says it cannot write, so that a person can add a source (a SQL table, a tracker) with no change to the library.

Enforced (none): Planned: phase 5

Cited by: Planning, physical/source, Planning sources and the store

FR-031noneno test run

The library MUST reserve the names of the sources that are not yet written (SARIF files, skipped and todo tests, Dependabot and Renovate pull requests, iCalendar to-dos, Linear, Jira, and the findings of the Quality System and of pen tests), and a source of the list MUST NOT be written before the specification of the standard or the service it reads has been read and cited.

Enforced (none): Planned: phase 5

Cited by: Planning, physical/catalog, Planning reconcile, patches and views, Planning sources and the store

FR-032noneno test run

A write MUST need an explicit target (a source and a place), MUST be a dry run unless it names a preview by its hash (FR-011), and the command in check mode MUST print the hash of the preview and exit with a status that says whether anything would change, so that a headless run applies exactly the plan a person looked at.

Enforced (none): Planned: phase 6

Cited by: Planning, logical/preview, physical/planctl, physical/source, Planning reconcile, patches and views, Planning sources and the store, Planning surfaces

FR-033noneno test run

The library MUST keep an outbox of the patches that no source could apply (FR-014), each with the reason, as items of the store that a person can read, and MUST offer each again WHEN a source that can apply it is given as a target.

Enforced (none): Planned: phase 3

Cited by: Planning, logical/outbox, logical/records/trace-file, Planning reconcile, patches and views

Physical: surfaces, configuration and formats

FR-034noneno test run

The program planctl MUST be a headless program of the library Headless (commons/headless) with the verbs collect, show, query, views, confirm, plan and apply, each returning a typed outcome and printing through a surface, and plan and apply MUST be the dry run and the write of FR-032.

Enforced (none): Planned: phase 6

Cited by: Planning, physical/collect, physical/planctl, Planning surfaces

FR-035noneno test run

The library MUST give a tool server of the same verbs, as a surface that is a projection of the same program, in which a tool that writes MUST take the target and the preview hash as arguments, an agent that calls it MUST be an actor of kind agent with its principal (FR-005), the principal MUST be the person the server's session was launched for (FR-045), and a call with no principal MUST be refused.

Enforced (none): Planned: phase 6

Cited by: Planning, physical/planctl, Planning surfaces

FR-036noneno test run

The library MUST give the items as relations of SQL, read-only, in a plugin planning-query in the way estate-query and anyfs-query do, with the relation issues having a column for each field of the core of FR-001 and the state of FR-004 (and the columns the monorepo's relation of that name has, id, title, state, reason, severity, blocker, labels, assignees, comments, opened_at and updated_at, where the item has the field), so that the statements of the SQL of lang-sql and agora query read it; the relations MUST be made from the same types and not written a second time.

Enforced (none): Planned: phase 6

Cited by: Planning Query relations

FR-037noneno test run

The configuration MUST be a typed value in planning.config.ts, made by definePlanning, that names the sources and their places, the markers, the threshold of FR-019, the authority of each field for each source (FR-012), the files that anchors may be written to (FR-027), the principal of a run (FR-045), the rule that makes an actor an agent acting for a person (FR-044), confirmers (FR-006), the clock's limit (FR-007) and the formats to render; a configuration MUST NOT be read from JSON or YAML, and a configuration that does not satisfy its type MUST be an error value naming the field.

Enforced (none): Planned: phase 6

Cited by: Planning, logical/config, physical/world, Planning surfaces

FR-038checkno test run

The store and the published edition MUST be files in a format that the library encodes and decodes at its boundary, JSON5 by default (the codec of formats, JSON5 1.0.0), the store with one file for each event (<item>/<event>.json5, so that two stores merge by the union of files) and the published edition with one file for each item that holds its events in the order of fold, each with an order of keys that does not change (the order of RFC 8785 section 3.2.3: by property name, recursively), so that a diff of two stores is a diff of events; decoding MUST be total and give an error value for a file that is not an item or an event of the schema.

Enforced (check): .github: cd commons/planning && bun run verify — commons/planning suite/records.test.ts (0002-planning-core FR-011): one JSON5 file for each event and each item, keys in the order of RFC 8785 section 3.2.3, and a total decoder

Cited by: Planning, logical/records/mod, logical/records/store, logical/records/trace-file, physical/store, Planning core, Planning sources and the store

FR-039noneno test run

The library MUST render items in a format by a function from items to bytes that is pure (Markdown, JSON5, SQL, and later iCalendar), and a renderer MUST be given by the configuration; WHEN a format cannot hold a field, the rendering MUST say so by the rule of FR-015 and MUST NOT drop it silently.

Enforced (none): Planned, phase 2 in part: the summary of the monorepo's issues is rendered from items by a pure function (commons/planning suite/records.test.ts); the renderers named by the configuration wait for phase 6

Cited by: Planning, logical/records/erga-index, logical/records/render, Planning core, Planning reconcile, patches and views, Planning surfaces

The library and how it is built

FR-040noneno test run

commons/planning MUST be a Kanon library (0033-kanon FR-009, FR-010) whose table has the layers governance (the kinds, the events, the states, the severities, the patches, the capabilities), logical (fold, reconcile, the merge, the query, the views), and physical (the surfaces and the sources' port), with the sources as plugins of the family planning-<noun> whose contract is the export that says what a source is (0033-kanon FR-020, FR-021), and its verify MUST run the check of @intellectual-frontiers/kanon.

Enforced (none): Planned, phase 0 in part: the library is Kanon with its three layers and its verify runs the check of kanon; the patches, reconcile, the queries and the surfaces wait for phases 3 to 6

FR-041checkno test run

The governance and logical code MUST be typed as an algebra (0033-kanon FR-018): a closed union for each thing with a fixed set of cases, a product type for each record, every field readonly and every optional field exact (exactOptionalPropertyTypes), a branded id for each kind of id made by a smart constructor that returns a Result, every switch over a union exhaustive and ending in default: return absurd(x), errors as values of Result, and no any, no non-null !, no enum and no cast but brand.

Enforced (check): .github: cd commons/planning && bun run verify — commons/planning suite/typing.test.ts (0002-planning-core FR-009): no any, non-null assertion, enum or cast but brand, readonly and exact optional fields held by the compiler, every switch closed

Cited by: governance/vocab, Planning, Planning core, Planning reconcile, patches and views

FR-042noneno test run

A source MUST be a package of its own, planning-<noun>, importing the host only by its public exports and no other source, and MUST pass the conformance suite of the host, which runs the laws of FR-023 over its generated places.

Enforced (none): Planned: phase 5

Cited by: Planning, physical/conformance, Planning sources and the store

FR-043noneno test run

A term of the model MUST be one of the ontology plan: before a specification or code names it, with its basis (0018-standards-first FR-003), and a name taken from a standard MUST be one read in the standard's own text and cited with its version and section (the table of Standards considered); WHERE a term needs a custom type that no standard or existing type carries, it MUST be listed as an open question and confirmed by the owner before it is written.

Enforced (none): Planned: the ontology names every list of the library, held by commons/planning suite/vocabulary.test.ts; the rule over every term of the model waits for phase 4

FR-044checkno test run

WHEN a record is read that has an id of another scheme (a ULID, an id of a build finding, a number of a host or of a library's issues), the source MUST carry that id as an external id of the item or the event, as the source named it (the source's name and the value), and MUST NOT write history into the id's wording; an external id that is a valid ULID MUST give its item or event id by a pure function: the 48-bit time of the ULID as the unix_ts_ms of a UUID version 7 and the first 74 of the 80 random bits as rand_a and rand_b (RFC 9562 section 5.7; ULID, 48 bits of time and 80 of chance), so that two stores that read one file make the same ids and merge with no duplicate; an id that is not a ULID MUST give its id by the same function from the time of its event and the SHA-256 of the external id; and WHEN the configuration says that an actor id is an agent acting for a person, the source MUST read the actor so, and otherwise MUST read the actor of the file as the file says and report each agent recorded as a person as a finding.

Enforced (check): .github: cd commons/planning && bun run verify — commons/planning suite/legacy-ids.test.ts (0002-planning-core FR-010): the id of a ULID and of another scheme, the external ids and the actors of a file by the rule of the configuration

Cited by: governance/ids, Planning, logical/legacy-id, logical/mod, logical/records/erga-read, Planning core, Planning reconcile, patches and views

FR-045noneno test run

The principal of an agent's event MUST be established from who is running the work and never guessed: from the person whose credentials, session or argument launched the program (a tool server's principal is the authenticated person of its session) or, for a headless run, the principal of the configuration; a source MAY derive the principal from the author of a commit (a commit whose author is a person and whose trailer Co-Authored-By names an agent, as the rule of repoctl commit of this repository makes it) only WHERE the configuration names that rule, and the actor MUST record how its principal was established, one of the four members of plan:PrincipalBasis (session, argument, configuration, commit author), stored with the actor and not only checked when the event is written; WHERE no principal is established, the library MUST refuse to write the event and MUST say so.

Enforced (none): Planned, phase 1 in part: a run's context makes an agent's actor with the basis stored and refuses a person or an agent where there is no person (commons/planning suite/actors.test.ts); the tool server, the headless run and the commit-author case over a real Git repository wait for phase 6

Cited by: planning/planning, governance/actor, governance/vocab, Planning, logical/config, physical/world, Planning core, Planning surfaces

FR-046noneno test run

Every field of a record that a source reads MUST be kept: a field that the core of FR-001 holds MUST be in the item, as the source wrote it, and WHERE the core has no field for it, the observation MUST keep it as read (FR-008) and the matrix of FR-015 MUST say it is carried, so that nothing of the issue records of inventory.md is dropped.

Enforced (none): Planned, phase 2 in part: an issue file's every key is carried or found (commons/planning suite/records.test.ts); the other sources wait for phase 5

Cited by: governance/event, governance/observation, Planning, logical/records/erga-read, physical/catalog, Planning reconcile, patches and views, Planning sources and the store

FR-047noneno test run

A journal (the hash-chained entries of a day's file journal/YYYY/MM/DD.jsonl of Evidence Capture) MUST NOT be read as items by any source and MUST NOT be changed; an item MAY cite an entry by a locator of kind file span that names the day's file and the line, with the entry's digest as the fingerprint of the observation, and a finding of a check MAY be an item of the kind plan:Finding through a source of its own (FR-031).

Enforced (none): Planned: phase 5

Cited by: Planning, physical/catalog, Planning sources and the store

Standards considered

Each standard below was read from its primary text on 2026-11-21 (the document, its version and the section are in the table; none is quoted from memory). An IRI is written only where it was read. A name that is in the text is stated as the text states it; a design choice of Planning is marked as the library's.

Standard (version)What Planning takes from itSection readCorrected against the first draft
W3C PROV-O, Recommendation 30 April 2013; namespace http://www.w3.org/ns/prov# (section 1.3)prov:Entity, prov:Activity, prov:Agent, prov:wasGeneratedBy, prov:wasDerivedFrom, prov:wasAttributedTo, prov:wasAssociatedWith, prov:actedOnBehalfOf (domain and range prov:Agent) are starting point terms (4.1); prov:Person, prov:SoftwareAgent, prov:hadPrimarySource (a sub-property of prov:wasDerivedFrom, prov:Entity to prov:Entity) are expanded terms (4.2); prov:Derivation (a subclass of prov:EntityInfluence, which qualifies prov:wasDerivedFrom), prov:Delegation (a subclass of prov:AgentInfluence, with prov:hadActivity and prov:agent, qualifying prov:actedOnBehalfOf) and prov:qualifiedDelegation (from a prov:Agent to a prov:Delegation) are qualified terms (4.3)1.3, 4.1, 4.2, 4.3A prov:Activity "occurs over a period of time" (4.1): an event of an item is an instant, so the class plan:Event specializes it as the audit already says and a time is data (plan:eventAt) and not prov:startedAtTime. prov:Derivation is an influence and not an entity, which is why plan:Trace specializes it and no other class does
OASIS SARIF 2.1.0 Plus Errata 01, OASIS Standard 28 August 2023The result level is warning, error, note or none, and none only where kind is not fail (3.27.10); kind is pass, open, informational, notApplicable, review or fail, fail by default (3.27.9); fingerprints and partialFingerprints are objects of strings keyed by a versioned name (3.27.16, 3.27.17); baselineState is new, unchanged, updated or absent, and a result management system might file an issue on new, edit it on updated and resolve it on absent (3.27.24, note 2); suppressions hold kind inSource or external and status accepted, underReview or rejected (3.27.23, 3.35); locations, ruleId and workItemUris are properties of a result (3.27.12, 3.27.5, 3.27.27); a physicalLocation holds an artifactLocation and a region with startLine (3.29, 3.30.5)3.27, 3.29, 3.30, 3.35The three severities are the levels that apply to a fail result and not all of level; none is not a severity. The default level where it is absent is warning, and a result's fingerprint is a SARIF term, so plan:fingerprint is the same idea under the library's own name
W3C Web Annotation Data Model, Recommendation 23 February 2017, and Web Annotation Vocabulary, Recommendation 23 February 2017 (namespace http://www.w3.org/ns/oa#, vocabulary 1.1)The motivations, instances of oa:Motivation, are assessing, bookmarking, classifying, commenting, describing, editing, highlighting, identifying, linking, moderating, questioning, replying and tagging (model 3.3.5; vocabulary 2.3.1 to 2.3.13, each IRI http://www.w3.org/ns/oa#<name>); there SHOULD be exactly one motivation for each annotation (3.3.5); a TextQuoteSelector has exactly one exact and at most one prefix and one suffix (model 4.2.4)Model 3.3.5, 4.2.4; vocabulary 1.1, 2.3The first draft named three motivations; there are thirteen. The monorepo's record keeps one, as the text says a record SHOULD, and uses commenting by default and assessing for a build finding
IETF RFC 5545 (iCalendar), September 2009The STATUS of a VTODO is NEEDS-ACTION, COMPLETED, IN-PROCESS or CANCELLED (3.8.1.11); PERCENT-COMPLETE is an integer from 0 to 100 (3.8.1.8); PRIORITY is an integer from 0 to 9, 0 undefined and 1 highest (3.8.1.9); RELATED-TO takes the RELTYPE PARENT (the default), CHILD or SIBLING (3.8.4.5, 3.2.15)3.6.2, 3.8.1.8, 3.8.1.9, 3.8.1.11, 3.8.4.5, 3.2.15PRIORITY is the importance of a task and plan:Severity is how serious a problem is: they are two things (OSLC also keeps them apart) and Planning does not take PRIORITY for severity. A closed item is COMPLETED or CANCELLED by its reason, and the library's mapping of a reason to one of them is its own
IETF RFC 9253 (iCalendar relationships), August 2022, Standards Track, updates RFC 5545RELTYPE=DEPENDS-ON: the current component depends on the referenced one, so that "a task may be blocked waiting on the other" (section 5); the temporal types FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH, STARTTOSTART sit in the predecessor and refer to the successor (section 4); RELATED-TO may be in any component and take a URI or a UID (9.1)4, 5, 9.1The direction is the reverse of plan:Blocks: the blocked item holds the DEPENDS-ON that names the blocker
OASIS OSLC Change Management 3.0, OASIS Standard with Approved Errata 01, 6 July 2023 (Part 1 specification, Part 2 vocabulary, Part 3 constraints; namespace http://open-services.net/ns/cm#)A oslc_cm:ChangeRequest with the properties dcterms:title, dcterms:description, dcterms:identifier, dcterms:subject, dcterms:contributor, dcterms:created, dcterms:modified (Part 3, 2.1); oslc_cm:state of the individuals Closed, Inprogress, Fixed, Approved, Reviewed, Verified (Part 2, 3.1) and the predicates closed, inProgress, fixed, approved, reviewed, verified (Part 1, 2.9); oslc_cm:priority High, Medium, Low, PriorityUnassigned (3.2); oslc_cm:severity Blocker, Critical, Major, Normal, Minor, SeverityUnassigned (3.3); oslc_cm:parent, oslc_cm:relatedChangeRequest; servers MAY have custom states and SHOULD relate them with skos:narrower (Part 2, 3)Part 1 2.9; Part 2 2.1, 3; Part 3 2.1OSLC Change Management defines no history of events, so the events are Planning's own. The Part 2 text says its states are values of oslc_cm:status, and Part 1 says status is deprecated for state: the text disagrees with itself and Planning takes state. The severity Blocker is a level of severity and is not the monorepo's blocker flag
GitHub Flavored Markdown, version 0.29-gfm (2019-04-06)The task list item extension (5.3): a list item whose first block is a paragraph that begins with a marker of optional spaces, [, a whitespace character or x or X, ], and at least one whitespace character; unchecked for whitespace, otherwise checked; nested without limit (examples 279, 280)5.2, 5.3The first draft read - [ ] and - [x]: the marker is the text above and not a list marker, X is checked, +, * and ordered markers hold, and the spec does not say how a checkbox is changed. GitHub's own page says to use a hyphen and a space and [x], which is narrower than the extension
GitHub Docs, REST API version 2026-03-10; issue linking and issue relationsThe state of an issue is open or closed; the state_reason is completed, not_planned, duplicate, reopened or null, and duplicate_issue_id goes with duplicate (REST, update an issue); the closing keywords are close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved, with KEYWORD #N or KEYWORD OWNER/REPOSITORY#N, in a pull request description or a commit message, and act on the default branch; sub-issues up to 100 for each parent and eight levels, and an issue may be marked blocked by or blocking anotherREST issues; linking a pull request to an issue; adding sub-issues; creating issue dependenciesThe reasons for closing are three and a fourth value reopened is the reason of the opposite change. Refs #N is not a closing keyword and is not named by the pages read
git interpret-trailers (git-scm.com documentation)A trailer is a key and a value with a colon as the separator, the key of ASCII letters, digits and hyphens, in a block after a blank line; only : is recognized by default (trailer.separators changes that)Description; trailer.separatorsThe line Refs #N has no colon, so Git does not read it as a trailer by default; it is a convention of this repository (repoctl.config.ts), and Co-Authored-By: ... and Claude-Session: ... are trailers
IETF RFC 9562 (UUIDs), May 2024, Standards TrackUUIDv7: 48-bit big-endian unix_ts_ms, version 7, rand_a of 12 bits, variant 10, rand_b of 62 bits (5.7); counters in rand_a and rand_b and clock precision in rand_a keep order within a millisecond (6.2, methods 1 to 3); sortable as raw bytes and as text (6.11); a node id belongs in a UUIDv8 (6.4)4, 5.7, 6.2, 6.4, 6.11AnyFS's makeVersionId fills rand_a with a counter that starts at a random seed below 2048 in each new millisecond and grows by one (method 1) and rand_b with 62 random bits for each id, so that it is a version 7 as section 5.7 words it and holds no node identity (6.4)
ULID specification (github.com/ulid/spec, README; no version number)128 bits: 48 bits of time in milliseconds since 1970 and 80 bits of randomness; 26 characters of Crockford base 32 (0123456789ABCDEFGHJKMNPQRSTVWXYZ); sorted as text; within one millisecond the order is not guaranteed; the largest is 7ZZZZZZZZZZZZZZZZZZZZZZZZZComponents, Sorting, Canonical string representation, Overflow errorsThe second precision of the monorepo's event time and the unordered millisecond of a ULID are the reasons the real fold orders by time and then id and the reason a new event there is made to come after the latest
IETF RFC 8785 (JSON Canonicalization Scheme), June 2020, InformationalProperties sorted recursively by name, arrays not reordered (3.2.3); data in the I-JSON subset (3.1)3.1, 3.2.3None; it is the model of the order of keys, not a requirement that the files be canonical JSON
JSON5 1.0.0, March 2018A superset of JSON with comments, unquoted keys and trailing commasAbstract, commentsNone
SKOSEvery code list is a conceptTerms held by rdf (not re-read in this pass)Unchanged
RFC 2119, EARS, GherkinThe form of this specificationAdopted by 0003-mizan (not re-read in this pass)Unchanged

The terms that no standard names (the sum of kinds, the fold of a history into a state, a derived close, a patch, a preview and an outbox) are in plan: with a basis of PROV-O or SKOS, and none is unaligned.

The existing records and what is deliberately more general

The monorepo's issue record (entries 1 to 6 of inventory.md) has: ten event types; the states open and closed with three reasons; an actor of type person, agent or tool, an id and a name; a ULID for an issue and for each event; a time to the second; a fold in the order of time and then id with the first event an opening; the union of events by id and the smaller canonical text where two differ. Planning covers all of it and differs in these places, each deliberate.

PlaceThe monorepoPlanningReason
Event typesTen, named severity and blocker for twoFourteen: the ten (the two as plan:SeveritySetEvent and plan:BlockerSetEvent) and started, deferred, linked, confirmedstarted, deferred and linked for the places that hold them (inventory.md 7, 10); confirmed for the owner's rule on proposals
Statesopen, closedproposed, open, in progress, deferred, closedin progress and deferred (with its until day) are data 0044's; proposed is the owner's rule
Actortype, id, name; the existing agent claude is written as type personAdds the principal, prov:actedOnBehalfOf, a person, for an agentThe owner's decision; the monorepo's decoder and encoder read and write type, id and name only, so a Planning write through them would lose the principal: the matrix says unexpressed until that schema gains the field (OQ-10)
IdsA ULID; f- and hex for a finding; ev-... for a toolUUID version 7 by the hybrid clock; every other id an external idThe owner's decision; FR-007, FR-044
OrderThe time text, then the id textThe idIds made by the hybrid clock are after every id seen; legacy ids give ids in the same order except where two events of one second hold ids of two forms (a ULID and a tool's), which a property test against the real fold on made-up files reports
Same id, two contentsThe smaller canonical text winsA conflict valueFR-017: nothing is settled silently
Severityerror, warning, note, from SARIFThe same three; a source with more levels carries its ownFR-002
Fields beyond the coremotivation, blocker, target, sourceOptional fields of the item, as the source wrote themFR-001, FR-046
Findings of a buildMade issues by the sync, closed by a tool when no longer found, reopened by a toolThe same by FR-018None

Acceptance scenarios

  1. Given a history of events in one order and the same events in another order with one repeated, When each is folded, Then the two states are equal, per FR-003 and FR-004.
  2. Given an item an agent inferred from a heuristic, When the roadmap is derived, Then the item is not in it, and When a person's confirmed event is added, Then it is, per FR-006 and FR-021.
  3. Given an event built by the agent claude for the person who launched the session, When its actor is made, Then the actor is of kind agent and names that person as its principal, and an agent with no principal is refused, per FR-005.
  4. Given an event of a person that names an agent, When it is built or read, Then it is refused as invalid, per FR-005.
  5. Given an item proposed by an agent for a person, When the agent tries to confirm it, Then it is refused, and When a person confirms it, Then it leaves the state proposed, and When the configuration says confirmers: "principal", Then only the principal's confirmation counts, per FR-006.
  6. Given a field whose authority is person only and an event of an agent that changes it, When the item is folded, Then the state is unchanged and the change waits as a proposal naming the agent and its principal, per FR-012 and FR-021.
  7. Given a headless run with no principal in the configuration and no argument, When an agent's event is to be written, Then the library refuses and says that no principal is established, per FR-045.
  8. Given a Markdown file with a task list item nested under another, When it is read and the item is closed and written back, Then only the character between the brackets of that line became x and the item is a sub-item of the first, per FR-026 and FR-023.
  9. Given a comment TODO: tidy inside a function, When the function moves down the file and the file is read again, Then the item keeps its id, per FR-016 and FR-027.
  10. Given an item derived from a comment, When the comment is removed and the file is read, Then the item is closed as completed by a tool, and When the comment is restored, Then it is reopened, per FR-018.
  11. Given a patch that closes an item in a source that cannot close, When the patch is applied to it, Then nothing is written and the patch waits in the outbox with the capability named, per FR-014 and FR-033.
  12. Given a write with no preview hash, When the command runs, Then it prints the preview and its hash and writes nothing, and When it is run with that hash, Then it writes exactly that, per FR-011 and FR-032.
  13. Given a link of kind blocks that would close a cycle, When it is added, Then it is refused naming the items, per FR-009.
  14. Given a file read over a store of Git and written back after another change to it, When the write states the revision it read, Then the write is a conflict and the file is unchanged, per FR-029.
  15. Given two items with nearly the same title, When duplicates are sought, Then a proposed link of kind same as is made and both items stay open, per FR-019.
  16. Given a field that a source cannot hold, When the matrix is made, Then the cell says unexpressed with its reason, and with no reason it is a finding, per FR-015.
  17. Given two stores that each made events of one item with their own replica, When they are merged, Then the union of the events is the history, with no conflict and in any order, and the next id made after the merge is after every id taken, per FR-007.
  18. Given an issue file whose ids are ULIDs, When two stores read it, Then they make the same item id and the same event ids, each ULID is an external id, and no id's wording says where it came from, per FR-044.
  19. Given an issue file in which the agent claude is written as a person, When it is read with no rule in the configuration, Then the actor is read as the file says and a finding names each such event, and When the configuration says the id is an agent acting for a person, Then it is read as an agent with that principal, per FR-044.
  20. Given an entry of a journal, When an item cites it, Then the locator names the day's file and the line, its fingerprint is the entry's digest and the journal is unchanged, per FR-047.
  21. Given a typed issue of data 0044 with the severity high, the priority P2 and the status deferred, When it is read, Then the item holds the fields as read, the state is deferred with its until day, and the matrix says the severity is carried as the source's own value and not expressed by the three of the model, per FR-002, FR-004 and FR-046.

Out of scope

  • A user interface, a calendar, a time tracker and estimates: Planning holds what is planned, not who does it when.
  • The typed issues of the weaknesses of a library of commons/data and their copy in a database: FR-024 makes them a source of Planning, and this specification does not change them; the database copy stays as the specifications of commons/data have it (data 0044-issues and data 0045-issues-model).
  • The findings of the Quality System, pen test findings of Opsfolio and the like: a later phase, after experience with the library; inventory.md says where each would attach and nothing is modeled for them now.
  • The monorepo's issue schema: Planning reads and writes it as it is; a change to it (OQ-10) is the monorepo's.
  • The release, the version and the publication of the package: the release of commons.

Edge cases

  • A comment written twice with the same words in one function: the fingerprint is the same, so the order of the two in the function is part of the identity, per FR-016 and FR-027.
  • A line of a task list edited in a place and its item edited in the store at the same time: a conflict value naming the title and its three values, never a silent choice, per FR-017.
  • A source that cannot write at all (a SARIF file, a read-only host): every patch for it goes to the outbox, per FR-014 and FR-033.
  • A person closes an item and a later read of a place finds its text again: the person's event wins over the derived reopening, per FR-018.
  • An item seen in three places: it has three traces and one id, and a close in one place is a patch to the other two, per FR-009 and FR-010.
  • A requirement cited by no item: found by the matrix, per FR-021.
  • A format that cannot hold links (a plain list): the rendering says so and the links are unexpressed with that reason, per FR-039 and FR-015.
  • A configuration in JSON beside planning.config.ts: not read, per FR-037.
  • A write to a file in a vendored folder that the configuration does not list: refused, per FR-027.
  • A task list item whose character between the brackets is a tab or an uppercase X: read as unchecked and as checked, and written back as the library writes it, per FR-026.
  • An event whose id is further ahead of the clock than the limit: refused when it is taken, per FR-007.
  • An agent acting for a person who is later removed from the configuration: the events keep their principal as written; only a new event needs one that is established, per FR-005 and FR-045.

Assumptions

  • The library is Kanon (0033-kanon), uses AnyFS for every file, githost for Git hosts and Headless for its program, as the libraries of commons do.
  • Items are public text unless a store is private: Planning holds no secret, no token and no person's data of its own, and its fixtures are made-up or public.
  • A dataset of audit findings that a person offers is a candidate fixture, never assumed to be available.
  • The monorepo's issue files are private and are not copied here: a test of the source for them (FR-025) runs over made-up files of the same schema.

Open questions

OQ-1open question

(closed by the owner): The name planning for commons/planning is confirmed. The specification stays Draft until the library is built.

OQ-2open question

(closed by the owner): The store and the published edition stay JSON5 at the boundary, encoded and decoded by the library (FR-038).

OQ-3open question

(closed by the owner, decided here): Findings join as the kind plan:Finding, through a source of their own (FR-031). Journal entries stay a journal: the journal of Evidence Capture is a file for each day of hash-chained entries (grc.ledger-entry: seq, previous, type, subject, evidence, digest), so an entry is a line of a file and not a row of a table, and an item cites it by a locator of kind file span and the digest as fingerprint (FR-047); the locator kind row is cut (OQ-9).

OQ-4open question

(closed by the owner): Item and event ids are UUID version 7 made by the hybrid clock of AnyFS's merge, reused (FR-007); a ULID and every other id is carried as an external id (FR-044).

OQ-5open question

Whether the derived close of a removed comment is completed (FR-018) or a state of its own, unobserved, that a person settles. The monorepo's sync closes it as completed.

OQ-6open question

Overlap, as found (inventory.md, the section on overlap in the report): the typed issues of a library and their database copy are a source of Planning (FR-024) and are held by data 0044-issues and data 0045-issues-model; docs has a scan of notes in the code (commons/docs/src/pages/insight.ts: TODO, FIXME, XXX, HACK in .ts files, 140 characters) that the comments source (FR-027) would serve; githost owns the Git host contract (IssueInfo) and holds no close reason, assignee or comment; integrations-github holds no issue; repoctl writes the Refs #N line. The issue cross-referencing and the view of Kanon that the session on IFC Data is said to work on are not found in this repository, in any of its references (main and every branch): the only cross-reference in a specification is 0033-kanon FR-017, between the ladder and Kanon, which is not about issues. Who owns what is for the owner.

OQ-7open question

(closed by the owner): The prefix is plan:.

OQ-8open question

Whether sources are plugins of the family planning-<noun> (the way the backends of AnyFS are) or dialects planning-dialect-<noun> in the sense of 0033-kanon FR-019, which says what a dialect is.

OQ-9open question

(closed by the owner on 2026-11-21): The custom types and fields this specification proposed, each decided. Cut: the item kinds RoadmapItem, Question and Decision (the kinds are Issue, Task, Todo and Finding; the verdicts stay as the data of the decided event), the event seen, the link kind derived from and the locator kind row. Kept: (1) the item kinds Issue, Task, Todo, Finding; (2) the events started and linked; (3) the link kind relates to; (4) the state deferred with an until day, reached by the event deferred, which a state that is a fold needs; (5) the carried fields of the monorepo's record, motivation, blocker, target and source; (6) the fields of data 0044, priority, size, goals, engines, cites, evidence and the day raised; (7) a severity of four levels, carried as the source's own value; (8) the external id, a source's name and a value, on an item and an event; (10) the field authorities latest wins and person only; (11) a stored record of how a principal was established (plan:PrincipalBasis: session, argument, configuration, commit author).

OQ-10open question

The monorepo's issue schema has no field for a principal, and its writer drops a key it does not know; Planning writes an agent's event there only when that schema gains an optional onBehalfOf of a person (an additive change that is the monorepo's to make); until then the matrix says the principal is unexpressed.

OQ-12open question

The until of a deferred typed issue (data 0044) is free text and the until of a deferred item (FR-004) is a day. Until the owner says how one is carried into the other (an optional day on the state, or a carried text), a deferral whose text is not a day is read as open with a finding that holds the text (commons planning 0004-planning-sources OQ-1). Of the thirteen issues of commons/data today, one is deferred, with text.

OQ-13open question

The terms the built code names that plan: does not hold: the four classes of an observation against its base (new, unchanged, updated, absent: SARIF baselineState, a standard's own values), the conflict value of FR-017, the outbox entry of FR-033 and whether a trace's thing is present or absent. The first is a standard's and only needs its entry; the other three are the library's own and are not in the ontology until the owner confirms them (FR-043).

OQ-14open question

A closed issue of a Git host is read as closed as completed because the host contract (githost) holds no close reason, and a close state needs one. Whether the state should allow an unknown reason, or githost should hold the reason, is the owner's.

OQ-15open question

The authority of a field is one for the field in the configuration and in fold; FR-012 and FR-037 say it is set for a source and a field. Keying it by the source needs fold to know which tool an event came from, which the actor of a tool already says: the owner's decision whether to build it before a configuration needs two sources to disagree.

OQ-11open question

Whether the markers of the comments source also include @todo; the first draft listed it and no record or standard read names it, so it is removed until a record needs it.

Key entities

  • Item - one thing planned, of one of the kinds, with a stable id and a history of events.
  • Event - one immutable thing that happened to an item, by an actor.
  • Actor - a person, an agent or a tool; an agent names the person it acts for.
  • Observation - what one source read in one place, with its locator and hash.
  • Patch - a change to write back to one source.
  • Preview - what a patch would write, with the hash a write is held to.
  • Source - a lens over one kind of place, with its capabilities.

Success criteria

SC-001success criterion

One thing planned is one item with one id however many places it is in, and every place it was seen can be found from it.

SC-002success criterion

A write changes only what the preview said, in the form of the place, or it changes nothing and says why.

SC-003success criterion

A person can add a source in a typed configuration and a typed function, with no change to the library.

SC-004success criterion

Every event an agent wrote names the person responsible for it, and no agent's event is counted as a person's.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Findings, logical/planning, generate-ontology, Ontology, planning/mod, planning/planning, governance/actor, governance/event, governance/ids, governance/item, governance/mod, governance/observation, governance/patch, governance/time, governance/vocab, Planning, logical/canonical, logical/clock, logical/config, logical/duplicates, logical/fold, logical/legacy-id, logical/links, logical/matrix, logical/mod, logical/outbox, logical/preview, logical/query, logical/reconcile, logical/records/erga-index, logical/records/erga-read, logical/records/erga, logical/records/mod, logical/records/render, logical/records/store, logical/records/trace-file, logical/views, physical/catalog, physical/collect, physical/conformance, physical/file-source, physical/mod, physical/planctl, physical/source, physical/sources/comments, physical/sources/event-files, physical/sources/githost, physical/sources/issues, physical/sources/markdown, physical/store, physical/world, Intellectual Frontiers Commons, Planning core, Planning Query relations, Planning reconcile, patches and views, The Planning ontology, Findings: the lifecycle, Planning sources and the store, Planning surfaces

Titles, headings, exports, tables, columns and requirements. Esc closes.