Skip to content
internal/ownership
Updated
On this page

Deciding whether a generated page's frontmatter description is a machine placeholder selfdoc may overwrite, or handwritten text it must never touch.

#internal/ownership

#internal/ownership

Package ownership decides whether a generated page's frontmatter description is machine-owned -- a placeholder selfdoc emitted and may freely overwrite -- or handwritten, and must never be overwritten.

The guiding principle: descriptions are handwritten; machine text is only ever a placeholder. The critical property is the INVERSE -- handwritten text must NEVER be classified machine-owned. The other direction is acceptable: legacy machine residue occasionally reads as handwritten when no seed hash was ever recorded for it, and the next gen reseeds it, since a release always runs gen before check.

Ownership is decided per page kind:

- module pages: the current or the historical instantiated template for that module, or the recorded seed hash. - the generated API index: the current or a legacy index template, or the recorded seed hash. - CLI pages: a live recompute from the dumped schema (which covers the truncated-prefix family no static set can), or the recorded seed hash.

The seed hash is the SHA-256 of the machine-emitted description TEXT, recorded per page by gen in the staleness store. An unrecorded seed hash is the empty string.

#ModuleDescTemplate

Go go
const ModuleDescTemplate = "API reference for the {module} module — " +

ModuleDescTemplate is the current auto-generated description of a module reference page, with "{module}" standing for the module's name.

The predicate compares a description against this text for equality, so every character of it -- the em dash included -- is part of the contract: a changed byte turns every page carrying the old text into handwritten prose that gen may no longer reseed.

#HistoricalModuleDescTemplate

Go go
const HistoricalModuleDescTemplate = "Documentation for {module}"

HistoricalModuleDescTemplate is the module page description a pre-current-template selfdoc emitted. It is still recognized, so that residue is reseeded rather than frozen as if a person had written it.

#LegacyIndexDescriptions

Go go
var LegacyIndexDescriptions = []string{

LegacyIndexDescriptions are the machine-seeded generated-index descriptions produced by selfdoc versions that recorded no seed hash.

They hardcode "selfdoc" and so are wrong for every consuming project; they are treated as machine residue and reseeded.

#NormalizeDescription

Go go
func NormalizeDescription(value any) string

NormalizeDescription strips surrounding whitespace and one layer of matching quotes, so a description written as 'x' or "x" in frontmatter compares equal to the same text written bare.

#DescriptionSeedHash

Go go
func DescriptionSeedHash(value any) string

DescriptionSeedHash is the SHA-256 of a normalized machine-emitted description string. It is what gen records per page, and what the predicates below compare a page's current text against.

#IsMachineOwnedModuleDescription

Go go
func IsMachineOwnedModuleDescription(value any, moduleName, seedHash string) bool

IsMachineOwnedModuleDescription reports whether value is machine-owned for a module page documenting moduleName.

An empty moduleName means the page carries no title to instantiate the templates with, so only the recorded seed hash can answer.

#IsMachineOwnedIndexDescription

Go go
func IsMachineOwnedIndexDescription(value any, seedHash string) bool

IsMachineOwnedIndexDescription reports whether value is a machine-owned description of the generated API index page.

#IsMachineOwnedCLIDescription

Go go
func IsMachineOwnedCLIDescription(

IsMachineOwnedCLIDescription reports whether value is a machine-owned description of a CLI page.

CLI machine text is derivable from the dumped schema, so beyond the recorded seed hash this is a live recompute: no static set can cover the family of truncated defaults earlier selfdoc versions wrote.

#IsMachineOwned

Go go
func IsMachineOwned(

IsMachineOwned classifies a page's description as machine-owned (true) or handwritten (false).

relPath selects the page kind by its filename; frontmatter supplies the description, and the title for a module page. seedHash is the page's recorded seed hash from the staleness store, "" when none was recorded. cliStructure is the parsed dumped schema, needed to look up a CLI command's help text; pass nil for a project that is not strictcli-based.

Handwritten text is never classified machine-owned. Only a page declaring generated: true can be machine-owned at all, so a hand-authored page always answers false and keeps its full staleness protection.

More tools from this site

  • claudestream Drive Claude Code from Python: run it as a subprocess and read its output as typed events, with async and sync sessions, sandbox policies, and tools you define in Python
  • claudewheel A TUI Claude Code Launcher that lets you have more than one profile, manage sessions lifecycle, pick the exact CC version, model to use (even older unlisted ones), pick which GitHub account to use, etc.
  • dirstat Fast, single-binary directory statistics CLI: every file under a tree grouped by format, with counts, sizes, and lines of code, as a colored terminal table or as JSON
  • fastware A batteries-included ASGI framework: msgspec JSON, a managed Granian server, dependency injection, SSE, WebSockets, auth, and a test client
  • go-toml-edit Zero-dep TOML editing library for Go with comment preservation
  • howmuchleft The fastest Claude Code statusline: context window, 5-hour, and weekly limit usage as three customizable gradient bars, rendering in about 6 ms
  • orxtra
  • pgdesign
  • predraw Declarative rendering pipeline: describe a scene in JSON and get SVG, PNG and WebP out, with light and dark style tokens, reusable components and text converted to path outlines
  • reposummary Turn a git repository's history into a Markdown journal: pick a time window or revision range and get a readable digest of what changed, optionally narrated by an LLM
  • rlsbl Release orchestration and project scaffolding CLI that bumps versions, validates a structured JSONL changelog, tags only the commit CI verified, and publishes to npm, PyPI, Go and more
  • safegit git wrapper CLI that gives each commit its own temporary index and retries ref updates on conflict, so concurrent agents share one repository
  • saferm Command-line replacement for rm that archives every deletion with a mandatory reason and the context it ran in, so deleted files can be listed, inspected and restored
  • strictcli
  • stricttest An always-on test-isolation floor: a pytest plugin and a Go env-hygiene module that make a test suite structurally unable to reach real credentials, the real HOME, the network, or the development repository.
  • wesktop A Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview
Search