Docs/internal assets readme#83
Merged
Merged
Conversation
A diagnostic conversation surfaced that `internal/assets/integrations/` contains TypeScript, Bash, PowerShell, JSON, YAML, and Markdown -- none of it Go source. First read was "internal/ is a dumping ground; lift integrations/ out." Audit of embed.go proved otherwise: every file under integrations/ is captured by an explicit //go:embed directive and shipped inside the ctx binary as raw bytes, then written to the user's filesystem at `ctx setup` time. The smell was real (no contract document existed) but the architectural diagnosis was wrong. Changes: - internal/assets/README.md: new contract document. Audience is contributors, code reviewers, security auditors. Covers: why non-Go code lives under internal/ (Go's import-privacy convention, single-binary distribution model, //go:embed lifecycle); the embed contract (three-clause rule, hard //go:embed no-`../` constraint); directory map with language, consumer, deploy target; current quality gates and four known gaps (TS type-check, shellcheck, PSScriptAnalyzer, skill frontmatter validation); add-asset checklist; negative space (what does not belong here). Complements doc.go rather than replacing it. - .context/DECISIONS.md: record "Embedded foreign-language assets under internal/assets/ are intentional, not a smell" with rationale. Future contributors who feel the same lift-out instinct will find the answer. - .context/TASKS.md: line-30 "add tsc --noEmit" task marked `[-]` skipped with reason; redirected scope produced the README and respawned four discrete Phase 0 gap tasks (TypeScript type-check, shellcheck, PSScriptAnalyzer, skill frontmatter validation). Companion whitespace/ blank-line normalization across the file. - .context/archive/tasks-2026-05-10.md: archive the previously-skipped "Promote 'block-dangerous-commands' to a real ctx system Go subcommand" task (decision recorded 2026-04-26-231517; the promotion is permanently off the table). - internal/assets/context/CONSTITUTION.md (embedded template): add new Process Invariant: never push code; the human is the final authoritative decision maker; refuse to push even when explicitly asked. - specs/internal-assets-readme.md: spec document for the README work, per the project's spec-trailer convention. Spec: specs/internal-assets-readme.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.