Skip to content

Commit f728dc1

Browse files
docs(spec): fold spec-guardian recommendations on req-tg-005 (antigravity) (#2087)
* docs(spec): fold spec-guardian recommendations on req-tg-005 (antigravity) Editorial + defensive fold on the OpenAPM v0.1 Antigravity instruction-rule contract, applying the advisory findings from the apm-spec-guardian 4-panel review of #1984 (issuecomment-4885320041). No new normative statements; count remains 97 (92 MUST, 5 SHOULD). - Section 4.2.1: define the auto-detectable vs explicit-only target taxonomy deterministically (auto-detectable == Registry publishes a detection predicate) and rewrite the `all` expansion to key off it, with a Section 8.4 cross-reference (themes T2, editorial cross-ref). - req-tg-001: generalise the agent-skills-only exclusion to any target without a detection predicate -> not auto-detected, excluded from `all` (covers antigravity in the normative detection home). - req-tg-005: pin a canonical `globs` scalar-vs-sequence representation for deployed-file hash reproducibility (theme T3); redefine the dedup scope from "expected Antigravity rule filenames" to names derived from the resolved instruction primitives (apm.lock.yaml + manifest), closing a fail-open non-suppression gap (theme T4); lowercase the `antigravity` identifier (theme T6); add an editorial note scoping the normative citation of the concrete deploy path (theme T1). - req-tg-002: add `.agents/rules/` to the subdirectory-partition list. - Appendix D: add revision 0.1.11 (no count change). - tests: update the req-tg-005 spec-text guard to the new phrasing. Deferred (out of scope, documented in PR): the req-tg-005 anchor split (T5) and the move-concretes-to-companion refactor (T1/F7) -- both were synthesizer-deferred and mutually conflict with the T3/T4 folds; the editorial note is the panel's own offered alternative. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(spec): fold spec-guardian round-1 recommendations (F1-F4) Apply the four surgical fold-now items from the apm-spec-guardian panel on this PR (avg shocked_meter 8, zero blockers, fold_and_ship). No new normative anchors; count remains 97 (92 MUST, 5 SHOULD). - F1 (T4): hyperlink the editorial-note opening cross-ref to [req-tg-005](#req-tg-005). - F2 (T1): weaken the `globs` canonicalization rationale from "keep ... reproducible" to "reduce sources of divergence" -- the scalar-vs-sequence pin removes one degree of freedom but does not alone guarantee byte-identical output (key order, quoting, indentation remain implementation-defined; a full serialization canon is deferred to v0.1.1). - F3 (T2): define the derivation function inline (name N -> `.agents/rules/N.md`) and establish lockfile `deployed_files` precedence over the manifest for the dedup scope (closes the two-source ambiguity). - F4 (T1): cross-reference [req-lk-012](#req-lk-012), the normative home of the canonical-content hash domain the pin feeds. Deferred to v0.1.1: amendment-discipline guardrail for companion reclassification (T3), explicit flow-sequence ban, collision-boundary note. Deferred to v0.2: oneOf frontmatter schema, companion relocation. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 53f0afd commit f728dc1

2 files changed

Lines changed: 58 additions & 15 deletions

File tree

‎docs/src/content/docs/specs/openapm-v0.1.md‎

Lines changed: 46 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -358,8 +358,13 @@ manifest; it is reserved for the auto-detection fallback described in
358358
[Section 8.4](#84-target-detection-signals-normative). In an
359359
auto-detect context, `minimal` denotes the no-target-detected profile
360360
that emits `AGENTS.md` only; `all` denotes the union of every
361-
registered auto-detectable target and excludes explicit-only targets
362-
such as `agent-skills` and `antigravity`.
361+
registered **auto-detectable** target (see
362+
[Section 8.4](#84-target-detection-signals-normative)). A target is
363+
**auto-detectable** when the OpenAPM Target Registry publishes at
364+
least one detection predicate for it; a target registered without a
365+
detection predicate is **explicit-only** and MUST be selected
366+
explicitly. At v0.1 the explicit-only targets are `agent-skills` and
367+
`antigravity`, so `all` excludes them.
363368

364369
Concrete per-target detection signals and deploy roots are documented
365370
in the non-normative companion **"OpenAPM Target Registry v0.1"**
@@ -1983,10 +1988,13 @@ identifier and for every vendor-registered identifier
19831988
([req-tg-004](#req-tg-004)). Auto-detection MUST activate a target
19841989
**only** when its registered predicate fires; no other filesystem
19851990
signal MAY substitute for, or augment, the registered predicate.
1986-
`agent-skills` MUST NOT be auto-detected; it MUST be selected
1987-
explicitly via `--target agent-skills` or via the manifest's
1988-
`target:` field. When no detection signal fires, the consumer MAY
1989-
fall back to a `minimal` profile that emits `AGENTS.md` only.
1991+
A target registered without a detection predicate
1992+
MUST NOT be auto-detected and MUST be excluded from the expansion of
1993+
`all`; such an **explicit-only** target MUST be selected explicitly
1994+
via `--target <name>` or via the manifest's `target:` field. At v0.1
1995+
the explicit-only targets are `agent-skills` and `antigravity`. When
1996+
no detection signal fires, the consumer MAY fall back to a `minimal`
1997+
profile that emits `AGENTS.md` only.
19901998

19911999
### 8.5 Deploy directory contract (normative)
19922000

@@ -2005,7 +2013,8 @@ defect, not a runtime warning. When two targets register the same
20052013
deploy root (for example two targets that both share `.agents/`),
20062014
each target OWNS only the file-name patterns documented for that
20072015
target in the Registry; `.agents/` is partitioned by subdirectory
2008-
(`.agents/skills/`, `.agents/commands/`, `.agents/prompts/`, ...)
2016+
(`.agents/skills/`, `.agents/commands/`, `.agents/prompts/`,
2017+
`.agents/rules/`, ...)
20092018
so that distinct targets do not contend for the same on-disk
20102019
patterns.
20112020

@@ -2021,15 +2030,39 @@ bundle serves every harness without per-target duplication.
20212030
**[req-tg-005]** A conforming **consumer** implementation that deploys
20222031
target-native per-file instruction rules MUST honour the registered
20232032
rule filename pattern and frontmatter mapping for the active target.
2024-
For the Antigravity target, instruction rules MUST be written under
2033+
For the `antigravity` target, instruction rules MUST be written under
20252034
`.agents/rules/<name>.md`; when the source instruction declares
20262035
`applyTo`, the emitted frontmatter MUST represent it as
2027-
`trigger: glob` plus a `globs` field whose value is either a scalar
2028-
glob or a YAML sequence of glob strings. Compile-time deduplication MUST
2029-
treat only the Antigravity target's expected instruction rule filenames
2030-
as deployed rules; unrelated `.md` files under `.agents/rules/` MUST NOT
2036+
`trigger: glob` plus a `globs` field. To reduce sources of divergence
2037+
in deployed-file content hashes across conforming implementations
2038+
(contributing to the canonical-content equivalence check of
2039+
[req-lk-012](#req-lk-012)), `globs` MUST be
2040+
emitted as a YAML scalar when `applyTo` resolves to exactly one glob
2041+
pattern and as a YAML block sequence when it resolves to two or more
2042+
patterns; when `applyTo` is absent or empty the emitted rule file MUST
2043+
NOT carry a frontmatter block. Compile-time deduplication MUST treat
2044+
only those files whose names derive from the currently-resolved
2045+
instruction primitives (specifically, for each resolved instruction
2046+
primitive of name N the derived filename is `.agents/rules/N.md`; the
2047+
authoritative set is the lockfile `deployed_files` list when a
2048+
lockfile is present, falling back to manifest instruction entries on
2049+
first install) as deployed rules; any other `.md` file under
2050+
`.agents/rules/` MUST NOT be treated as a deployed rule and MUST NOT
20312051
suppress instruction content in `AGENTS.md`.
20322052

2053+
> **Editorial note.** [req-tg-005](#req-tg-005) names the `antigravity` deploy path
2054+
> and frontmatter keys in the normative text rather than delegating
2055+
> them to the non-normative Target Registry companion (contrast
2056+
> [req-tg-002](#req-tg-002)). This is a deliberate, scoped exception:
2057+
> the `antigravity` rules directory shares the `.agents/` root that
2058+
> [req-tg-002](#req-tg-002) partitions, so the deduplication and
2059+
> non-suppression guarantees above require normative precision about
2060+
> the filename derivation. A future revision MAY relocate the concrete
2061+
> `antigravity` filename pattern and frontmatter mapping to the
2062+
> Registry companion once a cross-target instruction-rule schema is
2063+
> registered, retaining only the target-agnostic honour and dedup
2064+
> MUSTs here.
2065+
20332066
### 8.6 Per-target primitive support (informational)
20342067

20352068
The matrix of which primitive types each target supports is
@@ -2977,6 +3010,7 @@ renumbering of conformance classes.
29773010
| 0.1.8 | 2026-06-29 | Normative amendment (semver-zero `0.x` minor) to [req-lk-012]: redefined the `deployed_file_hashes` / `local_deployed_file_hashes` domain from "bytes as written to disk" to the *canonical content* -- UTF-8 text (decodable, no NUL byte) is hashed over its `\r\n` -> `\n` normalized form (a lone `\r` is preserved); binary is hashed raw. This makes the per-deployed-file hash platform-invariant so `apm audit --ci` no longer reports a false `content-integrity` drift when a file is checked out with `\r\n` on Windows (`core.autocrlf=true`) and `\n` on POSIX (apm#1952); it harmonizes `content-integrity` with the drift-replay normalizer. Preserving a bare `\r` keeps the carriage-return smuggling vector hash-visible. [req-lk-017] reworded to re-verify against the [req-lk-012] canonical domain rather than raw on-disk bytes (consistency, not a new obligation). Migration: lockfiles whose hashes were recorded on Windows before this amendment carry `\r\n`-domain hashes; one `apm install` re-records them in the canonical domain. No statement-count change (existing MUST modified, none added); 95 (90 MUST, 5 SHOULD). Subject to the Section 9.3 amendment panel + comment window. |
29783011
| 0.1.9 | 2026-07-04 | Spec-citation fold for network-free lockfile replay (closes the srobroek Mode-B silent-extension gate on the lockfile-seeded resolver cache). Added [req-rs-015] (Section 7.5, consumer MUST): a non-update install (not `apm update` and not `--refresh`/re-resolution) MUST replay a lockfile entry that records a `resolved_commit` by reusing that recorded commit as the resolution result without issuing any network ref-resolution -- no commits-API query, no `git ls-remote`, no clone -- for that entry, PROVIDED drift detection against the manifest reference does not require re-resolution; on drift or under an explicit `apm update`/`--refresh` ([req-rs-011], [req-rs-012]) the consumer MUST re-resolve over the network as usual. The recorded `resolved_commit` is the lockfile's resolution anchor ([req-lk-003]); replaying it is scoped to entries recording a `resolved_commit` WITHOUT a `resolved_tag` (git-literal and untagged-branch entries per [req-rs-003]), leaves content integrity subject to `tree_sha256` ([req-lk-015]) and `resolved_hash` ([req-lk-013]), and defines drift locally as the manifest `ref` no longer being character-equal to the lockfile `resolved_ref`; this makes a warm install of an already-locked reference network-free at the resolution step, extending the reproducible-and-offline resolution guarantee to commit-pinned and branch-tracking entries not covered by the semver-range equivalence of [req-rs-004]. Section 7.11 and Section 11.3.2 Consumer enumerations and Appendix C updated. Statement count: 95 -> 96 (91 MUST, 5 SHOULD). Subject to the Section 9.3 amendment panel + comment window. |
29793012
| 0.1.10 | 2026-07-04 | Spec-citation fold for Antigravity native instruction rules (closes the #1984 Mode-B silent-extension gate). Added [req-tg-005] (Section 8.5, consumer MUST): Antigravity instruction rules are deployed under `.agents/rules/<name>.md`, `applyTo` is rendered as `trigger: glob` plus `globs` (scalar or sequence), and compile-time deduplication only treats expected Antigravity rule filenames as deployed rules so unrelated `.md` files cannot suppress `AGENTS.md` content. Added `antigravity` to the Section 4.2.1 canonical target set and clarified that `all` excludes explicit-only targets. Statement count: 96 -> 97 (92 MUST, 5 SHOULD). |
3013+
| 0.1.11 | 2026-07-09 | Spec-guardian editorial+defensive fold on the Antigravity instruction-rule contract (no new normative statements; statement count remains 97 (92 MUST, 5 SHOULD)). Section 4.2.1: defined the **auto-detectable** vs **explicit-only** target taxonomy deterministically (a target is auto-detectable when the OpenAPM Target Registry publishes at least one detection predicate) and rewrote the `all` expansion to key off it, naming `agent-skills` and `antigravity` as the v0.1 explicit-only set (with a Section 8.4 cross-reference). [req-tg-001] extended: a target registered without a detection predicate MUST NOT be auto-detected and MUST be excluded from `all`, generalising the prior `agent-skills`-only clause to cover `antigravity`. [req-tg-005] extended: pinned a canonical `globs` representation (YAML scalar for exactly one glob, YAML block sequence for two or more, no frontmatter block when `applyTo` is absent) so deployed-file content hashes are reproducible across implementations; redefined the deduplication scope from "expected Antigravity rule filenames" to filenames derived from the currently-resolved instruction primitives recorded in `apm.lock.yaml` and the manifest, closing a fail-open interpretation where an unrelated `.agents/rules/*.md` file could suppress `AGENTS.md` content; lowercased the `antigravity` identifier and added an editorial note scoping the normative citation of the concrete deploy path. [req-tg-002] subdirectory-partition list updated to include `.agents/rules/`. No normative count change. |
29803014

29813015
Errata (none at publication).
29823016

‎tests/spec_conformance/test_manifest_reqs.py‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -380,12 +380,21 @@ def test_consumer_routes_vendor_target_identifiers_to_handlers():
380380

381381
@pytest.mark.req("req-tg-005")
382382
def test_consumer_deploys_antigravity_rules_with_expected_dedup():
383+
# Needles updated for the v0.1.11 spec-guardian fold on req-tg-005:
384+
# the anchor was reworded to (a) lowercase the `antigravity`
385+
# identifier, (b) pin a canonical `globs` scalar-vs-sequence
386+
# representation for hash reproducibility, and (c) redefine the
387+
# deduplication scope to filenames derived from the resolved
388+
# instruction primitives (fail-closed non-suppression). See
389+
# Appendix D revision 0.1.11.
383390
assert_spec_contains(
384-
"For the Antigravity target, instruction rules MUST be written under",
391+
"For the `antigravity` target, instruction rules MUST be written under",
385392
"`.agents/rules/<name>.md`",
386393
"`trigger: glob` plus a `globs` field",
387-
"either a scalar\nglob or a YAML sequence of glob strings",
388-
"unrelated `.md` files under `.agents/rules/` MUST NOT\nsuppress",
394+
"emitted as a YAML scalar when `applyTo` resolves to exactly one glob",
395+
"as a YAML block sequence when it resolves to two or more",
396+
"names derive from the currently-resolved",
397+
"MUST NOT be treated as a deployed rule and MUST NOT",
389398
)
390399

391400

0 commit comments

Comments
 (0)