Skip to content

docs(knowledge): reconcile zsh-lint parser guidance with f1c43fa (#803) - #804

Merged
ss-o merged 1 commit into
mainfrom
feature-803-parser-guidance
Oct 16, 2026
Merged

ss-o merged 1 commit into
mainfrom
feature-803-parser-guidance

Conversation

@ss-o

@ss-o ss-o commented Oct 16, 2026 •

Copy link
Copy Markdown
Member

Summary

  • Reconcile knowledge/domains/tooling/zsh-lint-parser-front-end.md against tested zsh-lint commit f1c43fac9c8eadfc914a4af89a1beea11afca891 (zsh-lint PR 699): the reconciled project revision and the contract link now name that commit, and the import-prefix sentence links ADR-0041. Frontmatter, selectors, rules, paths and examples are unchanged.
  • Update the sentence in knowledge/domains/tooling/index.md that names each source's project revision: Go AST stays at 7ff05091, parser front end moves to f1c43fac. The rest of that file's diff is Prettier padding of its existing task table, which was unformatted on main and is required once the file is touched; no cell text changed.
  • This is the first of the two organization changes in [docs]: reconcile zsh-lint parser guidance for installable packaging #803. No delivery record changes here, so no project consumer regenerates; the approved record in knowledge/project-delivery.json still pins 21693189 and is updated in the follow-up change.

Refs #803

Impact review

  1. Classification: scoped project guidance (a complete project-native instruction source), not shared policy, runtime behavior or enforcement.
  2. Consumers: z-shell/zsh-lint's .github/instructions/parser-front-end.instructions.md, through the approved project delivery record; the change-impact report selects only z-shell/zsh-lint. The tooling index is organization navigation with no generated consumer.
  3. Owner: unchanged; this source stays the editable owner and the project consumer stays generated.
  4. Duplication or contradiction: none added. The same index paragraph still ends with a pre-existing sentence saying no project delivery record is active for these sources, which has been inaccurate since PR 721; it is outside this change and is left for the follow-up.
  5. Manifests: no route changes in either manifest.
  6. Runtime delivery: unchanged mechanism; the project receives the content only after the record update and its own regeneration.
  7. Generation and size: knowledge-delivery.py --check passes for 57 consumers; no generated file changes.

Verification

  • Every path, command and symbol the source names exists at f1c43fac, including adapterChain, parseWithAdapters and parseTree in internal/parse/adapter_chain.go, the File metadata methods, the fork's RepeatClause, internal/manualcite, cmd/zsh-lint-survey, the fixture directories and third_party/mvdan-sh/FORK.md. The Bump crowdin/github-action from 2.0.0 to 2.1.1 #287 placement note is still in section 3 of the contract.
  • A render preview with project_revision set to f1c43fac rewrites the contract link to ../../docs/project/parser-gap-workflow.md, which resolves from the consumer path in that tree; organization links become immutable revision links.
  • knowledge-delivery.py --check, knowledge-coverage.py, validate-agent-policy.py, org-routing.py validate and org-routing.py verify-approved (with the agent-skills source root) pass. verify-approved checks the unchanged approved record, not the new source revision.
  • 339 unit tests pass: knowledge coverage 7, delivery 14, decision records 17, agent policy 99, routing and policy report 91, Zsh standard policy 111.
  • git diff --check and trunk check --no-fix --ci on both files pass.

Agent handoff

Point the parser front-end source's reconciled project revision and
contract link at tested zsh-lint commit f1c43fa, which packages the
parser fork inside the root module, and link ADR-0041 where the import
prefix is explained. Every path, command and symbol the source names
exists at that commit; rules, selectors and frontmatter are unchanged.

Update the tooling index sentence that names each source's project
revision. Prettier pads that page's task table, which the touched file
must satisfy.

Refs #803
@ss-o
ss-o requested a review from a team as a code owner October 16, 2026 22:01
@ss-o ss-o added type:docs Documentation-only work. area:docs Documentation systems, content, or publishing. labels Oct 16, 2026
@ss-o ss-o self-assigned this Oct 16, 2026
@ss-o ss-o moved this to In Review in Z-shell Delivery Oct 16, 2026

@ss-o ss-o left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fallback review under ADR-0026: maintainer elected after the Copilot request did not register, on 149c199

Findings

No actionable findings in the two-file diff against main 2ddeb0e (merge base equal to base).

Note

This is an author-side review of record, not independent human approval. It does not approve the project delivery record update or the zsh-lint consumer refresh, which follow separately under #803.

Checklist verdicts

  • Scope: pass. The parser front-end source changes only its reconciled project revision, its contract link and one added ADR-0041 link. Frontmatter, the applyTo selector, rules, paths and examples are byte-identical. The tooling index changes one sentence; its other lines differ only by Prettier table padding, with identical cell text after whitespace normalization.
  • Accuracy against the tested project: pass. At zsh-lint f1c43fac9c8eadfc914a4af89a1beea11afca891, every path and symbol the source names exists, including adapterChain, parseWithAdapters and parseTree in internal/parse/adapter_chain.go, the File metadata methods, the fork's RepeatClause, internal/manualcite, cmd/zsh-lint-survey, both fixture directories and third_party/mvdan-sh/FORK.md. The contract link target exists at that commit (blob 983560749db7aa4004d168095fca09c818bf0b37), and the #287 placement note is still in its section 3. The fork's import prefix and FORK.md packaging text match ADR-0041.
  • Delivery compatibility: pass. A render with project_revision set to f1c43fac rewrites the contract link to ../../docs/project/parser-gap-workflow.md, which resolves from the consumer path, and the ADR links become immutable organization revision links. The approved record is unchanged, so no consumer regenerates and verify-approved still passes against revision 2169318.
  • Links and accessibility: pass. The new relative link resolves from knowledge/domains/tooling/ to decisions/0041-zsh-lint-parser-root-module-packaging.md; the link text names the decision, matching the existing ADR links. The links check passes.
  • Verification: pass. Knowledge delivery, coverage, agent policy, routing validation and approved-revision verification pass locally, with 339 unit tests. git diff --check and Trunk pass on both files. All 12 hosted checks pass on this head, and the commit signature is verified.

Limits and follow-up

The index paragraph's last sentence, saying no project delivery record is active for these sources, has been inaccurate since PR 721; it predates this change and is disclosed in the PR body for the follow-up. The Go AST source stays reconciled against 7ff05091 by design. Runtime discovery of the regenerated consumer is not exercised here. Review threads and comments were checked before publication; there are none.

@ss-o
ss-o merged commit f7ec572 into main Oct 16, 2026
12 checks passed
@ss-o
ss-o deleted the feature-803-parser-guidance branch October 16, 2026 22:04
@github-project-automation github-project-automation Bot moved this from In Review to Done in Z-shell Delivery Oct 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:docs Documentation systems, content, or publishing. type:docs Documentation-only work.

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant