Repository navigation
docs: changelog-agent - Document specification decisions #3470
Description
Part of #3464.
Design decisions in .github/specs/016-changelog-agent-quality/ raised by CodeRabbit on #3434. They need an owner decision before code changes.
- CLI contract (
contracts/cli-interface.md) does not match the shipped validator (.github/validation/changelog/): required path,--output-format,csv,--strict,--max-entries, exit codes. Implement an adapter or document the existing interface. - REST interface (
contracts/rest-api-interface.md): define path confinement forchangelog_pathand merge targets. - Data model: line numbers used as immutable IDs; use a stable hash and treat line number as location.
-
plan.mdis still the template. - Skill model:
metadata.ymlvsSKILL.md(resolved by task: conform all skills to the Agent Skills SKILL.md spec #3467). - Lock files: stale
.changelog.lockafter a crash; add owner metadata and stale recovery or an OS lock. - Merge must block until validation completes; the research design allows validation without a lock.
-
package-json-validator.jsandstructure-checker.jsenforce different rules; centralise (overlaps task: revise spec 014 to AGENTS.md, *.agent.md frontmatter and SKILL.md #3466). - Registry validation (T064) checks two fields only; validate against
contracts/registry-schema.jsonand fail the phase on errors.
Metadata
Metadata
Assignees
Type
Fields
Priority
None yet
Activity
linear-code commentedon Sep 23, 2026
LS-4235
eleshar commentedon Sep 23, 2026
Status update: a
coderabbitai[bot]commit (334c1d1, 2026-09-23 05:50 UTC) on #3434 rewrote the spec 016 contracts and docs ("align changelog specifications with the shipped CLI, locking protocol and repository path boundaries"):contracts/cli-interface.md,contracts/rest-api-interface.md,data-model.md,plan.md,quickstart.md,research.md,spec.md, plusregistry-schema.jsonand a schema validator for T064.These are design decisions written by a bot. They now sit in #3434 and need an owner read before they are treated as agreed. Please review each checklist item above against that commit and tick the ones you accept.
eleshar commentedon Sep 23, 2026
Status after 447ed24 on #3434, rechecked against the branch:
validate.js --helpoptions, defaults, exit codes,GITHUB_TOKENfallback).changelog_pathand server-resolved merge targets.plan.mdis concrete (no template markers).SKILL.mdfrontmatter across research, spec, data model and quickstart.PackageJsonValidator.contracts/registry-schema.json; phase fails on errors.changelog_pathandchangelog_contentbe mutually exclusive (CodeRabbit:oneOf, exactly one), or ischangelog_pathalways required withchangelog_contentas an optional inline override? The text currently says path is required and content is optional.docs: define changelog_path and changelog_content in the REST contract (
eleshar commentedon Sep 23, 2026
Last item resolved in b29c26b on #3434 (decided 2026-09-23):
changelog_pathis always required and confined;changelog_contentis an optional inline body that is validated instead of the file on disk; the validate endpoint never writes, and merge operates only on its own confinedchangelog_path. All items are now done; this issue closes when #3434 merges.docs(specs): sync 014 and 016 with the agreed #3434 head (b29c26b)
docs: fix the MD022 failure the specification lint caught (#3500)
docs: specs - land CI remediation, changelog agent and agent consolid…
refactor: changelog-agent - establish quality framework and spec 015 …
[-]task: resolve spec 016 changelog-agent design findings[/-][+]docs: changelog-agent - Document specification decisions[/+]