Repository navigation
spike(framework): validate a portable project-policy boundary #585
Description
Question
What portable project-policy boundary, if any, lets a team version genuinely shared AI-development policy without colliding with CLI-managed state or a specific host?
Why this must be investigated first
.aidd/ already contains CLI-managed auth, manifests, and caches. aidd clean --force currently removes the whole directory. The previous proposal assumed .aidd/config.yml, YAML, precedence, and a broad schema before proving the consumers or a safe ownership boundary.
Scope
- Map the lifecycle and ownership of existing project state, including clean, ignore, secrets, and generated files.
- Establish at least two independent, live policy consumers that cannot be served by existing project documentation, rules, or host configuration.
- Compare candidate locations and formats against portability, team review, lifecycle safety, and host neutrality.
- Decide whether a shared policy artifact is warranted; if so, recommend its narrowest first contract and migration safeguards.
Evidence of completion
- A written decision records the candidate consumers, alternatives considered, and rejected options.
- The chosen boundary is not deleted by normal CLI cleanup and cannot expose credentials through normal version control.
- Any required correction to the stale
config.ymldocumentation is identified with an owner. - The result names follow-up delivery work only when the evidence justifies it.
Out of scope
- Implementing a parser, schema, generator, precedence cascade, or consumers.
- Choosing YAML in advance.
- Migrating existing runtime configuration or secrets.
Activity
docs(framework): plan a telemetry v1 that ships in a week
blafourcade commentedon Aug 18, 2026
Telemetry needs a project-level switch — "is AIDD allowed to measure this project" — read by the CLI, by skills, and by a bundled hook. It lands in
.aidd/rather than inventing a home, which is what this issue specifies.One deviation, and it is a constraint rather than a preference: it has to be
config.json, notconfig.yml.The journal hook (
plugins/aidd-telemetry/hooks/) ships with zero dependencies and cannot acquire any —aidd framework buildcopieshooks/verbatim into every user project with no install step. It canJSON.parse; it cannot parse YAML without something to parse it with. The CLI has no YAML parser either today.So the rule this issue draws — YAML is human policy, JSON is machine/runtime — puts the telemetry switch on the JSON side by its own logic: it is read at runtime, by a dependency-free script, on every session start. This issue already anticipates the case with its "optional later:
config.jsonfallback".What that leaves for this issue to decide, and it is worth deciding rather than discovering: whether a project ends up with both files. Two config files in
.aidd/is the duplication this issue exists to prevent, so eitherconfig.ymlowns human policy andconfig.jsonowns anything a hook reads — with the boundary written down — or one format serves both and YAML loses on the dependency argument.Plan carrying the telemetry side:
aidd_docs/tasks/2026_08/2026_08_20_telemetry-export-enable/phase-1.md. Related: #646, #620.blafourcade commentedon Aug 18, 2026
Confirmed with the maintainer:
config.json, notconfig.yml.The reason is a constraint rather than a preference, and it now applies to more than telemetry. Anything a bundled hook must read has to be parseable with no dependency at all —
aidd framework buildcopieshooks/verbatim into every user project with no install step, and the CLI ships no YAML parser either.JSON.parseis available everywhere and to everyone; YAML is not.So the split this issue drew — YAML for human policy, JSON for machine and runtime — collapses in practice, because the same keys are read by both audiences: a human decides whether telemetry is on, and a dependency-free hook reads that decision on every session start.
One format,
.aidd/config.json, committed. It keeps everything else this issue specifies: the project config root, host-neutral, no secrets, a precedence order, and a key-ownership map that prevents duplication with the orchestrator JSON.What is lost is comments, which is a real loss for a policy file people review. Worth deciding here whether that is answered by a documented schema plus a commented starter template, or whether it needs something else.
docs(cli): the telemetry switch belongs in .aidd/, not in aidd_docs/
docs(framework): plan a telemetry v1 that ships in a week
docs(cli): the telemetry switch belongs in .aidd/, not in aidd_docs/
feat(framework): measurement that works on five tools, each proven by…
[-]feat(framework): .aidd/ project config root (YAML policy, multi-tool)[/-][+]spike(framework): validate a portable project-policy boundary[/+]blafourcade commentedon Sep 9, 2026
Changed to a Spike.
.aidd/is CLI-managed andaidd clean --forceremoves it, so the need and safe location must be proven before adding project configuration.