You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f728dc1
Browse filesBrowse the repository at this point in the historyBrowse 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>
so that distinct targets do not contend for the same on-disk
2010
2019
patterns.
2011
2020
@@ -2021,15 +2030,39 @@ bundle serves every harness without per-target duplication.
2021
2030
**[req-tg-005]** A conforming **consumer** implementation that deploys
2022
2031
target-native per-file instruction rules MUST honour the registered
2023
2032
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
2025
2034
`.agents/rules/<name>.md`; when the source instruction declares
2026
2035
`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
2031
2051
suppress instruction content in `AGENTS.md`.
2032
2052
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
+
2033
2066
### 8.6 Per-target primitive support (informational)
2034
2067
2035
2068
The matrix of which primitive types each target supports is
@@ -2977,6 +3010,7 @@ renumbering of conformance classes.
2977
3010
| 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. |
2978
3011
| 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. |
2979
3012
| 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. |
0 commit comments